/** * `wait-for` 的行为测试。 * * 这个工具存在的唯一理由是「agent 敢把一个长等待交给它,而不是回去自己写轮询」。 * 所以这里断言的不是"它能等",而是它在每一种收尾下**都给出足以继续决策的输出**: * 达成和超时要能区分(0 / 124),超时也要带上日志尾巴,probe 自己坏掉不能被当成 * "条件没达成"。少了任何一条,agent 都会退回去一格一格地 poll —— 那正是它要消灭的。 * * 用真进程跑,不 mock:被测的东西就是子进程、退出码和超时,mock 掉就什么也没测。 * 每个用例都钉在秒级,整支跑完 ~6s。 */ import { describe, expect, test, beforeAll, afterAll } from "bun:test"; import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import path from "node:path"; import { ensureWaitBlockInPrompt, waitPromptBlock } from "@bbbug/shared/wait_prompt"; const BIN = path.resolve(import.meta.dir, "../../bin/wait-for.ts"); let dir = ""; beforeAll(() => { dir = mkdtempSync(path.join(tmpdir(), "waitfor-")); }); afterAll(() => { rmSync(dir, { recursive: true, force: true }); }); async function run(args: string[]): Promise<{ code: number; out: string }> { const p = Bun.spawn([process.execPath, BIN, ...args], { stdout: "pipe", stderr: "pipe" }); const [out, err] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]); return { code: await p.exited, out: out + err }; } describe("wait-for", () => { test("--until 条件立刻成立时秒退,退出码 0", async () => { const t0 = Date.now(); const r = await run(["--until", "true", "--timeout", "10s"]); expect(r.code).toBe(0); expect(r.out).toContain("条件达成"); // 首分钟走 3s 快探,但第一次探测是立即的 —— 不该先睡一觉再看。 expect(Date.now() - t0).toBeLessThan(3000); }); test("条件一直不成立 → 退出码 124,且明说这不等于失败", async () => { const r = await run(["--until", "false", "--timeout", "2s", "--interval", "1s", "--quiet"]); expect(r.code).toBe(124); expect(r.out).toContain("未达成"); // 这句是防「等超时了就写成环境阻塞」的护栏,比退出码更要紧。 expect(r.out).toContain("环境阻塞"); }); test("--file 等文件出现:先不在,中途落下来", async () => { const f = path.join(dir, "late.txt"); setTimeout(() => writeFileSync(f, "done\n"), 1200); const r = await run(["--file", f, "--timeout", "15s", "--quiet"]); expect(r.code).toBe(0); }, 20_000); test("--file + --match:文件在但内容没命中时继续等", async () => { const f = path.join(dir, "log.txt"); writeFileSync(f, "building…\n"); setTimeout(() => writeFileSync(f, "building…\npull success\n"), 1200); const r = await run(["--file", f, "--match", "pull success", "--timeout", "15s", "--quiet"]); expect(r.code).toBe(0); }, 20_000); test("--tail 在达成时把日志尾巴一起打出来(省掉紧随其后的那次 tail 调用)", async () => { const f = path.join(dir, "build.log"); writeFileSync(f, ["a", "b", "BUILD SUCCEEDED"].join("\n") + "\n"); const r = await run(["--until", "true", "--tail", f, "--tail-lines", "2", "--quiet"]); expect(r.code).toBe(0); expect(r.out).toContain("BUILD SUCCEEDED"); expect(r.out).not.toContain("\na\n"); // 只要末 2 行 }); test("超时同样带日志尾巴 —— 超时那一刻恰恰最需要看日志", async () => { const f = path.join(dir, "stuck.log"); writeFileSync(f, "linking…\n"); const r = await run(["--until", "false", "--timeout", "2s", "--tail", f, "--quiet"]); expect(r.code).toBe(124); expect(r.out).toContain("linking…"); }); test("--pgrep:没有匹配进程时立刻达成", async () => { const r = await run(["--pgrep", "zzz-no-such-process-zzz", "--timeout", "5s", "--quiet"]); expect(r.code).toBe(0); }); test("--while:probe 退出 0 表示还在跑,非 0 才算完", async () => { const f = path.join(dir, "flag"); writeFileSync(f, "x"); setTimeout(() => rmSync(f, { force: true }), 1200); const r = await run(["--while", `test -f ${f}`, "--timeout", "15s", "--quiet"]); expect(r.code).toBe(0); }, 20_000); test("probe 是个不存在的命令:sh 返回 127 = 条件未达成,不能被当成达成", async () => { // sh 对未知命令返回 127(非 0)= 条件未达成,不是 probe 故障;真正的故障是 probe 卡死。 // 这里断言它没有把 127 误判成「达成」。 const r = await run(["--until", "definitely-not-a-command-xyz", "--timeout", "2s", "--quiet"]); expect(r.code).toBe(124); }, 15_000); test("probe 自己卡死不会卡住整个等待:单次 probe 有独立上限", async () => { const t0 = Date.now(); // probe 每次都要睡 30s,--probe-timeout 必须把它掐断,否则整体会被拖到 30s 以上。 const r = await run(["--until", "sleep 30", "--timeout", "3s", "--probe-timeout", "500ms", "--quiet"]); expect(r.code).toBe(124); expect(Date.now() - t0).toBeLessThan(15_000); }, 25_000); test("互斥与必填:没给条件、或给了两个,都是用法错(2)", async () => { expect((await run(["--timeout", "5s"])).code).toBe(2); expect((await run(["--until", "true", "--file", "/tmp/x"])).code).toBe(2); }); test("时长写错要当场报错,不能按默认值静悄悄跑 30 分钟", async () => { const r = await run(["--until", "true", "--timeout", "45minutes"]); expect(r.code).toBe(2); expect(r.out).toContain("--timeout"); }); // ── --run:起一个长命令并等它跑完 ─────────────────────────────────────── // 这一组盯的是「不谎报成败」。语料里的构建壳有五种写法,搓错一次白烧 25 分钟, // 所以退出码必须是真的,超时必须不杀命令。 test("--run 跑完并报出真实退出码 0", async () => { const r = await run(["--run", "echo hello; echo world", "--timeout", "20s", "--quiet"]); expect(r.code).toBe(0); expect(r.out).toContain("退出码 0"); expect(r.out).toContain("world"); // 日志尾巴自带,不用再发一次 tail }, 30_000); test("命令里的 exit N 必须原样报出来,不能变成「拿不到退出码」", async () => { // 曾经的真 bug:用 `{ cmd; }` 包,命令里的 `exit 7` 把整个 shell 退掉, // 写退出码那一句永远跑不到 —— 每一次失败都被报成「拿不到」。 const r = await run(["--run", "echo building; exit 7", "--timeout", "20s", "--quiet"]); expect(r.code).toBe(1); expect(r.out).toContain("退出码 7"); expect(r.out).not.toContain("拿不到退出码"); }, 30_000); test("日志里出现 error: 但命令成功时,不能报成失败", async () => { // 构建日志里出现 "error:" 太常见(警告、第三方输出)。靠 grep 猜成败会把 // 成功的构建报成失败,更糟的是反过来。所以只认退出码。 const r = await run(["--run", "echo 'note: error: deprecated API'; exit 0", "--timeout", "20s", "--quiet"]); expect(r.code).toBe(0); expect(r.out).toContain("退出码 0"); }, 30_000); test("--log 指定日志路径,并把 stderr 也收进去", async () => { const f = path.join(dir, "build-r2.log"); const r = await run(["--run", "echo out; echo err 1>&2", "--log", f, "--timeout", "20s", "--quiet"]); expect(r.code).toBe(0); const body = readFileSync(f, "utf8"); expect(body).toContain("out"); expect(body).toContain("err"); }, 30_000); test("超时不杀命令,并给出续等的现成命令", async () => { const f = path.join(dir, "slow.log"); const r = await run(["--run", "sleep 20; echo finished", "--log", f, "--timeout", "2s", "--quiet"]); expect(r.code).toBe(124); expect(r.out).toContain("没有杀它"); expect(r.out).toContain("--pid "); // 续等命令 // 真的还活着:等它自己跑完,日志里应当出现结果 await new Promise((res) => setTimeout(res, 22_000)); expect(readFileSync(f, "utf8")).toContain("finished"); }, 45_000); test("--run 与其它条件互斥", async () => { expect((await run(["--run", "true", "--until", "true"])).code).toBe(2); }); test("--label 出现在输出里,便于在会话日志里认出在等什么", async () => { const r = await run(["--until", "true", "--label", "iOS clean build", "--quiet"]); expect(r.out).toContain("[iOS clean build]"); }); }); /** * 这一组测的不是工具,是「改了默认就真的生效」。 * * 生产跑的是 agent_prompts 里 active 指向的模板版本,那些版本是在这个小节存在 * 之前存的,里面没有 {{waitBlock}} 占位符。只改内置默认的话,工具部署到每台节点、 * 而没有一个 agent 被告知它存在 —— 看起来上线了,实际什么也没发生。 * ensureWaitBlockInPrompt 就是堵这个洞的,与 ensureDeviceBlockInPrompt / * ensureKbInPrompt 同一套做法。 */ describe("ensureWaitBlockInPrompt", () => { const BLOCK = "## 等构建 / 拉包 / 部署 —— 不要自己写轮询循环\n\n用 wait-for。\n\n"; test("老模板没有占位符 → 仍然把小节插进去", () => { const old = "## 步骤 2 — 判断本批是否接着上一批修\n略。\n\n## 步骤 3 — 复现、修复、验证\n正文。\n"; const out = ensureWaitBlockInPrompt(old, BLOCK); expect(out).toContain("## 等构建 / 拉包 / 部署"); // 插在「步骤 3」之前 —— agent 正要开始构建的位置 expect(out.indexOf("## 等构建")).toBeLessThan(out.indexOf("## 步骤 3")); expect(out).toContain("## 步骤 2"); }); test("模板已有这一小节 → 不重复插第二份", () => { const already = `前言\n\n${BLOCK}## 步骤 3 — 复现\n正文\n`; const out = ensureWaitBlockInPrompt(already, BLOCK); expect(out).toBe(already); expect(out.split("## 等构建").length - 1).toBe(1); }); test("人工改过措辞也算已有,不覆盖别人的编辑", () => { const edited = "## 等构建 / 拉包 / 部署(本节点特调)\n只准用 wait-for。\n\n## 步骤 3 — 复现\n"; expect(ensureWaitBlockInPrompt(edited, BLOCK)).toBe(edited); }); test("security 模板的锚点是「运行规则」", () => { const sec = "前言\n\n## 运行规则\n- 按 SecuritySpec 走\n"; const out = ensureWaitBlockInPrompt(sec, BLOCK); expect(out.indexOf("## 等构建")).toBeLessThan(out.indexOf("## 运行规则")); }); test("英文模板走英文锚点", () => { const en = "Intro\n\n## Step 3 — implement and verify\nbody\n"; const out = ensureWaitBlockInPrompt(en, BLOCK); expect(out.indexOf("## 等构建")).toBeLessThan(out.indexOf("## Step 3")); }); test("模板被改得认不出锚点 → 追加到末尾,而不是丢掉", () => { const weird = "完全自定义的模板正文,没有任何标准小标题。\n"; const out = ensureWaitBlockInPrompt(weird, BLOCK); expect(out).toContain("## 等构建 / 拉包 / 部署"); expect(out.startsWith("完全自定义")).toBe(true); }); test("block 为空时什么都不做", () => { const t = "## 步骤 3 — 复现\n"; expect(ensureWaitBlockInPrompt(t, "")).toBe(t); }); // 上面几条用的是手写的小节,标题恰好是旧标记 —— 所以真实小节的标题和标记对不上时 // 没有一条测试会红,线上每份执行 prompt 都被插了第二份(09-14 → 10-02)。这里用真实生成的小节。 test.each(["zh", "en"] as const)("真实生成的小节(%s)已在 prompt 里 → 不插第二份", (lang) => { const real = waitPromptBlock({ cmd: "bun satellite.js wait-for", lang }); const step3 = lang === "zh" ? "## 步骤 3 — 复现、修复、验证\n" : "## Step 3 — reproduce, fix, verify\n"; const rendered = `前言\n\n${real}${step3}正文\n`; expect(ensureWaitBlockInPrompt(rendered, real)).toBe(rendered); }); }); /** * 失败时打更多日志 —— 上线首日的实测反馈。 * * 2026-09-15,上线后 19 个执行轮里有 25 次调用是在 wait-for 之后**再去读它自己那份 * 日志**(`tail -c 4000 "$L"`、`grep -i "no space|Internal compiler error"`、 * `sed -n '30,90p'`)。「省掉紧随其后那次 tail」是这个工具的卖点之一,而它恰恰在 * 最需要的时候(构建挂了)没兑现:默认 20 行里通常只有收尾噪音,真正的报错在更上面。 */ describe("失败时的日志行数", () => { const manyLines = (n: number) => Array.from({ length: n }, (_, i) => `line-${i + 1}`).join("\n") + "\n"; test("成功时仍然只打 20 行 —— 成功不需要翻历史", async () => { const f = path.join(dir, "ok.log"); writeFileSync(f, manyLines(200)); const r = await run(["--until", "true", "--tail", f, "--quiet"]); expect(r.out).toContain("line-200"); expect(r.out).toContain("line-181"); expect(r.out).not.toContain("line-180"); // 第 21 行往上不打 }, 20_000); test("命令失败时自动打到 80 行", async () => { // 输入和 --log 必须是两个文件:让命令 cat 自己的日志会边读边写,永不结束。 const src = path.join(dir, "fail-src.txt"); const log = path.join(dir, "fail.log"); writeFileSync(src, manyLines(200)); const r = await run(["--run", `cat ${src}; exit 2`, "--log", log, "--quiet"]); expect(r.code).toBe(1); expect(r.out).toContain("退出码 2"); expect(r.out).toContain("末 80 行"); expect(r.out).toContain("line-121"); // 末 80 行的第一行 expect(r.out).not.toContain("line-120"); }, 30_000); test("超时时也打 80 行 —— 超时那一刻最需要看日志", async () => { const f = path.join(dir, "slowfail.log"); writeFileSync(f, manyLines(200)); const r = await run(["--until", "false", "--timeout", "2s", "--tail", f, "--quiet"]); expect(r.code).toBe(124); expect(r.out).toContain("line-121"); // 末 80 行的第一行 expect(r.out).not.toContain("line-120"); }, 20_000); test("显式传了 --tail-lines 就一律听用户的,失败时也不擅自加码", async () => { const f = path.join(dir, "explicit.log"); writeFileSync(f, manyLines(200)); const r = await run(["--until", "false", "--timeout", "2s", "--tail", f, "--tail-lines", "5", "--quiet"]); expect(r.code).toBe(124); expect(r.out).toContain("line-196"); expect(r.out).not.toContain("line-195"); }, 20_000); }); /** * 设备 UI 状态的边界 —— 上线三天后量出来的误用。 * * 66 个执行轮里 33 次超时、烧掉 4.4 小时,清一色是拿 --until 等设备 UI: * `catuse apps | grep -q TikTokBase`、`dumpsys window | grep -q mCurrentFocus`、 * `uiautomator dump | grep -q …`,超时值 3–8 分钟(UI 尺度,不是构建尺度)。 * * 构建有确定的终点,UI 状态没有。把可观察的轮询换成盲等,在这个场景下是净损失。 * 所以:**警告,不拦截** —— 拦截会把 agent 逼去找绕过写法。 */ describe("等设备 UI 状态时要警告", () => { const DEVICE_PROBES = [ "catuse apps 2>/dev/null | grep -q TikTokBase", 'adb shell dumpsys window | grep -q "mCurrentFocus=Window.*musically"', 'adb shell "uiautomator dump /sdcard/b2.xml >/dev/null; grep -q Profile /sdcard/b2.xml"', ]; for (const probe of DEVICE_PROBES) { test(`--until 等 UI 状态会警告: ${probe.slice(0, 34)}…`, async () => { const r = await run(["--until", probe, "--timeout", "2s", "--quiet"]); expect(r.code).toBe(124); expect(r.out).toContain("设备 UI 状态"); expect(r.out).toContain("catuse ui"); // 超时时再说一次,而且是针对性的:别调大 timeout 重来 expect(r.out).toContain("再等下去多半也不会变"); expect(r.out).not.toContain("调大 --timeout;"); // 通用那句不该出现 }, 20_000); } test("构建类 probe 不触发警告 —— 别把正常用法也吵一遍", async () => { const r = await run(["--until", "test -f /tmp/definitely-not-there.exit", "--timeout", "2s", "--quiet"]); expect(r.code).toBe(124); expect(r.out).not.toContain("设备 UI 状态"); expect(r.out).toContain("不要改成「环境阻塞」"); // 仍给通用引导 }, 20_000); test("--run 跑一条 adb 命令是正常用法,不该被警告", async () => { // 装包、点一下、起 App 都是 --run 的正当场景;只有「轮询一个 UI 条件」才是误用。 const r = await run(["--run", "echo 'adb shell dumpsys window'", "--timeout", "15s", "--quiet"]); expect(r.code).toBe(0); expect(r.out).not.toContain("设备 UI 状态"); }, 25_000); test("警告不拦截 —— 条件真达成时照常返回 0", async () => { const r = await run(["--until", "catuse apps | grep -q x || true", "--timeout", "10s", "--quiet"]); expect(r.code).toBe(0); expect(r.out).toContain("设备 UI 状态"); // 警告仍打,但没挡住 expect(r.out).toContain("条件达成"); }, 20_000); });