Appearance
Tests
This lens answers: when someone changes the code, do they change a test in the same commit? The share of changes that did is called test co-change. It shows where the habit holds and where it breaks down, by package and by file.
It isn't coverage. GitRelic never runs your tests and doesn't know which lines they execute. Its biggest limit is that it recognizes tests by file name and folder: in a repository whose tests don't match the names it knows, such as a JavaScript project with tests named order-test.js beside its code, the share comes out near zero however well tested the code is. The third example shows what that looks like. Check it before you believe a low number.
Reading the numbers
| What you see | What it means |
|---|---|
| "64% of 954 source changes shipped with a test" | Of the commits in the analyzed period that changed source code, the share that also changed a test or fixture. A source change is one commit, however many files it touched. The overview shows the same number as "64% with tests," and the portfolio as "Changes shipped with a test." |
| "services/gateway lags: 30% of its 160 changes shipped with a test." | A package more than 15 points under the repository's share, holding at least 4% of its source changes. At most two are named, the most untested work first. A package with a lower share but less work isn't named here, though you can still see it in the picture. |
| "3 files changed 5+ times never shipped with a test; the most: retry.go (21×)." | Files still in the repository, changed at least 5 times in the period, none of those times with a test in the commit. |
| "Up from 18% to 66% over the last year." | The twelve calendar months ending at the latest source change, against the twelve before. It appears when the share moved 10 points or more and each year has at least 20 source changes. It usually needs more history than the default period holds, and can mislead on the default period. |
| "30% of 160 with a test" on a package row | That package's own share and source changes. Rows won't add up to the headline: a commit touching two packages counts in both, and packages with no files left aren't listed but still count in the headline. |
| The tick on a row | Where the repository's share would fall on that row. If the accent part stops short of the tick, the package is under the repository's share, and its name is highlighted. |
| "123 of 484 untested" | Source changes in that package with no test in the commit, out of its total. This is the amount of untested work, which a percentage hides: a big package at 75% can hold more of it than a small one at 30%. |
| "With a test: 0 of 21 changes" on a file's card | That file's own count. It's marked as a warning when the count is zero and the file changed 5 or more times. Only source files that changed in the period and still exist get this row. |
| "26% of often-changed files never shipped with a test" on the lens's dot | Of the files changed 5 or more times, the share that never shipped with a test. The dot on Tests, and on Structure in the rail, appears at 15% or more with at least 3 such files. That line is a rule of thumb GitRelic picked, not an industry standard. |
| "Add tests before the next change. None of its 21 changes shipped with a test." | Advice on a file's card under What to do. It can appear for a file Hotspots rates as a warning or critical, changed at least 3 times, never with a test. |
| "No source changes to pair with tests" | Nothing to measure. The message names an empty period or an old report, but it also appears when every code file sits in the repository's root, or when the code is in a language GitRelic doesn't list (see How it's measured). It doesn't mean the repository has no tests. |
The table's tiers are by a file's share: Mostly (50% or more), Sometimes (25% up to 50%), Rarely (under 25%, at least one) and Never with a test, which includes a file changed only once.
There is no good score to aim for. Nobody has a trustworthy norm for this number across languages and team habits, and GitRelic doesn't offer one. Not every change needs a test, so 100% isn't the goal either. Compare a package with its own repository, and a repository with its own past.
Three example repositories
These repositories are invented, but each result is what GitRelic reports for commits like these.
A Go backend with one package that lags
64% of 954 source changes shipped with a test.
services/gateway lags: 30% of its 160 changes shipped with a test.
3 files changed 5+ times never shipped with a test; the most: retry.go (21×).
The inspector's list of the most untested work:
| Package | Untested | Share |
|---|---|---|
| services/api | 123 of 484 | 75% |
| services/gateway | 112 of 160 | 30% |
| services/billing | 83 of 280 | 70% |
| tools | 27 of 30 | 10% |
What it means: the team has a working habit, and services/gateway is where it breaks down. The lens's dot stays off: 3 of the 27 often-changed files is 11%, under the 15% line.
Two things here aren't obvious. tools has the lowest share but isn't named as lagging, because its 30 changes are under 4% of the repository's work. And services/api has a strong share and still holds the most untested changes, since it does the most work. A share tells you about the habit, and the count tells you how much is at stake.
What to look at: select services/gateway to see its files, then look at the ones on the floor. retry.go and tls.go changed repeatedly and never with a test. Often that means they're hard to test, or that something outside this repository tests them.
A Python repo where testing arrived
Over two years of history, with --since "2 years ago":
49% of 828 source changes shipped with a test.
Up from 18% to 66% over the last year.
5 files changed 5+ times never shipped with a test; the most: legacy_csv.py (34×).
The lens's dot reads "26% of often-changed files never shipped with a test."
The same repository on the default 12 months:
66% of 528 source changes shipped with a test.
4 files changed 5+ times never shipped with a test; the most: settings.py (16×).
What it means: the 49% describes neither period. The team moved from 18% to 66%, and the two-year number is an average of the two. The period you choose changes the answer, and a trend you can trust needs a second year to compare.
legacy_csv.py drops off the second list because it changed fewer than 5 times in the last year, so the 34 changes are mostly old news. The dot stays on in both readings. Even after the change in habit, 22% of the often-changed files in the last year never shipped with a test.
What to look at: settings.py, admin_hooks.py, retries.py and throttle.py are the files the new habit hasn't reached. A settings file may be fine as it is. Retry logic probably isn't.
A repo that looks untested and isn't
Each service keeps its tests beside its code, named like order-service-test.js. Most changes come with a test.
4% of 272 source changes shipped with a test.
9 files changed 5+ times never shipped with a test; the most: order-service.js (80×).
The lens's dot reads "90% of often-changed files never shipped with a test." The inspector's list of files changed often and never with a test:
| File | Changes |
|---|---|
| order-service.js | 80 |
| payment-service.js | 70 |
| order-service-test.js | 60 |
| payment-service-test.js | 50 |
| order-mapper.js | 40 |
What it means: this result is wrong, and the list shows why. A test file is listed as a file that never shipped with a test. GitRelic doesn't recognize names like *-test.js as tests, so it reads them as source code. The 4% comes from the few commits that also changed a JSON file under a fixtures/ folder.
What to look at: if test files appear in this lens's table, don't use its numbers for that repository. The Add tests advice and the portfolio's figure read the same numbers, so they're wrong too. These test files also count as source in other lenses, including Languages, Age, Churn, Parallel Dev and Risk.
How it's measured
GitRelic reads the commits in the analyzed period, the last 12 months by default, and sorts each one:
A source change is a commit that changed at least one file that is all of these:
- A code file by extension:
ts,tsx,mts,cts,js,jsx,mjs,cjs,py,rb,go,rs,java,kt,scala,cs,cpp,cc,c,h,hpp,php,swift,dart,vue,svelteorastro. Other languages, such as Elixir, Lua, Perl, Objective-C and shell scripts, aren't counted. - Not a test, fixture or generated file, and not a configuration file such as
vite.config.ts. - Inside a folder. A file in the repository's root isn't counted, and neither is one in a top-level dot-folder such as
.github/. So a Go library with all its code in the root has no source changes at all.
A commit that changes only tests isn't a source change, so adding tests in their own commit doesn't raise the share.
A test or fixture can be anywhere in the same commit, in any package. A change to billing/ with a test under api/tests/ counts for billing/. The file doesn't need to test the change, or even be related to it. These count:
| Kind | Matches |
|---|---|
| Test folders | Any file under __tests__/, tests/, Tests/, *.Tests/, src/test/ or cypress/, at any depth |
| Test folders at a root | Any file under test/ or spec/, at the repository's root or a package's root, such as packages/app/test/ |
| Fixture folders | Any file under __fixtures__/, fixtures/, fixture/, testdata/, __snapshots__/ or __mocks__/ |
| Test names | *.test.*, *.spec.* and *.test-d.*; files named *_test.* or *_spec.*, other than .json, .yaml, .yml, .toml, .md and .txt files; test_*.py and conftest.py; FooTest.* and FooTests.* in Java, Kotlin, Scala, Groovy, C#, F#, Visual Basic, Swift and PHP |
| Snapshots | *.snap |
Any file type counts, so tests/data.csv does, but images and fonts don't. That includes anything else in those folders: spec/openapi.yaml counts as a test, so a commit changing it counts as shipping with one. A folder name must match exactly, including its case. A generated or vendored file doesn't count, even inside a test folder.
Some test layouts aren't recognized. These are all read as source code, so they count as untested changes and appear in the table:
| Example | Why it's missed |
|---|---|
lib/test/helpers.js, pkg/spec/helpers.go | test/ and spec/ only count at a root, and the name doesn't match |
src/FooTest.cpp, src/FooTest.ts | FooTest only counts in the languages above: elsewhere it's as often a component, like ABTest.tsx |
src/foo-test.js | A dash, outside the test folders |
src/test_foo.js, src/test_foo.c | The test_ prefix only counts for Python |
Tests written inside a source file, such as a Rust #[cfg(test)] module, leave no test file to find.
Sweeps. A commit of more than 50 files, counting every file in it, is left out of the share, packages and files, because a codemod or a format pass changes tests by accident. The line is looser than Fix rate's 20 files because a 30-file feature with its tests is real evidence. The dashboard doesn't show how many commits were left out; the --json report does.
What else counts. Merge commits aren't read. Commits by bots count like any others, though a bot that changes only a lockfile isn't making a source change. --include-fixtures doesn't change this lens.
Packages are the repository's declared workspaces, else packages/*, apps/*, libs/* or services/*, else the top-level folder. A commit counts once in each package whose source it changed.
Files are listed only if they still exist. A renamed file's earlier changes sit under its old path, so they count in the headline but not in the file's row (see Renames).
The trend
The trend compares calendar months, counting back from the latest month with a source change: that month and the eleven before it, against the twelve before those.
On the default period there's usually no second year, so no trend appears. To see a real one, run with --since "2 years ago" or --since all.
There's one catch. The default period usually starts partway through a month. When the latest source change is in the current month, that partial month falls on the "before" side. If it alone holds 20 or more source changes, it's compared with the whole year after it. Its few weeks can produce a line like "Down from 100% to 40% over the last year." If you see a trend on the default period, don't trust it until you've checked it with a longer --since.
In the dashboard
Find this lens under Structure.
- Work, split by tests is the main picture. Each package is a row, most source changes first, up to 14, and a line counts the rest. A row's length is its source changes. The accent part shipped with a test and the faint part didn't, so a long faint part is a lot of untested work. Hover a row for its counts.
- Share ladder (the corner toggle) places each package by its share alone, around a line at the repository's share, with larger dots for more changes. Dots under the line are warm. Up to 14 are drawn, and the 8 with the most changes are named.
- Selecting a package shows its files.
- In Work, each file is a dot: further right for more changes, on a log scale, and higher for a larger tested share. Files that never shipped with a test sit on the floor in a warm color. The most-changed of those are named, along with the package's top files.
- In Share ladder, the files spread out under the ladder on the same share axis, sized by their changes, and only up to four never-tested ones are named. Hover any dot for its file.
- The time strip counts every commit each week, and shades the source changes that shipped with a test. Its caption gives the total of those. With a selection, it shades only the selection's.
- The inspector, with nothing selected, shows the share and the findings quoted above, then the five packages with the most untested work and the five most-changed files never shipped with a test. Selecting a package or file swaps it for that selection's general card.
- The table (
T) lists every changed source file: its package, changes, how many came with a test, the share, and the date of the last one, or "never."
Elsewhere, a file's card has the With a test row, the overview's list for this lens shows the never-tested files, and the portfolio shows each repository's share.
What it can't tell you
- Whether the code is tested. A commit that changed a test may have deleted one, skipped one or accepted a new snapshot without looking. A commit with no test change may be a rename or a fix that existing tests already cover. Read the share as a habit, not a measure of safety.
- Whether the test relates to the change. Any test in the commit counts, so a large commit with one unrelated test change scores the same as careful work.
- How a team commits. A team that squashes a feature and its tests into one commit scores higher than one that commits tests separately, with the same tests. Tests written in the next commit don't count for the change they test.
- About tests it can't see. An end-to-end suite in another repository is invisible, and the package reads as untested. So are the layouts listed above.
- How one repository compares with another. Differences in language, test layout and commit habits can outweigh any difference in testing, so a gap between two repositories in the portfolio is a reason to look, not a ranking.
Related
- Hotspots — files that are both busy and big, where a missing test costs the most.
- Fix rate — how often changes need a fix of their own lines, which is worth checking against a package's share here.
- Languages — how much of each language's code is tests and fixtures, by lines.
- Renames — where a file's history starts over.