monorepo-template / tests

---
description: "Vitest - two runtimes, @repo/vitest-config, no watch for agents"
alwaysApply: false
globs: **/*.test.ts,**/tests/**,**/vitest.config.ts,**/vitest.config.mts
---

# Vitest (general)

Shared factories: `@repo/vitest-config` (Node) and `@repo/vitest-config/workers` (Cloudflare pool). Discipline: [testing.mdc](../quality/testing.mdc). Workers + Hono: [hono-workers.mdc](hono-workers.mdc). Front React: [front-react.mdc](front-react.mdc).

## Repo invariants

- Run via package scripts / turbo (`pnpm turbo run test --filter=<pkg>`). Package scripts use `vitest run`. Agents: non-watch only - never leave interactive watch or `--ui`.
- Turbo caches `test` with no outputs: a cache hit replays the stored log; add `--force` for a fresh execution. Single file: `pnpm --filter=<pkg> exec vitest run tests/<path>.test.ts`. Smoke-running the dev servers: skill `run-app`.
- Tests under `tests/` mirroring source; kebab-case `*.test.ts`. No Vitest globals - import from `"vitest"`. Never `jest.*`.
- Per-app `vitest.config.ts` / `.mts` via `@repo/vitest-config`. Pin `root` / `test.dir` with `resolvePackageRoot(import.meta.dirname)` for the Vitest VS Code explorer. No root Vitest workspace. Leave `reporters` unset so agent / GHA auto-detection works.
- **Two runtimes:** `worker-*` / `queue-*` / `webhook-*` / `mcp-*` → `@repo/vitest-config/workers`; `front-*` → `@repo/vitest-config` (Node). Never put Workers pool on front or Node pool knobs on Workers.
- **Cloudflare unit vs integration:** Vitest pool (`defineWorkersConfig`) = unit / single-Worker. Wrangler `createTestHarness` = multi-Worker production-build integration only - see `packages/vitest-config/AGENTS.md`. Do not replace pool route suites with the harness.
- Meaningful assertions on observable behavior (status, body, headers, binding effects). Prefer real pool bindings on Workers; mock only true I/O on Node, through `vi.fn` / `vi.stubGlobal` or an injected fake - never module mocking (`vi.mock` & co. are lint errors via `vitest/no-restricted-vi-methods`).
- Prefer package.json `#/*` imports over inventing `@/` aliases.