# Testing

> Meaningful testing strategy and coverage guardrails Use when this capability is needed.

- Skill: `tomevault-io/testing-55` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/testing-55`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/testing-55/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/testing-55

---


# Testing Skill

Testing guidance focused on durable behavior and maintainable feedback loops.

## Core Principles

- Tests protect durable contracts, invariants, and failure modes.
- Prefer tests that still matter after refactors, removals, and package moves.
- Coverage informs risk; it is not a target to game.

## Choose the Right Test Level

- Unit tests: deterministic domain logic, pure transformations, validation rules.
- Integration tests: seams between transport, domain, storage, and adapters.
- End-to-end tests: critical user/system paths only.
- During architecture-first refactors, favor seam/integration coverage around stable contracts before cutover.

## Test-First Guidance (Not Ceremony)

- Prefer test-first when it clarifies behavior or de-risks implementation.
- For large refactors or testability seam setup, it is acceptable to reshape code first, then add or adjust tests before declaring the change done.
- Do not create ceremonial failing tests for behavior intentionally removed.
- When behavior is removed, delete stale tests and replace them only with tests for the new intended contract.

## Durable Assertion Heuristics

- Start with a user-visible contract: what should render, enable, redirect, or block.
- Prefer positive assertions (`contains`, state transitions, status, links) over absence assertions.
- Use negative assertions only for explicit invariants (security/privacy/protocol/mutual exclusion).
- Every allowed negative assertion should include an adjacent `// Invariant: ...` rationale.

Example:

- Weak assertion: "response does not contain class `foo`."
- Strong assertion: "HTMX response returns fragment content and does not include a full HTML document wrapper (`Invariant:` protocol contract)."

## Coverage Guardrails

- Use `make cover` and `make cover-critical-domain` only when you need focused
  standalone coverage diagnostics outside the normal verification workflow.
- If coverage drops, explain whether risk changed and add targeted tests when needed.
- If you introduce generated outputs, update `COVER_EXCLUDE_REGEX` in `Makefile` so coverage reflects hand-written code.

## Verification

- Use the public verification surface from `docs/running/verification.md`:
  - `make test` during normal implementation
  - `make smoke` when runtime paths need quick feedback
  - `make check` before pushing or updating a PR
- Do not run `make cover*` in parallel with `make check`; `make check` already
  generates the shared coverage artifacts.
- When a verification command is running in the background, inspect
  `.tmp/test-status/` instead of repeatedly re-running or blindly polling the
  process.
- Use `.tmp/test-status/test/status.json` for `make test`.
- Use `.tmp/test-status/smoke/status.json` for overall `make smoke` stage
  progress.
- Use `.tmp/test-status/smoke/integration/status.json` and
  `.tmp/test-status/smoke/scenario/status.json` for lane-specific `make smoke`
  progress.
- Use `.tmp/test-status/check/status.json` for `make check` stage progress.
- If `make check` is in `check-runtime`, read
  `.tmp/test-status/check-runtime/scenario/status.json`.
- If `make check` is in `check-coverage`, read `.tmp/test-status/cover/status.json`
  and the nested shard status files under `.tmp/test-status/cover/`.
- Treat `state`, `current_stage`, `current_package`, `current_test`,
  `packages_completed`, `packages_running`, `updated_at_utc`, and
  `last_event_at_utc` as the primary fields for liveness and progress.
- If a command cannot run locally, report why and what risk remains.

## Removal Policy

- Do not preserve tests that only assert a removed feature, path, or section stays gone.
- If no durable invariant remains after a removal, delete the stale test.
- If a negative assertion must remain, add an adjacent `Invariant:` rationale.

## Testability

See `docs/architecture/policy/testing-policy.md` for constructor, dependency injection, and fake-oriented testability guidance.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/louisbranch) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-16 -->