From fa626dc90f8cc3c74b429b4fbeefdd11f383c291 Mon Sep 17 00:00:00 2001 From: Yunfei He Date: Fri, 29 May 2026 14:02:33 +0800 Subject: [PATCH] docs(agents): record PTY-concurrent testing and concurrency constraints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document that the PTY suite runs concurrently (and the wall-clock-assertion pitfall there), plus the two patterns that force the main suite to stay sequential, with the root cause and fix for each: - Inline snapshots lose test context under concurrency — fixable via the context-local `expect` (test.concurrent("...", ({ expect }) => ...)). - Fake timers mutate process-global timer functions, so concurrent tests clobber each other's mocked timer state — not fixable with context; must stay sequential. Investigated empirically: enabling sequence.concurrent on the main suite fails deterministically (not flaky) in exactly the snapshot files (background-color, borders) and fake-timer files (throttle, animation-scheduler). --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 368c8aa..0192f31 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,6 +7,10 @@ - Bug fixes must follow test-first: write a failing test that reproduces the bug, then fix the code and verify the test passes. - Tests must simulate real user conditions. Non-TTY environments disable chalk colors — use `FORCE_COLOR` env var so ANSI output is always exercised. A bug invisible in tests but visible in a real terminal is a testing gap, not a minor issue. - When debugging color/ANSI output in non-TTY environments (e.g. Claude Code shell), use `FORCE_COLOR=3` env var to force chalk to output ANSI codes. +- The **PTY suite** (`vitest.pty.config.ts`) runs tests **concurrently** (`sequence.concurrent: true`). Each test spawns its own isolated subprocess/app, so they don't share state. Never assert on wall-clock-dependent behavior there (e.g. exact render/commit counts that rely on the renderer's ~32ms throttle): trigger the event so it renders synchronously and assert immediately after, or it flakes under CPU contention. `it.sequential` does NOT fix cross-fork CPU contention — fix the timing dependency instead. +- Two test patterns are **incompatible with concurrent execution** and must run sequentially (this is why the main `vite.config.ts` suite is **not** concurrent): + - **Inline/file snapshots** (`toMatchInlineSnapshot`): the module-level `expect` loses snapshot test context under concurrency. _Fixable_ — destructure the context-local `expect`: `test.concurrent("name", async ({ expect }) => { expect(x).toMatchInlineSnapshot() })`. + - **Fake timers** (`vi.useFakeTimers` / `advanceTimersByTime`): these mutate the **process-global** timer functions, so a concurrent test calling `useRealTimers()` yanks the mocked API out from under another mid-`advanceTimersByTime` ("timers not mocked"). _Not fixable_ with context — these tests must stay sequential. - After completing any task, run `vp run ready` (or `vpr ready`) to verify: lint, type-check, test all packages, and build. - Never commit anything under `docs/`. That directory is for local working notes and specs — it must stay out of git.