# Testing Best Practices > Use when designing tests, writing test cases, or planning test strategy for a module. Covers unit, integration, and e2e layering. - Skill: `tomevault-io/testing-best-practices-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/testing-best-practices-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/testing-best-practices-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/testing-best-practices-2 --- ## Test layering policy ### Unit tests Purpose: verify individual functions and invariants in isolation. - **Data-driven**: parameterized tables covering happy path, boundary, error, and edge cases. - **Property-based**: fuzz invariants that must hold across all inputs (e.g., idempotency, sort stability, roundtrip serialization). - Derive cases from the module's public API surface: input types/constraints, output shape, error modes, invariants. ### Integration / contract tests Purpose: verify interactions between components and external services. - **API envelope**: request/response shape, status codes, content types, pagination. - **Error contract**: error codes, error shapes, rate limiting, retries. - **Auth and scoping**: token validation, role-based access, tenant isolation. - **Eventual consistency**: verify convergence within bounded time; poll rather than sleep. - Reuse auth state across tests where possible; avoid redundant login flows. ### E2E tests Purpose: verify real user workflows through the full stack. - No mocks; exercise real services, databases, and APIs. - Happy-path workflows only; save edge cases for lower layers. - **State-tolerant**: never assume a clean slate; tolerate and work with prior state. - **Idempotent**: safe to run repeatedly without cleanup between runs. - **Flow-oriented**: validate real data paths end-to-end rather than isolated assertions. ## Hard rules - **Never invent signatures, source locations, or line numbers.** Only reference what you have read from the codebase. - **No fabricated fixtures.** Derive test data from actual schemas, types, or seed data in the repo. - **No test-only hacks in product code.** No `if (process.env.TEST)` branches, no test-specific exports, no test backdoors. - **E2E must not rely on clean slate.** Tests must tolerate pre-existing data, prior test runs, and shared environments. ## Execution guidance ### Preflight checks (before e2e) 1. Verify the target environment is reachable (health endpoint, ping). 2. Confirm required services are running (database, API, auth provider). 3. Validate test user / credentials exist and are functional. 4. Check for leftover state that could cause false failures; log it, do not fail on it. ### Deterministic fixtures - Use seeded randomness for generated data (seeded faker, deterministic UUIDs). - Fixtures should be self-contained; avoid cross-test fixture dependencies. - Prefer factory functions over shared mutable fixture objects. ### Async handling - Poll with bounded timeout and backoff; never use fixed `sleep`/`waitForTimeout`. - Set explicit timeout per operation; fail fast with a descriptive message on timeout. - Bound retry attempts (e.g., max 3 retries with exponential backoff). - Use framework-native waiting (Playwright `expect`, async assertions) over manual loops. ### Flake handling - **Single infrastructure retry** per test run; if it fails twice, it is not flake. - On retry failure, collect diagnostics: screenshots, network logs, service health, timestamps. - Classify the failure (flaky / outdated / bug) before attempting a fix. - Never add arbitrary delays or retry loops as a flake "fix." ## API surface discovery Before generating test cases: - Read the module source to enumerate exports/public functions. - Confirm scope from the user request and inspected code context; if ambiguous, state assumptions and proceed conservatively. - For each function: input types/constraints, output shape, error modes, invariants. - Probe for state dependencies and ordering constraints between functions. ## Output format Use markdown. Produce three sections: **Test Strategy** -- one bullet per layer (unit/integration/e2e) naming the functions/flows and their coverage type. **Test Matrix** -- table per function: columns `ID | Category | Name | Input | Expected`. Case ID scheme: `{CATEGORY}-{NN}` (HP, BV, ERR, EDGE). Append-only; never renumber. **Implementation Plan** -- ordered steps: fixtures, unit tests, integration tests, e2e flows, run command. ## CI guidance ### Fast PR smoke lane - Unit tests + linting + type-check on every PR. - Subset of integration tests covering critical contracts. - Target: under 5 minutes. ### Nightly full lane Full unit + integration + e2e suite with higher property-based iteration counts. Flag tests that pass on retry but failed initially. ## Workflow 1. Spec or code defines the module behavior (types, constraints, API surface). 2. Agent (with this skill) produces test strategy, matrix, and implementation plan. 3. test-writer agent translates the plan to runnable code in the target language's idiom. 4. Developer implements to pass the tests. 5. If implementation reveals missing cases, propose them first; append to spec only when explicitly requested. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/0xbigboss) — claim your Tome and manage your conversions.