testing-conventions

Appearance

testing-conventionsEnforce testing conventions in CI

Opinionated testing standards enforcing structure, measurement, and isolation. For Python, TypeScript, and Rust.

Getting Started
Understand the checks

Getting Started

The five-minute drop-in — add one workflow file, watch a check go red on a pull request, make it green.

Start the tutorial

Adopt on a monorepo

One workflow call per package, each scoped to its own source directory, language, and config.

Adopt per package

The checks

What each check enforces and why — the three kinds of test, the unit ladder, and what makes it agent-resistant.

Understand the model

Respond to a red check

The two responses to a red check — fix the code, or record a reasoned exemption in one auditable file.

Tune a floor, exempt a file

Checks at a glance ​

Every check is a CLI command that fails CI on a violation. The checks reference carries one page per check, with its per-language behavior, run conditions, and configuration surface.

Unit

  • unit colocated-test — every source file has a colocated, matching-named unit test (Python, TypeScript, Rust); with --base, a source changed in the diff must also change its colocated test (co-change; Python, TypeScript).
  • unit one-function-per-file — a file holds at most one module-scope function whose body runs longer than the configured max_lines (Python and TypeScript by default, Rust on opt-in; default 1, so a one-line function is trivial and shares freely).
  • unit coverage — enforce a coverage floor on the unit suite (Python, TypeScript, Rust); with --base, the same floor is measured over the changed lines of a <base>...HEAD diff instead of the whole tree.
  • unit lint — a unit test mocks every collaborator: effectful out-of-module calls and imports are checked while named pure constructors and parsers are allowed; typed mocks (TypeScript).
  • unit mutation — every line a change touches is verified, not just executed: mutation testing breaks the code and requires a test to fail. It's a binary gate, not a score — diff-scoped, so only an unexplained surviving mutant on the diff fails the check (Python, TypeScript, Rust; wired into the reusable workflow as a diff-scoped, PR-only job).

Integration

  • integration lint — integration tests run first-party code for real: no first-party mock, double, or patch (Python, TypeScript, Rust); plus Python mock-mechanism hygiene (no-monkeypatch, no-inline-patch, no-environ-mutation, no-constant-patch) and the suite layout itself, where a test file under tests/ outside a standard tier is flagged (unknown-tier; Python, TypeScript).

Packaging

  • packaging — test files never ship in the built artifact (wheel, sdist, npm tarball, crate).

E2E

  • e2e attest / e2e verify — attest runs the e2e command of your choosing locally and, when it passes, records a branch-keyed receipt; verify reads the diff alone in CI, asking a branch that changed the scoped source for a receipt. An [e2e] config table joins shared source trees beside the package into the scoped diff, and carves feature-gated subtrees back out.