opencode: Skill for OpenCode

TUI tests

packages/tui runs about 170 test files in one bun test process. CI runs it next to up to two other suites on 4-vCPU runners (bun turbo test --affected --concurrency=3 in .github/workflows/test.yml), where it has taken 136-146s on Linux and 147-171s on Windows, most of it idle on frame pacing, production timers and sleeps. Most flakes come from waiting on the wrong signal and then running out of frames on a busy runner.

Read the root AGENTS.md Testing section (no globalThis mocks, run from the package directory) and its TUI Stories section. To drive the real TUI, use the opencode-dev skill. For CLI subprocesses, service deadlines, Effect TestClock and turbo test tasks, use the unit-tests skill.

Frame budgets are not time

• waitForFrame, waitFor and flush give up after maxPasses (default 20). waitForVisualIdle gives up after maxFrames (default 20). One pass is one rendered frame (DEFAULT_MAX_PASSES in @opentui/core/testing). "Timed out waiting for frame predicate after 20 passes" comes from this budget, not from bun's timeout.
• Started renderer (setup.renderer.start(), as createAppFixture does at packages/tui/test/fixture/app.ts:28): frames tick at OpenTUI's default 30 fps, so 20 passes are about 0.66s. Production renders at targetFps: 60 (packages/tui/src/app.tsx:241), so test frames are twice as slow as the real app.
• Not started (the default for testRender and createTestRenderer): waitFor and waitForFrame fail within milliseconds when no render is scheduled, and the error shows isRunning: false. In the same state flush() and waitForVisualIdle() return immediately without error; they do not wait for fetches or timers. Await the signal, then renderOnce().
• Wait on frames only for something a frame produces. For anything else, wait on the signal itself:
  • Focus set on a timer. DialogSelect focuses its filter with setTimeout(..., 1) (packages/tui/src/ui/dialog-select.tsx:702), which takes about 15ms on Windows. typeText sends keys to whatever is focused, so early keys are dropped and Enter then picks the default option. Put the focus in the predicate, as both dialog waits in packages/tui/test/command-selection.test.tsx do (:68-70 for the model, :75-80 for the variant): setup.renderer.currentFocusedRenderable instanceof InputRenderable. Before the variant wait had it, the test flaked in 5 CI runs in 20 hours, including a dev push, and a bigger budget did not help: it still failed with maxPasses: 150, because the keys were lost, not late. If a wait fails with the focus in the predicate, look for a state race, not the budget.
  • Markdown and code text. <markdown> (packages/tui/src/routes/session/message-parts.tsx:182) draws no text until the shared tree-sitter worker replies, while frames keep ticking, so a plain waitForFrame can spend all 20 passes on a loaded runner with the text still pending. Use waitForHighlightedFrame(setup, predicate, options?) from packages/tui/test/fixture/frame.ts. When the predicate fails, it awaits every in-flight CodeRenderable.highlightingDone inside the frame predicate, and awaiting there does not use up passes. It accepts any setup with renderer and waitForFrame; app-lifecycle, session-group-navigation and session-home wait on transcript text this way. If the code under test accepts a client, inject new MockTreeSitterClient({ autoResolveTimeout: 0 }) instead (packages/tui/test/mini/scrollback.surface.test.ts:87).
  • Requests and other state. Await the deferred response your fetch handler returns. With no signal to await, poll with a wall-clock deadline instead of raising maxPasses: the file-local waitForFrame(setup, matches) at command-selection.test.tsx:117 checks captureCharFrame() every 10ms for up to 2s. wait in packages/tui/test/cli/tui/data.test.tsx:37 and waitForModel in packages/tui/test/fixture/local.tsx:109 do the same for state.
• waitForVisualIdle returns on the first frame with cellsUpdated === 0 by default. A frame waiting on a highlight is also quiet, so wait for the text before you measure layout or assert on it: session-home.test.tsx:227 waits for "History message 0001" with waitForHighlightedFrame after waitForVisualIdle() instead of reading the frame directly.
• Settle steps cost frames. Each waitForVisualIdle({ quietFrames: 3 }) takes at least 3 frames, about 100ms at 30 fps. session-group-navigation.test.tsx has 14 of them. When you know what you are waiting for, wait for that frame instead.
• Do not use maxPasses as a clock. Several waits do, and each assumes 33ms frames:
  • app-lifecycle.test.tsx:792: 120 passes to cover the 1s reconnect delay after setup.events.disconnect() at :784;
  • app-lifecycle.test.tsx:1721-1723: 200 passes per retry-countdown second;
  • component/dialog-shell-output.test.tsx:144: 100 passes for a 1s poll, plus Bun.sleep(1100) at :163 and :182;
  • session-panel.test.tsx:590: 120 passes in ready() for the initial load.