Files
streamline/satellite/test/wait_for.test.ts
T
2026-11-16 17:26:44 -08:00

346 lines
17 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* `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);
});