# Testing Strategy

> Use when writing, reviewing, or refactoring test code. Triggers on Vitest tests, React Testing Library usage, MSW handlers, Playwright E2E tests, pytest fixtures, test structure decisions, or coverage configuration. Contains 46 testing rules across 12 categories.

- Skill: `brite-nites/testing-strategy` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add brite-nites/testing-strategy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/brite-nites/testing-strategy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Brite-Nites (https://skillmd.com/u/brite-nites)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/brite-nites/testing-strategy

---


# Testing Strategy — Core Patterns, Vitest, Playwright & pytest

Testing patterns and conventions for Vitest, React Testing Library, MSW, Playwright, and pytest. Contains 46 rules across 12 categories, prioritized by impact. Focuses on patterns that produce reliable, maintainable tests — test isolation, mock boundaries, query priorities, meaningful coverage, E2E best practices, and Python testing fundamentals.

## When to Apply

Reference these guidelines when:
- Writing new test files or test cases
- Reviewing test code for correctness and maintainability
- Deciding what to mock and what to test through
- Setting up test infrastructure (MSW, factories, fixtures)
- Configuring coverage thresholds or CI test pipelines
- Refactoring flaky or brittle tests
- Writing or reviewing Playwright E2E tests
- Configuring Playwright for CI or visual regression
- Writing pytest fixtures, parametrize tests, or conftest.py files
- Reviewing pytest code for isolation, async patterns, or parallelism

## Target Versions

- Vitest 3.x
- React Testing Library 16.x
- MSW 2.x
- @testing-library/user-event 14.x
- Playwright 1.45+
- pytest 8.x
- anyio 4.x
- pytest-mock 3.x
- pytest-xdist 3.x

## Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | Test Structure | CRITICAL | `struct-` | 5 |
| 2 | Mocking Strategy | HIGH | `mock-` | 4 |
| 3 | Vitest Patterns | HIGH | `vitest-` | 5 |
| 4 | React Testing Library | HIGH | `rtl-` | 4 |
| 5 | MSW & API Mocking | MEDIUM-HIGH | `msw-` | 3 |
| 6 | Fixtures & Factories | MEDIUM | `fixture-` | 4 |
| 7 | Coverage & CI | MEDIUM | `ci-` | 4 |
| 8 | Snapshot Testing | LOW-MEDIUM | `snap-` | 3 |
| 9 | Playwright Fundamentals | HIGH | `pw-` | 4 |
| 10 | Playwright CI & Advanced | MEDIUM | `pw-` (shared) | 3 |
| 11 | pytest Fundamentals | HIGH | `pytest-` | 4 |
| 12 | pytest Advanced Patterns | MEDIUM | `pytest-` (shared) | 3 |

## Quick Reference

### 1. Test Structure (CRITICAL)

- `struct-arrange-act-assert` — Follow AAA pattern: setup, execute, verify in every test
- `struct-single-concept` — Each test verifies one behavior, not multiple assertions on different things
- `struct-descriptive-names` — Test names describe behavior: "shows error when email is invalid", not "test1"
- `struct-test-isolation` — Tests must not depend on other tests' state or execution order
- `struct-no-logic` — No conditionals, loops, or try/catch in tests — tests are straight-line code

### 2. Mocking Strategy (HIGH)

- `mock-boundaries` — Mock at system boundaries (network, filesystem, time), not internal modules
- `mock-reset` — Reset mocks between tests to prevent state leakage
- `mock-minimal` — Mock the minimum needed — over-mocking makes tests pass when code is broken
- `mock-type-safety` — Mocked return values must match the real type signature

### 3. Vitest Patterns (HIGH)

- `vitest-vi-mock` — Use vi.mock for module mocking, vi.spyOn for method spying
- `vitest-test-each` — Use test.each for parameterized tests instead of loops
- `vitest-setup-teardown` — Use beforeEach/afterEach for per-test setup, beforeAll/afterAll for expensive shared setup
- `vitest-in-source` — Use in-source testing for pure utility functions with no side effects and no more than 3 dependencies
- `vitest-fake-timers` — Use vi.useFakeTimers for time-dependent code, always restore after

### 4. React Testing Library (HIGH)

- `rtl-query-priority` — Query by role > label > text > testId. Avoid container.querySelector
- `rtl-user-event` — Use userEvent over fireEvent for realistic user interaction simulation
- `rtl-async-queries` — Use findBy for elements that appear asynchronously, waitFor for assertions
- `rtl-avoid-implementation` — Test behavior, not implementation — don't assert on state or props

### 5. MSW & API Mocking (MEDIUM-HIGH)

- `msw-handlers` — Define default handlers in a shared handlers file, override per-test for edge cases
- `msw-server-setup` — Use setupServer in test setup, resetHandlers in afterEach, close in afterAll
- `msw-response-assertions` — Assert on rendered output from API responses, not on whether fetch was called

### 6. Fixtures & Factories (MEDIUM)

- `fixture-factories` — Use factory functions that return valid defaults with optional overrides
- `fixture-no-shared-mutation` — Never mutate shared fixture objects — create fresh instances per test
- `fixture-realistic-data` — Use realistic data shapes, not placeholder strings like "test" or "abc"
- `fixture-builders` — Use builder pattern for complex objects with many optional fields

### 7. Coverage & CI (MEDIUM)

- `ci-meaningful-coverage` — Measure branch coverage, not just line coverage. Target 80% as a floor, not a ceiling
- `ci-parallel-execution` — Run tests in parallel by default; isolate tests that need serial execution
- `ci-flaky-quarantine` — Quarantine flaky tests immediately, fix root cause, don't retry-and-ignore
- `ci-test-splitting` — Split test suites across CI workers by file for faster pipelines

### 8. Snapshot Testing (LOW-MEDIUM)

- `snap-inline-small` — Use inline snapshots for small outputs (< 10 lines), file snapshots for large
- `snap-avoid-large` — Never snapshot entire component trees — snapshot the specific output that matters
- `snap-review-updates` — Review every snapshot update in diffs — never blindly run --update

### 9. Playwright Fundamentals (HIGH)

- `pw-page-objects` — Encapsulate page interactions in page object classes; expose behaviors, not selectors
- `pw-selectors` — Prefer `getByRole` > `getByLabel`/`getByText` > `getByTestId` > CSS (mirrors `rtl-query-priority`)
- `pw-test-isolation` — Each test gets a fresh browser context; no shared mutable state (cross-ref `struct-test-isolation`)
- `pw-fixtures` — Use `test.extend` for custom fixtures; compose fixtures; use `{ scope: 'worker' }` for expensive setup

### 10. Playwright CI & Advanced (MEDIUM)

- `pw-network-mocking` — Use `page.route()` to intercept/stub network requests for deterministic E2E tests
- `pw-visual-regression` — Screenshot specific components with `toHaveScreenshot()` + explicit thresholds (cross-ref `snap-review-updates`)
- `pw-ci-config` — Browser projects, retries, `trace: 'on-first-retry'`, artifact upload, `--shard` (cross-ref `ci-test-splitting`)

### 11. pytest Fundamentals (HIGH)

- `pytest-fixtures` — Fixture scope (function/class/module/session), yield for teardown, fixture composition, autouse sparingly
- `pytest-parametrize` — `@pytest.mark.parametrize` for data-driven tests, indirect fixtures, `ids` for readable output
- `pytest-conftest` — conftest.py layering and discovery rules, scope-appropriate placement, keep test-specific fixtures local
- `pytest-mocking` — `monkeypatch` for env vars/attrs/dicts, `pytest-mock`'s `mocker` fixture, preference hierarchy vs raw `unittest.mock`

### 12. pytest Advanced Patterns (MEDIUM)

- `pytest-async` — anyio for async tests, `@pytest.mark.anyio`, async fixtures, strict mode. Cross-ref: python-best-practices `test-async-client` for FastAPI-specific patterns
- `pytest-markers` — Custom markers, marker registration in `pyproject.toml`, `--strict-markers`, `filterwarnings`
- `pytest-xdist` — Parallel execution with pytest-xdist, `--dist loadscope`/`loadfile`, worker-safe fixtures. Cross-ref: `ci-parallel-execution`

## Python Testing Note

For FastAPI-specific test patterns (async test clients, dependency overrides, database isolation), see the **python-best-practices** skill. The pytest rules here cover general patterns applicable to any Python project.

## Linting & Formatting

For ESLint test plugins (eslint-plugin-testing-library, eslint-plugin-vitest, eslint-plugin-playwright) and other tooling, see the **code-quality** skill.

## Full Compiled Document

For the complete guide with all rules expanded and code examples: `AGENTS.md`