# testing-conventions

> Enforce testing conventions in CI

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

## Table of Contents

### Tutorials

- [Getting Started](https://thekevinscott.github.io/testing-conventions/getting-started.md): Adopt the full standard on a repository — add one workflow file, watch a check go red on a pull request, fix it, and watch it go green.
- [Adopt on a Monorepo](https://thekevinscott.github.io/testing-conventions/monorepo.md): Adopt the standard on a monorepo — one workflow call per package, scoped by `source`.

### How-to Guides

- [Respond to a red check](https://thekevinscott.github.io/testing-conventions/guide/configure.md): Respond to a red check in testing-conventions.toml — relax a coverage floor or exempt a file or line with a required reason.

### Reference

- [Workflow](https://thekevinscott.github.io/testing-conventions/reference/workflow.md): The reusable GitHub Actions workflow — every input, every check and its run condition, and the @v0 versioning contract.
- [Configuration](https://thekevinscott.github.io/testing-conventions/reference/config.md): The testing-conventions.toml schema — every coverage key and its default, the exemption schema, and the shared test configs.
- [Glossary](https://thekevinscott.github.io/testing-conventions/reference/glossary.md): The repo's standard for check, rule, and gate — three words with one meaning each, and the named exceptions where a fourth population borrows one of them.
- [Checks](https://thekevinscott.github.io/testing-conventions/reference/checks.md): The GitHub Actions jobs the workflow runs — one page per job, each carrying the check(s) it runs, its run conditions, and links to each check's complete record.

#### Checks

- [Static checks](https://thekevinscott.github.io/reference/checks/static-checks.md): The Static checks job — one job per language bundling the four source-scanning checks (colocated-test, one-function-per-file, unit-lint, integration-lint) as steps; what each step is, why they share a job, and how to read a red run.
- [`colocated-test`](https://thekevinscott.github.io/reference/checks/colocated-test.md): The colocated-test check — every source file has a colocated, matching-named unit test, and on a pull request a changed source changes its test with it.
- [`one-function-per-file`](https://thekevinscott.github.io/reference/checks/one-function-per-file.md): The one-function-per-file check — a file holds one substantial function; the threshold, what counts as a function, the per-language defaults, and the exemption.
- [`unit-lint`](https://thekevinscott.github.io/reference/checks/unit-lint.md): The unit-lint check — every collaborator in a unit test is mocked; the first-party/external line, the per-language rules, and their exemptions.
- [`integration-lint`](https://thekevinscott.github.io/reference/checks/integration-lint.md): The integration-lint check — integration and e2e tests run first-party code for real; the suite tiers it scans, the per-language rules, the hygiene lints, and unknown-tier.
- [`unit-coverage`](https://thekevinscott.github.io/reference/checks/unit-coverage.md): The unit-coverage check — the unit suite clears a 100% floor per language, whole-tree and over a pull request's changed lines; every key, default, and the line-scoped exemption.
- [`mutation`](https://thekevinscott.github.io/reference/checks/mutation.md): The mutation check — a binary gate, not a score: no unexplained surviving mutant on a pull request's changed lines; the engines, timeouts, and the line-scoped exemption.
- [`packaging`](https://thekevinscott.github.io/reference/checks/packaging.md): The packaging check — the built artifact ships no test files: what each registry's artifact is scanned for, the derived build per language, and the three ways the job gets an artifact.
- [`workflow-lint`](https://thekevinscott.github.io/reference/checks/workflow-lint.md): The workflow-lint check — a GitHub Actions `run:` or `github-script` body must be wiring, not a program. Covers the markers that make a body logic, the glue ceiling, which files are scanned, and why there is no exemption.
- [`e2e-verify`](https://thekevinscott.github.io/reference/checks/e2e-verify.md): The e2e-verify check — a branch that changes the scoped source records one visible e2e decision: the attest/verify pair, the two diff questions, and the extra-scope keys.
- [`changelog`](https://thekevinscott.github.io/reference/checks/changelog.md): The changelog check — a pull request that changes a package's public surface adds a changelog fragment and, where the repository keeps one, a migration fragment. Covers fragment discovery, the two layouts, the filename convention, and the bypass.

### Explanation

- [The testing model](https://thekevinscott.github.io/testing-conventions/explanation.md): The testing model the checks encode — the three kinds of test, the unit ladder, and why it's built to resist gaming.
- [Colocated tests](https://thekevinscott.github.io/testing-conventions/explanation/colocated-test.md): Why every source file carries a colocated, matching-named unit test — and why a changed source must change its test with it.
- [One function per file](https://thekevinscott.github.io/testing-conventions/explanation/one-function-per-file.md): Why a file holds one substantial function — and why the line threshold that decides "substantial" is yours to set.
- [Coverage](https://thekevinscott.github.io/testing-conventions/explanation/coverage.md): Why the coverage floor is a strict 100% with reasoned exemptions — and how the same floor is measured over a pull request's changed lines.
- [Mutation](https://thekevinscott.github.io/testing-conventions/explanation/mutation.md): Why mutation testing is the verification rung coverage can't reach, why the gate is binary, not a score, and the engines that run it.
- [Isolation](https://thekevinscott.github.io/testing-conventions/explanation/isolation.md): Why unit and integration tests mock opposite things — the first-party/external line, and what the two lint checks flag per language.
- [Packaging](https://thekevinscott.github.io/testing-conventions/explanation/packaging.md): Why test files never ship in the built artifact — the cost colocation imposes, and how the packaging check settles it per registry.
- [E2E attestation](https://thekevinscott.github.io/testing-conventions/explanation/e2e.md): Why CI never runs the e2e suite — and how the attest/verify pair nudges one visible e2e decision out of every branch that changes the code.
- [Scoping and exemptions](https://thekevinscott.github.io/testing-conventions/explanation/scoping.md): How the scan is scoped and how a deliberate omission is recorded — path scopes, exemptions name, and there is no ignore-glob.