test: remove deterministic CI waits (#6144)

* test: remove deterministic CI waits

* test: stabilize workspace restoration reload

Author: PerishCode

AGENTS.md

@@ -268,6 +268,10 @@ root `pnpm tools-pr` script without a new explicit maintainer decision.
 
 ## Validation strategy
 
+- Before adding, repairing, or optimizing tests, follow
+  [`docs/testing/test-efficiency.zh-CN.md`](docs/testing/test-efficiency.zh-CN.md)
+  for completion signals, virtual-clock usage, isolation, and performance
+  validation.
 - After package, workspace, or command-entry changes, run `pnpm install` so workspace links and generated dist entries stay fresh.
 - For agent-stream / parser changes (`apps/daemon/src/runtimes/claude-stream.ts`, `json-event-stream.ts`, `qoder-stream.ts`, etc.), replay a recorded session through the mock CLIs in `mocks/` to verify event shapes round-trip without burning provider budget. PATH-overlay activation: `export PATH="$PWD/mocks/bin:$PATH" OD_MOCKS_TRACE=<8-char-id> OD_MOCKS_NO_DELAY=1`. See `mocks/README.md` for the trace catalog and selection knobs.
 - Treat every `pnpm-lock.yaml` change that affects Nix packaging as requiring a Nix pnpm deps hash refresh when you maintain the flake. `nix/pnpm-deps.nix` is a generated lock artifact; use `pnpm nix:update-hash` then re-run `nix flake check --print-build-logs --keep-going` locally. Standalone `.github/workflows/nix.yml` runs flake check when nix/lock inputs change; it is **not** part of core `ci.yml` / `Validate workspace` / merge queue. Docker image smoke/publish lives only in `.github/workflows/docker-image.yml` and is likewise outside the merge gate.

apps/web/tests/components/App.amr-polling.test.tsx

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 
-import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { App } from '../../src/App';
@@ -205,6 +205,12 @@ function deferred<T>() {
   return { promise, resolve, reject };
 }
 
+async function advanceTestClock(ms: number): Promise<void> {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(ms);
+  });
+}
+
 describe('App AMR polling', () => {
   beforeEach(() => {
     mockedDaemonIsLive.mockResolvedValue(true);
@@ -255,20 +261,24 @@ describe('App AMR polling', () => {
 
   afterEach(() => {
     cleanup();
+    vi.useRealTimers();
     vi.unstubAllGlobals();
     vi.clearAllMocks();
   });
 
-  it('keeps polling AMR models until the remote catalog replaces the preset list', { timeout: 10_000 }, async () => {
+  it('keeps polling AMR models until the remote catalog replaces the preset list', async () => {
+    vi.useFakeTimers();
     render(<App />);
 
-    await waitFor(() => {
-      expect(screen.getByTestId('amr-model').textContent).toBe('preset-a');
-    });
+    await advanceTestClock(0);
+    expect(screen.getByTestId('amr-model').textContent).toBe('preset-a');
+    expect(mockedFetchAmrModels).toHaveBeenCalledTimes(1);
 
-    await waitFor(() => {
-      expect(screen.getByTestId('amr-model').textContent).toBe('remote-a');
-    }, { timeout: 4_000 });
+    await advanceTestClock(1_999);
+    expect(mockedFetchAmrModels).toHaveBeenCalledTimes(2);
+    await advanceTestClock(1);
+
+    expect(screen.getByTestId('amr-model').textContent).toBe('remote-a');
     expect(mockedFetchAmrModels).toHaveBeenCalledTimes(3);
   });
 
@@ -409,9 +419,8 @@ describe('App AMR polling', () => {
     }
   });
 
-  it('restarts AMR polling after sign-in when preset refresh previously stopped on a remote error', {
-    timeout: 10_000,
-  }, async () => {
+  it('restarts AMR polling after sign-in when preset refresh previously stopped on a remote error', async () => {
+    vi.useFakeTimers();
     mockedFetchAmrModels.mockReset();
     mockedFetchAmrModels
       .mockResolvedValueOnce({
@@ -433,19 +442,15 @@ describe('App AMR polling', () => {
 
     render(<App />);
 
-    await waitFor(() => {
-      expect(mockedFetchAmrModels).toHaveBeenCalledTimes(1);
-    });
-
-    await waitFor(() => {
-      expect(mockedFetchAmrModels).toHaveBeenCalledTimes(2);
-    }, { timeout: 4_000 });
-    await waitFor(() => {
-      expect(screen.getByTestId('amr-model').textContent).toBe('preset-a');
-    });
+    await advanceTestClock(0);
+    expect(mockedFetchAmrModels).toHaveBeenCalledTimes(1);
+    expect(screen.getByTestId('amr-model').textContent).toBe('preset-a');
 
-    await new Promise((resolve) => setTimeout(resolve, 1_500));
+    await advanceTestClock(1_000);
+    expect(mockedFetchAmrModels).toHaveBeenCalledTimes(2);
+    expect(screen.getByTestId('amr-model').textContent).toBe('preset-a');
 
+    await advanceTestClock(1_500);
     expect(mockedFetchAmrModels).toHaveBeenCalledTimes(2);
     mockedFetchVelaLoginStatus.mockResolvedValue({
       loggedIn: true,
@@ -455,15 +460,12 @@ describe('App AMR polling', () => {
     });
 
     fireEvent.click(screen.getByText('open settings'));
-    await waitFor(() => {
-      expect(screen.getByText('mark amr signed in')).toBeTruthy();
-    });
+    expect(screen.getByText('mark amr signed in')).toBeTruthy();
     fireEvent.click(screen.getByText('mark amr signed in'));
+    await advanceTestClock(0);
 
-    await waitFor(() => {
-      expect(mockedFetchAmrModels).toHaveBeenCalledTimes(3);
-      expect(screen.getByTestId('amr-model').textContent).toBe('remote-a');
-    }, { timeout: 4_000 });
+    expect(mockedFetchAmrModels).toHaveBeenCalledTimes(3);
+    expect(screen.getByTestId('amr-model').textContent).toBe('remote-a');
   });
 
   it('does not restart AMR model polling for repeated signed-in status snapshots', async () => {
@@ -497,9 +499,8 @@ describe('App AMR polling', () => {
     expect(mockedFetchAmrModels).toHaveBeenCalledTimes(2);
   });
 
-  it('stops polling after the preset retry budget is exhausted when remote never arrives', {
-    timeout: 20_000,
-  }, async () => {
+  it('stops polling after the preset retry budget is exhausted when remote never arrives', async () => {
+    vi.useFakeTimers();
     mockedFetchAmrModels.mockReset();
     mockedFetchAmrModels.mockImplementation(async () => ({
       source: 'preset',
@@ -509,14 +510,15 @@ describe('App AMR polling', () => {
 
     render(<App />);
 
-    await waitFor(() => {
-      expect(mockedFetchAmrModels).toHaveBeenCalledTimes(11);
-    }, { timeout: 12_000 });
-
-    await new Promise((resolve) => setTimeout(resolve, 1_500));
+    await advanceTestClock(0);
+    expect(mockedFetchAmrModels).toHaveBeenCalledTimes(1);
+    await advanceTestClock(10_000);
 
     expect(mockedFetchAmrModels).toHaveBeenCalledTimes(11);
     expect(screen.getByTestId('amr-model').textContent).toBe('preset-a');
+
+    await advanceTestClock(1_500);
+    expect(mockedFetchAmrModels).toHaveBeenCalledTimes(11);
   });
 
   it('does not merge stale AMR remote models over a rescan with new agent env', async () => {

apps/web/tests/components/ProjectView.run-cleanup.test.tsx

@@ -234,6 +234,18 @@ async function waitForReadyChatPaneProps() {
   };
 }
 
+async function advanceTestClock(ms: number): Promise<void> {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(ms);
+  });
+}
+
+async function settleTestClock(): Promise<void> {
+  for (let step = 0; step < 3; step += 1) {
+    await advanceTestClock(0);
+  }
+}
+
 describe('terminal replay artifact recovery', () => {
   it('only reuses existing artifacts created at or after the current run started', () => {
     const runCreatedAt = 1_000;
@@ -2357,6 +2369,7 @@ describe('ProjectView daemon cleanup', () => {
   });
 
   it('keeps reattaching after two generic disconnects while daemon status stays running, but backs off before the next retry', async () => {
+    vi.useFakeTimers();
     const runCreatedAt = Date.now();
     const genericDisconnect = await createGenericDisconnectError();
 
@@ -2419,16 +2432,15 @@ describe('ProjectView daemon cleanup', () => {
       />,
     );
 
-    await waitFor(() => expect(reattachDaemonRun.mock.calls.length).toBeGreaterThanOrEqual(2), {
-      timeout: 2_000,
-    });
-    expect(reattachDaemonRun.mock.calls.length).toBe(2);
-    await new Promise((resolve) => setTimeout(resolve, 500));
-    expect(reattachDaemonRun.mock.calls.length).toBe(2);
-    await waitFor(() => expect(reattachDaemonRun.mock.calls.length).toBeGreaterThanOrEqual(3), {
-      timeout: 4_500,
-    });
-  }, 12_000);
+    await settleTestClock();
+    expect(reattachDaemonRun).toHaveBeenCalledTimes(2);
+
+    await advanceTestClock(2_999);
+    expect(reattachDaemonRun).toHaveBeenCalledTimes(2);
+    await advanceTestClock(1);
+    await settleTestClock();
+    expect(reattachDaemonRun.mock.calls.length).toBeGreaterThanOrEqual(3);
+  });
 
   it.each([
     {
@@ -2609,19 +2621,19 @@ describe('ProjectView daemon cleanup', () => {
     );
 
     const sendProps = await waitForReadyChatPaneProps();
+    vi.useFakeTimers();
     await sendProps!.onSend!('flaky stream', [], []);
 
-    await waitFor(() => expect(streamViaDaemon).toHaveBeenCalledTimes(1));
-    await waitFor(() => expect(reattachDaemonRun.mock.calls.length).toBeGreaterThanOrEqual(1), {
-      timeout: 2_000,
-    });
-    expect(reattachDaemonRun.mock.calls.length).toBe(1);
-    await new Promise((resolve) => setTimeout(resolve, 500));
-    expect(reattachDaemonRun.mock.calls.length).toBe(1);
-    await waitFor(() => expect(reattachDaemonRun.mock.calls.length).toBeGreaterThanOrEqual(2), {
-      timeout: 4_500,
-    });
-  }, 12_000);
+    await settleTestClock();
+    expect(streamViaDaemon).toHaveBeenCalledTimes(1);
+    expect(reattachDaemonRun).toHaveBeenCalledTimes(1);
+
+    await advanceTestClock(2_999);
+    expect(reattachDaemonRun).toHaveBeenCalledTimes(1);
+    await advanceTestClock(1);
+    await settleTestClock();
+    expect(reattachDaemonRun.mock.calls.length).toBeGreaterThanOrEqual(2);
+  });
 
   it('keeps a partial live generic disconnect recoverable after the first failure', async () => {
     const runCreatedAt = Date.now();
@@ -2793,6 +2805,7 @@ describe('ProjectView daemon cleanup', () => {
   });
 
   it('keeps generic-disconnect cap retryable when the follow-up status probe returns null, but backs off before retrying', async () => {
+    vi.useFakeTimers();
     const runCreatedAt = Date.now();
     const genericDisconnect = await createGenericDisconnectError();
 
@@ -2873,16 +2886,15 @@ describe('ProjectView daemon cleanup', () => {
       />,
     );
 
-    await waitFor(() => expect(reattachDaemonRun.mock.calls.length).toBeGreaterThanOrEqual(2), {
-      timeout: 2_000,
-    });
-    expect(reattachDaemonRun.mock.calls.length).toBe(2);
-    await new Promise((resolve) => setTimeout(resolve, 500));
-    expect(reattachDaemonRun.mock.calls.length).toBe(2);
-    await waitFor(() => expect(reattachDaemonRun.mock.calls.length).toBeGreaterThanOrEqual(3), {
-      timeout: 4_500,
-    });
-  }, 12_000);
+    await settleTestClock();
+    expect(reattachDaemonRun).toHaveBeenCalledTimes(2);
+
+    await advanceTestClock(2_999);
+    expect(reattachDaemonRun).toHaveBeenCalledTimes(2);
+    await advanceTestClock(1);
+    await settleTestClock();
+    expect(reattachDaemonRun.mock.calls.length).toBeGreaterThanOrEqual(3);
+  });
 
   it('finalizes a reattach generic disconnect as succeeded when the next status poll turns terminal', async () => {
     const runCreatedAt = Date.now();

docs/testing/test-efficiency.zh-CN.md

@@ -0,0 +1,120 @@
+# 测试效率与确定性
+
+本文记录当前测试实现与评审应遵守的效率规则。目标是在不降低隔离性、
+覆盖强度和诊断质量的前提下，减少无意义的真实等待、重复初始化与重试。
+
+## 当前策略
+
+- 当前不以统一耗时分档或 guard 拒绝测试变更。
+- 优先修复有重复 CI 证据的异常用例，再用收敛后的数据建立耗时基线。
+- 测试超时是失败预算，不是测试预期需要消耗的时长。
+- CI retry 只用于保留诊断机会；首次失败、重试通过仍视为待修复信号。
+- 优化不得通过共享可变运行时、串行化用例或削弱断言来换取速度。
+
+## 等待业务完成信号
+
+测试必须等待后续动作真正依赖的完成信号，不能把中间 UI 状态当作持久化
+完成。
+
+例如，上传后立即 reload、切换项目或访问深链接时：
+
+1. 在触发上传前注册对应的 response waiter。
+2. 精确匹配请求方法和业务路径。
+3. 断言响应成功。
+4. 再验证 UI，并执行 reload 或导航。
+
+```ts
+const uploaded = page.waitForResponse((response) => {
+  const url = new URL(response.url());
+  return response.request().method() === 'POST'
+    && url.pathname.endsWith('/upload');
+});
+
+await input.setInputFiles(file);
+expect((await uploaded).ok()).toBe(true);
+await page.reload();
+```
+
+仅等待标签、按钮、toast 或乐观列表项出现是不充分的，除非该状态本身就是
+用例的最终业务结果，且后续步骤不依赖服务端持久化。
+
+## 时钟驱动逻辑
+
+polling、retry、backoff、debounce、throttle、TTL 和自动关闭等逻辑默认使用
+虚拟时钟测试。
+
+- 在定时器被创建前调用 `vi.useFakeTimers()`。
+- 通过 React `act` 推进时钟并等待异步回调完成。
+- 同时断言边界两侧，例如 `2999ms` 尚未执行、再推进 `1ms` 后执行。
+- 在 `afterEach` 中恢复真实时钟，避免污染同文件的其他用例。
+- 不用扩大 test timeout 代替虚拟时钟。
+
+```ts
+vi.useFakeTimers();
+
+await act(async () => {
+  await vi.advanceTimersByTimeAsync(2_999);
+});
+expect(retry).not.toHaveBeenCalled();
+
+await act(async () => {
+  await vi.advanceTimersByTimeAsync(1);
+});
+expect(retry).toHaveBeenCalledTimes(1);
+```
+
+虚拟时钟必须保持被测并发语义。若一个用例专门验证浏览器事件循环、React
+提交和未决 I/O 之间的交错，而 fake timer 会把这些阶段合并进同一个
+`act`，应保留真实时钟并在代码旁说明该等待保护的语义。
+
+## 真实等待
+
+不要使用 `setTimeout` 或固定 sleep 等待普通异步状态“应该已经完成”。
+优先选择：
+
+- 等待网络 response、SSE 终止事件或进程退出；
+- 等待可观察的持久化数据；
+- 等待明确的 UI actionability 或稳定状态；
+- 控制并解决 deferred promise；
+- 推进虚拟时钟。
+
+确实需要真实时间时，等待必须对应无法由测试控制的运行时边界，并使用仓库
+已有的超时常量。评审时应能从用例名称、断言或邻近注释看出该真实等待保护
+的具体行为。
+
+## 隔离与生命周期
+
+- 每个用例独立建立自己依赖的项目、配置、mock 和运行状态。
+- 不依赖同文件前序用例或同 worker 前序文件遗留的数据。
+- 不为了摊薄启动成本共享可变 daemon、浏览器上下文或数据目录。
+- 不用 serial group 隐藏竞争条件。
+- 只有在生命周期成本已经被证明为主要瓶颈，且隔离模型仍然明确时，才调整
+  harness 的预热或复用策略。
+
+## 优化顺序
+
+处理慢测试时按以下顺序判断：
+
+1. 消除固定 sleep 和真实业务计时。
+2. 用精确完成信号替换轮询式等待。
+3. 减少重复 render、启动和 fixture 构造，但保持用例隔离。
+4. 收紧过宽的查询、事件和断言范围。
+5. 确认单文件仍是关键路径后，再考虑拆文件或调整 shard。
+6. 只有生命周期本身占主导时，才评估 harness 级改动。
+
+大文件名、用例数量或文件总耗时只能用于定位，不能单独证明拆分有收益。
+文件拆分如果没有减少执行工作量，通常只会改变调度形状。
+
+## 验证要求
+
+优化后的测试至少满足：
+
+- 聚焦用例重复运行通过；
+- 所在测试文件完整通过；
+- 相关 package typecheck 通过；
+- `pnpm guard` 与根级 `pnpm typecheck` 通过；
+- UI 竞态修复在对应 merge lane 的运行模型下验证；
+- 记录优化前后的可比测试体耗时，区分测试体、文件和 CI job wall time。
+
+任何 retry-only pass、首次失败或明显偏离基线的耗时都需要解释，不能只报告
+最终绿色状态。