# Review test coverage by reading assertions, not percentages

Canonical: https://githtml.com/guides/review-test-coverage-by-assertions
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

A useful test review asks what behavior each assertion protects and which failure it would detect. Inspect setup, assertions, and important boundaries rather than relying on test names or coverage percentages. Distinguish an existing test from one that actually ran successfully, and record the risks that remain outside the review.

## Choose a risk and follow its evidence

An illustrative risk is duplicate submission creating duplicate records. Start with that behavior, then locate tests that claim to address it. The Practical Test Pyramid offers context for selecting different test levels, but no fixed shape proves that a particular risk is covered. Read the setup to see whether it represents the relevant conditions. A test named prevents duplicates may only verify that a button becomes disabled, leaving the persistence behavior unexamined. The review should describe this gap without dismissing the useful interface check.

## Inspect the assertion and its failure mode

Ask what change would make the test fail. If the assertion checks only that a function returns something, it may not protect the invariant named in the test. Review boundary values, error paths, and isolation from unrelated state. Distinguish a realistic integration dependency from a mock that guarantees the result under discussion. An illustrative checklist for the duplicate case includes repeated requests, concurrent attempts when relevant, and a failed first attempt followed by retry. These are review prompts, not a universal requirement for every feature.

1. Risk: name the user-visible failure the test is meant to detect.
2. Assertion: identify the exact property checked and its meaningful failure condition.
3. Boundary: record important cases that are covered, missing, or outside scope.

## Keep review findings reproducible

Link to test and implementation at the reviewed revision. If you run tests in an authorized local environment, record the command and result; if you only read them, say so. Avoid equating a source review with a passing test suite. Prioritize missing protection by consequence and propose the smallest useful follow-up. For a phone-friendly HTML summary, show the risk, evidence, and gap in short sections, with long output in a separate appendix. gitHtml reads that report but does not execute tests or calculate coverage.

## Sources and further reading

- [Martin Fowler: The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html)
- [GitHub Docs: Getting permanent links to files](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files)

## Related guides

- [Trace data flow through a technical review document](https://githtml.com/guides/trace-data-flow-in-technical-review)
- [Review a PostgreSQL query-plan report safely](https://githtml.com/guides/review-postgresql-query-plan-report)
- [Review performance claims without being fooled by one fast run](https://githtml.com/guides/review-performance-claims-with-distributions)
- [Review an asynchronous job design for retries and ownership](https://githtml.com/guides/review-asynchronous-job-design)

Editorial approach: https://githtml.com/guides/about