policy:
  allow_implicit_invocation: true

# Configuration

> Configuration and runner scripts are repository-owned. Add or migrate config only for the requested behavior.

- Keep project-specific environment and setup ownership. Use `test.projects` for distinct projects and give each a
  stable name; a project container does not run tests itself. Do not change a suite-wide environment for one exception.
- Keep aliases consistent with TypeScript and Vite resolution; aliases do not repair arbitrary externalized
  dependencies.
- Setup files are for truly suite-wide polyfills, matcher registration, cleanup, and mocks. Keep scenario data and heavy
  initialization in owned fixtures or tests.
- Coverage is opt-in. When requested, specify the intended source set and retain repository thresholds; do not use a
  provider change or lower threshold to hide a bad include/exclude set.
- For v4 migration, replace removed workspace/match-glob and worker settings with the documented project/worker model;
  `coverage.all` and the `basic` reporter are gone, `verbose` is flat, and browser APIs come from `vitest/browser`. See
  the [v4 migration guide](https://v4.vitest.dev/guide/migration).
- For v5 migration, require Vite 6.4+ and Node.js 22.12+; `vite` is now a peer dependency, so Yarn projects must add it.
  Audit these changes, which can silently alter results rather than fail:
  - `clearMocks` defaults to `true`, clearing call history recorded in setup files, at module scope, or in `beforeAll`.
  - Inline `test.projects` inherit the root config (`extends: true`, arrays such as `setupFiles` append) and share its
    Vite server (`sharedViteServer`). A referenced config that declares `projects` now expands into nested projects, so
    do not merge a root config that defines them.
  - `-t`/`testNamePattern` matches the `' > '`-joined full name; `test.each`/`test.for` titles no longer quote `$`
    strings.
  - Coverage `include`/`exclude` match project-relative paths without `contains`; glob thresholds no longer inherit
    `perFile`.
  - Config files are no longer found in parent directories; pass `--config` from a subdirectory.
  - Artifacts live under `.vitest/`, and the `json` and `junit` reporters write files instead of stdout unless
    `stdout: true` is set.
  - `VITEST_POOL_ID` and `VITEST_WORKER_ID` are 1-based.
  - Browser locators and `toHaveTextContent` match exactly (partial or regex matching moved to `toMatchTextContent`),
    and `browser.api` moved to top-level `api`.

  These now fail loudly: nested `vi.mock`/`vi.unmock`/`vi.hoisted`, unawaited
  `resolves`/`rejects`/`toMatchFileSnapshot`, late `expect.poll`, removed `sequential` APIs (use
  `{ concurrent: false }`), module-scope `bench` (now a test-context fixture), and the removed `vitest/coverage`,
  `vitest/reporters` (use `vitest/node`), `vitest/environments`, and `vitest/snapshot` (use `vitest/runtime`) entry
  points. Check the installed version's [migration guide](https://vitest.dev/guide/migration.html) rather than carrying
  shims.

Use repository reporter conventions. Otherwise prefer minimal agent-oriented output: Vitest 4.1 introduced
`--reporter=agent`; current versions call it `minimal` and retain `agent` as an alias. Use automatic agent detection
when available, and check the installed version's [reporter documentation](https://vitest.dev/guide/reporters.html)
before passing a flag. See [configuration](https://vitest.dev/config/file),
[projects](https://vitest.dev/config/projects), and [aliases](https://vitest.dev/config/alias).

# Mocking

> Mock boundaries and own their cleanup; prefer dependency injection when it keeps the production interface simpler.

- `vi.mock` is hoisted. Keep it at file scope (v5 throws otherwise); put handles used by its factory in `vi.hoisted`.
  Its specifier must be identical to the production `import` specifier, and it cannot mock `require()`.
- Create a fresh result from every stateful mock factory per test. Keep one-off module wiring in that file; share only
  repository-conventional factories.
- Install fake timers before code schedules work. Use async advancement when callbacks schedule promises, and always
  restore real timers. Do not combine fake timers with uncontrolled real waits. From v5, fake timers and
  `vi.setSystemTime` also mock a global `Temporal`.
- From v5, `clearMocks` defaults to `true`: call history is cleared before each test, so assert on calls made inside
  that test unless the repository sets `clearMocks: false`.
- Restore owned spies, timers, environment stubs, and replaced global property descriptors in local cleanup.
  `vi.restoreAllMocks()` restores `vi.spyOn` implementations but neither clears their history nor restores automocks;
  reset or reconfigure automocked exports explicitly.

See the installed version's [Vi API](https://vitest.dev/api/vi) for factory, timer, and stub semantics.

# Testing Patterns

> Match local naming, imports/globals, DOM utilities, fixtures, and cleanup.

- For components, drive accessible observable behavior: query by role or label, then visible text, with semantic test
  IDs last. Keep provider state fresh; centralize a wrapper only when several tests need it. Use jest-dom matchers only
  when the setup file imports them.
- Await or return every promise. Wrap callback APIs in a promise; a test callback parameter is Vitest context, not a
  completion callback. Since v4, pass an options object as the second argument (a numeric final timeout remains
  supported).
- Put fixture cleanup with the fixture and scenario data with its test. Use tables only where cases clarify distinct
  behavior. Use snapshots only for stable, reviewable output; focused assertions are usually better.
- Do not commit `only`. Use skips, tags, or concurrency only with an explicit condition and safe isolation.
- Use browser mode and visual assertions only when the repository already owns browser configuration; do not add it
  merely for a component test covered by the established environment.

See [Test API](https://vitest.dev/api/test) for version-specific options.

# Troubleshooting

> Reproduce with the narrowest repository command before changing configuration.

- For a hang, use `--detect-async-leaks` diagnostically: it is slower and identifies resources created by a test file
  that remain open. Before raising a timeout, investigate unawaited work, unresolved mocks, unbounded retries, unclosed
  resources, and fake-timer schedulers.
- For state that passes alone but fails in a suite, use order or `--no-file-parallelism` only to diagnose. Restore state
  where it is created and make stores, clients, caches, and stateful mocks fresh per test; serialization is not a fix.
- For missing mocks, resolution errors, or hoisting failures, check the identity and factory rules in
  [mocking.md](mocking.md) against the configured aliases.
- For discovery, check configured include/exclude, config root, selected project, and project ownership before renaming
  a test. Clear the Vite/Vitest cache only after evidence of stale dependency, transform, alias, or config resolution.
- Preserve the repository reporter. Reporter availability and output shape vary by Vitest version.

See [async-leak detection](https://vitest.dev/config/detectasyncleaks), [CLI](https://vitest.dev/guide/cli), and
[configuration](https://vitest.dev/config/file).