# Read an HTML code coverage report without being misled

Canonical: https://githtml.com/guides/read-html-code-coverage-reports
Published: 2026-10-10
Publisher: WaveTech LLC / gitHtml

An HTML coverage report shows which lines and branches ran during tests, file by file. Read it to find untested risky code, not to grade quality: coverage proves execution, not correct assertions. Start from the files a change touched, look for missed branches in error handling and boundaries, and compare against the diff rather than the overall percentage.

## Generate the report locally

Each ecosystem has a command that writes HTML. coverage.py writes an htmlcov folder with an index page and one page per source file. c8 and nyc write into coverage when you choose the html reporter; Istanbul's lcov reporter also produces HTML in coverage/lcov-report. Jest accepts any Istanbul reporter. Go writes a single coverage.html containing every file.

Run these on your machine and commit the report only if reviewers need it away from a terminal. The folder-based reports are multi-file sets, so keep the directory structure intact.

````bash
# Python
coverage run --branch -m pytest
coverage html --skip-covered      # writes htmlcov/index.html

# Node with c8
c8 --reporter=html --reporter=text node --test

# Jest
npx jest --coverage --coverageReporters=html

# Go
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html
````

## What the colors mean

Covered lines ran at least once. Missed lines never ran. Partial branches, shown when branch measurement is on, mean a condition went one way but not the other, such as an if statement that was always true. Branch coverage usually lowers the percentage, because each destination of a decision counts separately, and it is the more useful signal for review.

Go's report has an inexact edge worth knowing: its blog notes that a statement like f() && g() is not instrumented per call. Count mode, enabled with -covermode=count, shows how often lines ran, which helps spot hot paths with suspiciously few test hits.

## A focused review pass

The overall number is the least informative part of the report. Google's testing blog points out that coverage only guarantees code was executed by a test, not that it was checked. Spend the review on the code that changed and on paths where a missed case is expensive.

1. Open only the files touched by the change under review.
2. Look for missed or partial branches in error handling, retries, permission checks, and input validation.
3. For each covered risky line, find the test and confirm it asserts an outcome, not just that no exception occurred.
4. Ignore missed lines in generated code or trivial accessors unless they hide logic.
5. Write findings as specific requests, such as add a test where the token is expired, rather than raise coverage.

## Reading reports on a phone

Coverage reports use JavaScript for sorting, filtering, and in Go's single file, switching between source files with a dropdown. In gitHtml those scripts are off by default, so the coverage.py and Istanbul per-file pages are the practical reading units; open the file page you care about directly. For a phone-friendly summary, have the author add a short HTML note listing the changed files, their branch coverage, and the specific gaps, with links to the per-file pages.

## Sources and further reading

- [coverage.py: HTML reporting](https://coverage.readthedocs.io/en/latest/commands/cmd_html.html)
- [coverage.py: Branch coverage measurement](https://coverage.readthedocs.io/en/latest/branch.html)
- [c8: native V8 code coverage](https://github.com/bcoe/c8)
- [The Go Blog: The cover story](https://go.dev/blog/cover)
- [Google Testing Blog: Code Coverage Best Practices](https://testing.googleblog.com/2020/08/code-coverage-best-practices.html)

## Related guides

- [Review test coverage by reading assertions, not percentages](https://githtml.com/guides/review-test-coverage-by-assertions)
- [Write evidence-backed technical review findings](https://githtml.com/guides/write-evidence-backed-code-review-findings)
- [Triage a technical review from your phone without over-approving](https://githtml.com/guides/triage-technical-review-from-phone)
- [Review architecture boundaries from a phone without losing context](https://githtml.com/guides/review-architecture-boundaries-on-phone)

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