Verify Changes

verify-changes — testing and verification in dev-3.0

The two hard gates (lint + touched tests before push, full suite before a PR) live in AGENTS.md and apply whether or not you read this file. Everything here is the detail behind them: which runner covers what, how to write a test that fits, and what "enough" means.

Which config runs what

Vitest with happy-dom and React Testing Library. Three configs, three independent processes:

bun run test          # mainview + bun + cli in parallel, minus 3 slow e2e files (~6s)
bun run test:full     # everything incl. slow e2e (~42s) — CI/PR only
bun run test:watch    # watch mode

Running vitest directly (outside bun run): bunx vitest run, never npx.

Narrowing while iterating: bunx vitest run <path>, -t "<test name>", --repeat <n> for suspected flakes. Because the three configs are separate processes, a failure in one says nothing about the others — read which prefix ([mainview] / [bun] / [cli]) failed.

Local E2E policy: do not run the full E2E suite locally — bun run test:full and any equivalent unfiltered command are reserved for CI/PR validation. Investigating a specific behavior means running that one E2E file or test case.

What to test

• Unit (mandatory) — state reducer actions and their edge cases, all pure functions/utils/parsers, every RPC handler (happy path plus 2-3 error cases), CLI commands (parsing, validation, output), data-layer CRUD plus corrupt-data handling, git operations with mocked spawn, i18n interpolation and pluralization for every locale.
• Component (mandatory) — every major interactive component: board views, task cards, modals, settings panels.
• E2E (CLI-based) — full lifecycle through the CLI plus Unix socket against a real app process in a tmpdir: task lifecycle (create → move statuses → complete), project CRUD, worktree creation and cleanup, notes CRUD, CLI context auto-detection, concurrent writes with no data corruption.

House style

• One logical assertion per test; no dependencies between tests.
• Always userEvent, never fireEvent. Test behavior, not implementation.
• Mock only external boundaries — git, tmux, fs, Electrobun. Never mock internal modules.
• No sleep and no timer juggling; use proper async/await.
• Tests live in __tests__/ next to their module, e.g. src/mainview/components/__tests__/Dashboard.test.tsx.
• Avoid the patterns that make a suite flake under CI load: index-based queries (getAllBy…[0]), structural traversal (.parentElement, .closest(…)), and assertions wedged between two userEvent interactions without an intervening waitFor.

Mocking Electrobun RPC and providers

Components importing api from rpc.ts need the Electrobun native module mocked:

vi.mock("../../rpc", () => ({
	api: { request: { listDirectory: vi.fn(), addProject: vi.fn() /* … */ } },
}));

Components calling useT() must render inside <I18nProvider> (import from ../../i18n).

Handler tests mock the tmux singleton the same way they mock rpc.ts; the tmux client's own tests inject a fake spawn instead.

A test that reads a file as data is an untyped interface

Some tests consume something as data rather than importing it as code: workflow YAML parsed line by line, a fixture matched by a regex, a log line asserted on, a JSON shape read by string matching. Nothing type-checks that link, so reshaping the source breaks the test with the compiler silent.

The failure is worse than silent — it is misleading. When the test finally fails it describes the invariant ("every Bun-pinning workflow would ship an unproven pin"), not the missing source, so it reads as a real regression and someone spends an hour proving it is not.

Two rules:

• Before deleting or reshaping anything, grep who reads it — not just who imports it. A YAML key, a fixture line shape, a log string.
• If you write one of these, make its failure message name the cause and the fix — "the pinned string moved; update it in this test" — never just restate the invariant.