--- name: testing description: Run, place and fix tests in this repo. Use when choosing which npm command runs a given suite (web unit, web integration, Storybook, cli, tui, launcher, scripts); when deciding where a new test file belongs — beside its source, under src/test/, or in a client's __tests__/; when a per-file coverage check fails or a v8 ignore is in question; when asking which test tier spawns the built binary rather than importing it; or when rendering, mounting or asserting on Mantine components and their transitions in a test. disable-model-invocation: false --- # Testing **Every change needs tests, and every file must clear ≥90% on lines, statements, functions, and branches.** That rule and the React/Mantine conventions live in [`AGENTS.md`](../../../AGENTS.md); this skill is where a test goes, how to run it, and how to clear the gate. ## Before you write it: does the test need a real server? **If it does, load the `test-servers` skill now — that is step one, before choosing a location or writing a line.** The condition is **"does this test depend on a fixture from `test-servers/`?"** — not which tier it lands in, and not which directory it lands in. There are two ways to depend on one, and they need different halves of that skill: - **It connects to a fixture.** An integration test that connects; an end-to-end test that connects; a smoke that drives a connected flow; a coverage gap only reachable over a real connection; reproducing a reported bug against a server. These need the whole procedure — which showcase config, which protocol era, and the staleness hazard. ⚠️ **Connecting is a strong hint, not the rule.** A few integration tests deliberately hand-roll a JSON-RPC server because the composable fixture *cannot* produce what they assert on — `inspectorClient-malformed-list.test.ts` and `listSalvage-era.test.ts` need wire shapes the SDK's own server refuses to emit. Real transport, real client, no `test-servers/` dependency. Check whether a fixture can express the case before reaching for one. - **It names or runs the built fixture without connecting.** `smoke:tui` boots the TUI against a catalog whose stdio command *is* the built fixture, then asserts it survives. No transport is driven and no protocol era applies, but the **build and staleness** half lands on it in full. ⚠️ **"A build ran" is not the dependency — using the artefact is.** `clients/web`'s `pretest` runs `test-servers:build` before *every* unit run, so the fixture is on disk for tests that never reference it. What counts is whether the test imports, spawns, or points a config at it. So the condition does **not** hold when the test renders a component from fixture props, exercises a pure function or a parser, or is a smoke that touches no fixture — `smoke:launcher` checks `--help`, and `smoke:web` / `smoke:web:browser` only assert the SPA is served and paints. ⚠️ **Neither the tier nor the folder decides this.** `src/test/integration/` holds `storage/store-id.test.ts`, which validates a string, and `mcp/import/*`, which parses config files, right beside the tests that drive a live connection. They sit there for the node env and the 30s timeout, not because they connect — placement is the project manifest, so it cannot also be the fixture trigger. Ask what the test *does*, not where it lives. **In the connecting case**, the test drives a **real server over a real transport, never a mock**, and picking the fixture, building it, and connecting with the right protocol era is a procedure this skill does not carry. Writing one without `test-servers` means hand-rolling a fixture that already exists, or mocking the thing the tier exists to avoid mocking. **In the build-only case**, none of the transport or protocol-era guidance applies — what you need from `test-servers` is how to build the fixture and why a stale build keeps serving old code. ## Where the test file goes **Side-by-side by default; `src/test/` only for what can't be co-located; and the Node clients are different.** ### `clients/web` — side-by-side `.test.tsx` (or `.test.ts` for non-React modules) **next to the source**. Components, hooks, `lib/`, `utils/`. This is the overwhelming majority; a web-owned test living under `src/test/` instead is a bug. `clients/web/src/test/` is for the three things that *cannot* be co-located: 1. **Tests of the repo-root `core/` package** → `src/test/core/…`, mirroring the `core/` folder layout. `core/` physically lives outside `clients/web/`, is consumed via the `@inspector/core` alias, and has no test harness of its own. This includes `core/json/*` and `core/client/*`. 2. **The `integration` project** → `src/test/integration/…`, mirroring the `core/` source layout (`mcp/`, `mcp/node/`, `mcp/remote/`, `auth/`, `auth/node/`, `storage/`). **Placement is the manifest** — any file under that folder is picked up by the integration project (node env, 30s timeouts) via a folder glob; there is no enumeration to keep in sync. ⚠️ Placement is *not* the fixture trigger, though — this folder holds pure parser and storage tests alongside the connecting ones. If the test you are adding here **needs a fixture from `test-servers/`, load that skill first**; the fixture is half of that test. Connecting is a strong hint but not the rule — see the hand-rolled-server exception above. 3. **Shared test infrastructure** — `renderWithMantine.tsx`, `setup.ts`, `fixtures/`, `scrollAreaStoryAssertions.ts`. ### `clients/cli`, `clients/tui`, `clients/launcher` — a top-level `__tests__/` **All** their tests, not beside their source. Their `tsconfig.json` excludes `**/*.test.*` and their `tsconfig.test.json` includes `__tests__/**/*`, so a co-located `src/**/*.test.*` lands in **no** tsconfig project and fails `npm run verify:typecheck-coverage` (#1791). ### Root tooling — `scripts/*.test.mjs` A new `scripts/*.mjs` helper with pure logic gets a sibling `*.test.mjs`, run by `npm run test:scripts` (node's built-in runner; the root has no vitest harness by design). ⚠️ Keep the filename `*.test.mjs` — `node --test` silently **skips** a file its glob misses and still exits 0. ## Running them | Scope | From | Command | | --- | --- | --- | | Web unit | `clients/web` | `npm run test` (`test:watch` while iterating) | | Web integration | `clients/web` | `npm run test:integration` | | Web Storybook play fns | `clients/web` | `npm run test:storybook` | | CLI | `clients/cli` | `npm run test` (`pretest` builds test-servers + the bin) | | TUI | `clients/tui` | `npm run test` | | Launcher | `clients/launcher` | `npm run test` | | Root tooling | repo root | `npm run test:scripts` | | Everything, fast | repo root | `npm run validate` | | The coverage gate | repo root | `npm run coverage` | There is **no aggregate root `test` script** — each client self-validates. In unit tests that expect error output, **suppress it from the console**. ## The tiers, shallowest first unit (`test`, per client) → web integration (`test:integration`, real transports/servers) → out-of-process (`clients/cli/__tests__/e2e.test.ts`, spawns the built binary) → smokes through the built launcher (`npm run smoke`) → Storybook play functions (`test:storybook`) → the published-tarball check (`npm run pack:verify`, local/release only — needs network). ⚠️ **Depth in that list is not the fixture boundary, and the boundary cuts across the tiers rather than along them.** Needing `test-servers/`: the web integration tests **that drive one**, the out-of-process CLI tests, the smokes that connect (`smoke:cli`, `smoke:web:app`, `smoke:web:elicit`, `smoke:web:tabs`), `pack:verify`, and **`smoke:tui`** — which never asserts a round trip but calls `ensureTestServers({ requires: ["stdio"] })` and hands the built fixture to the TUI as its catalog's stdio command. Not needing it: the pure tests inside the same integration project, the connecting tests that deliberately hand-roll a server, `smoke:launcher`, `smoke:web` and `smoke:web:browser` (all three stop at boot without a fixture), and every Storybook play function (fixture props). **Load the `test-servers` skill as soon as a task puts you on the fixture side of that line** — whichever tier it sits in. `validate` runs the per-client `test` scripts — so web **unit** plus cli's out-of-process `e2e.test.ts`, but **not** web's integration project, which runs inside the `coverage` gate. CI therefore has no separate `test:integration` step. ## The coverage gate **Per-file ≥90 on all four dimensions**, CI-enforced, across web, cli, tui and launcher. New code must clear 90 on every dimension. Scope notes: - The **web** coverage `include` (in `clients/web/vite.config.ts`) also covers the shared `core/` runtime the browser consumes — `core/mcp`, `core/react`, `core/auth`, `core/storage`, `core/logging`, `core/node`, `core/json`, `core/client`. - ⚠️ That `include` is a **whitelist** naming `components`/`hooks`/`theme`/ `lib`/`utils`/`server`. A module placed **outside** those directories falls out of the gate entirely, silently. The documented exceptions are `src/App.tsx` (a composition root at ~42% branch coverage — gating it is a dedicated decomposition effort) and the `src/main.tsx` / `src/index.ts` bootstraps. - **CLI** tests run **in-process** by importing `runCli()` (`__tests__/helpers/cli-runner.ts`) so `src` is measured; `src/index.ts` is the only exclusion. `commander` uses `.exitOverride()` so a parse error throws instead of tearing down the test worker. - **TUI** covers **all of `src/**`, React surface included**. Components mount through `ink-testing-library` with the passthrough doubles in `__tests__/helpers/`; keypresses are driven through stdin. The only exclusion is `src/tui-servers.ts` (a pure re-export, excluded so it doesn't surface as a misleading 0/0 row). ### When a `v8 ignore` is justified A genuinely-unreachable branch is annotated at the source rather than waved through by lowering the gate. The acceptable reasons are enumerated in [`AGENTS.md`](../../../AGENTS.md) — do not reach for one that is not on that list. ## React tests: `renderWithMantine` **Always render through `renderWithMantine`** (`src/test/renderWithMantine.tsx`) — it wraps in `MantineProvider` with the project theme. Do not hand-roll a bare `MantineProvider`; it skips the project theme and the helper's options and drifts from every other test. Note the justification has changed and the old one is wrong: it sets `env="test"`, which makes Mantine skip the animated **render** — but it does **not** stop the timers. `env` is read only at `Transition.mjs`'s render branch, while `useTransition()` runs before that check and still schedules real `window.setTimeout`s (opening a `` schedules three 200ms timers). What prevents a timer outliving its file — and throwing an uncaught `ReferenceError: window is not defined` that fails the **whole run**, attributed to an innocent file (#1760) — is the **leaked-timer safety net in `src/test/setup.ts`**, which is global and covers every unit test however it renders. The rule stands on consistency, not on timer safety. - **Forced color scheme:** pass the option — `renderWithMantine(ui, { colorScheme: "dark" })` — rather than hand-rolling `defaultColorScheme="dark"`. - **Mid-flight transition state** (e.g. asserting a `data-anim="out"` cell during an exit crossfade) is the only reason to use `renderWithMantineTransitions`. Pass `settleMs` derived from the component's real animation duration (`HEADER_ANIM_MS + 200`), do **not** also use `vi.useFakeTimers()` in that test (the auto-settle no-ops under fake timers), and if the test unmounts the tree itself use the `unmount()` the helper returns. The mechanism is documented at length on the helper — read there before changing it. ## Storybook play functions Every screen and element component has a `*.stories.tsx`; play functions double as interaction tests, run headless in CI and in the local gate. ⚠️ **`expect(...)` from `storybook/test` returns a promise.** Storybook instruments it, so every `expect` in a play function is awaited — as is any shared helper that wraps one. ## Test servers, not mocks The tests that drive MCP behaviour over a transport use a real server rather than a mock, and **for the ones that get that server from `test-servers/`, load the skill and use all of it**: which showcase config covers the feature, which protocol era to connect with, how to add a combination that does not exist yet, and why a fixture can keep serving stale code after an edit. **A test that only *names* the built fixture needs that skill too, for a narrower reason.** `smoke:tui` boots the TUI against a catalog whose stdio command is the build output and asserts it survives — it opens no transport, so config choice and protocol era do not apply to it, but **building the fixture and the staleness hazard do.** Load the skill and take that half. A pure test that happens to live in the integration project, and a smoke that references no fixture, need neither (see the tier list above) — and note that `clients/web`'s `pretest` builds `test-servers/` before every unit run, so its presence on disk says nothing about whether your test depends on it.