Vitest Agent Rules: AGENTS.md Explained

Overview

Vitest distinguishes source checks, bundled output, test helpers, and CI coverage. Command pairs and exception lists show when a successful local check has tested the wrong files or missed generated output.

Documents

├── 
├──  · imports AGENTS.md
├── .github
│   └── 
├── docs
│   ├── guide
│   │   └── 
│   └── 
├── packages
│   └── vitest
│       └── 
└──

Patterns in this file

Good and bad pairs Architecture as narrative Verification by change type Generated file guards Contribution etiquette

01 / Good and bad pairs

Show the test-filter command that silently broadens a run

The guide pairs the pnpm invocation that loses its filter with the one that forwards it correctly. It explains the consequence so an agent can recognize an unexpectedly broad run.

51# WRONG - runs ALL tests (filter is ignored):52pnpm test -- basic.test.ts -t 'expect'53 54# CORRECT - runs only matching tests:55pnpm test basic.test.ts -t 'expect'

02 / Architecture as narrative

Separate source checking from the output tests execute

Typechecking reads TypeScript source while tests resolve workspace exports into dist. The mocker package is singled out because rebuilding Vitest does not inline its changes.

64Tests execute built output: test suites resolve `vitest` through workspace symlinks whose package exports point at `dist/`, while `pnpm typecheck` resolves TypeScript source. A passing typecheck never proves `dist` is fresh; rebuild before re-running tests.

03 / Verification by change type

State the holes in the root typecheck

The file lists the excluded test and documentation directories. It also supplies a separate command for Vue UI client changes, making the coverage boundary part of the workflow.

142- Root typecheck does not cover the UI client Vue code; when changing `packages/ui/client`, also run `pnpm -C packages/ui typecheck:client`

04 / Generated file guards

Name generated files even when the file has no banner

CLI option changes require regenerating the documentation table. The guide also explains that CI rebuilds and checks the diff, so reverting generated output does not make a change complete.

182- `docs/guide/cli-generated.md` is generated from `packages/vitest/src/node/cli/cli-config.ts` (it carries no banner saying so)

05 / Contribution etiquette

Make external contribution limits explicit

Opening issues, PRs, or comments requires human review. Contributors without write access are limited to one PR and are explicitly prohibited from using drafts to bypass that boundary.

240This repository has a limit of 1 PR if you don't have write access. DO NOT try to bypass it by creating draft PRs. If you cannot create a pull request, let a human know that you will not breach this repository's policy because it will ban the PR author in Vitest organisation.