Coverage for coding agents and software factories 🌙
Supercov gives your coding agent the next useful test to write. It runs the test command you already use, records local coverage evidence, and turns uncovered paths into small, actionable queries. Your agent writes a focused test, reruns the suite, proves what improved, and keeps going while useful gaps remain.
No account, config file, import, custom reporter, or hosted service is required. Supercov is local, free, open source, and MIT licensed.
Website · Documentation · npm · GitHub
Supported by Supercorp.
Agent workflow: ask your coding agent to add a test in your own project, with a recorded example to follow along.
Start with the suite you already have
Other ways in, all the same binary at the same version: brew install supercorp-ai/tap/supercov, or for a Go project go run github.com/supercorp-ai/supercov/cmd/supercov@latest.
Everything after -- is your test command. Supercov runs it without changing your source, tests, runner configuration, or normal build output.
Then ask what is still uncovered:
After your agent adds a test, rerun the complete suite and prove the gain:
Use whichever complete test command the repository already trusts:
Map what assertions check
Each normal test run creates an assertion map automatically. An agent can optionally fill in what the assertions check:
# Pin the returned run ID. Inspect assertions and the source that ran:
# Edit assertions.json, then validate and acknowledge:
# Copy examined expectedBasis tokens into assertions.json; save again.
After code or tests change, run the same test command again. Supercov reuses the
newest available map for that command and language and identifies dirty flows. Rust owns
validation, change tracking and reporting; the agent supplies semantic reasoning.
The score is agent-assessed and separate from MC/DC. See
assertion maps for the format and JS/TS limits, or run
supercov docs assertion-agent for the agent workflow. supercov assertions schema
exports the editor schema; assertions validate --file <path> checks JSON syntax.
Give Supercov a job
Paste one of these prompts into Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, or any coding agent that can run terminal commands.
Write the first useful test
Measure code coverage with `npx supercov`. Use the coverage evidence to choose
one useful missing test. Only edit tests. Run the repository's complete test
suite through Supercov again and report what improved.
Use leftover tokens on coverage
Measure code coverage with `npx supercov` and write tests til 100%. Only edit
tests. Keep going while useful gaps remain.
Run the repository's complete test suite through Supercov. Use
`npx supercov runs latest gaps --limit 5` to choose one useful target at a
time. Write a focused test, rerun the same complete suite, and use
`npx supercov diff <previous-run-id> latest` to verify the gain.
Never weaken assertions or change application code to make coverage easier.
Stop if the suite fails, the evidence is incomplete, or no useful gaps remain.
The agent loop
- Run the real suite. Supercov executes the command after
--in an isolated workspace. - Find one useful gap. Short, paginated queries show uncovered files, lines, branches, decisions, and value paths without loading a large HTML report into context.
- Write one focused test. The coding agent changes tests—not application code or coverage configuration.
- Rerun and prove the gain.
diffshows exactly what the new test covered. - Repeat while useful gaps remain. Failed tests, incomplete evidence, or ambiguous scope stay visible instead of being rounded away.
Supercov supplies the coverage signal and evidence. It does not host, schedule, or replace your coding agent.
Use leftover tokens on coverage
Before a reset—or overnight—turn idle agent time into coverage that stays with the repository. Each pass closes a small number of useful gaps and finishes with evidence that the tests still pass and coverage improved.
Use it in a software factory
Add Supercov as a repeatable quality loop in an automated software factory. Your factory schedules the work; Supercov gives each agent a bounded next task and an immutable record of the result.
Every pass runs the real suite, chooses an uncovered path, writes a focused test, reruns, and proves the gain. Fresh executable evidence lets agents keep iterating around the clock while failed tests and regressions stop the loop before they ship.
Coverage agents can act on
From lines and branches to MC/DC, every gap becomes a concrete test target. Supercov measures:
- lines, statements, functions, and branches;
- MC/DC independence witnesses;
- optional-chain, default-value, and logical-assignment paths;
try/catchand zero-iteration control-flow paths; and- per-test provenance where the runner exposes exact test boundaries.
The denominator comes from source structure before the run, so adding or removing tests cannot silently change what 100% means. Ambiguous source scope, uninstrumented code, and missing evidence remain visible as completeness blockers.
Install for your language
The same binary ships through each language's own package manager, at the same version, from one release:
&& && pip install supercov-cli and gem install supercov install a wheel or gem that carries the binary for your platform; nothing is compiled. cargo binstall downloads that same binary from the GitHub release, while plain cargo install supercov builds it from source and needs Rust 1.95.
Supported languages
| Language | Status | Start with |
|---|---|---|
| JavaScript | Available | npx supercov -- npm test |
| TypeScript | Available | npx supercov -- npm test |
| Rust | Available | npx supercov -- cargo test |
| Python | Available | npx supercov -- pytest |
| Ruby | Available | npx supercov -- rspec |
| Go | Available | npx supercov -- go test ./... |
| Java | Available | npx supercov -- mvn test |
| Kotlin | Available | npx supercov -- ./gradlew test |
| Zig | Coming soon | — |
| PHP | Coming soon | — |
| C | Coming soon | — |
Supercov requires Node.js 22 or newer. Rust support currently uses Rust 1.95; cargo-nextest 0.9.138 and 0.9.140 are supported. Python support requires CPython 3.12 or newer and measures pytest and unittest runs. Ruby support requires Ruby 3.3 or newer (3.4 or newer for full measurement) and measures RSpec, Minitest, test-unit and Cucumber runs. Go support requires Go 1.22 or newer and measures go test. Java and Kotlin support requires a JDK 17 or newer with Maven or Gradle, and measures every JUnit Platform engine -- JUnit 5, JUnit 4 through Vintage, Kotest and Spock -- as well as TestNG.
Supported operating systems and architectures
The CLI is a single native binary. npx supercov selects the build for the machine it runs on; nothing is compiled during installation.
| Operating system | Architectures | Notes |
|---|---|---|
| macOS | arm64 (Apple silicon), x64 (Intel) | macOS 11 or newer |
| Linux | arm64, x64 | glibc 2.28 or newer (Debian 10, Ubuntu 18.10, RHEL 8 and later), or musl (Alpine); chosen automatically |
| Windows | arm64, x64 | Windows 10 or newer |
JavaScript, TypeScript, Python, Ruby, Rust, Go, Java and Kotlin suites are verified on Linux, macOS and Windows -- CPython 3.12, 3.13 and 3.14, Ruby 3.3, 3.4 and 4.0, and Go 1.22 and 1.25 on every one, and JDK 17 and 21 on every one that has them (Temurin publishes no 17 for arm64 Windows, so that pairing is 21 alone). Containers, VMs, and remote executors run the same Linux builds. Every release publishes the same binaries to npm, PyPI (supercov-cli, a wheel per platform) and RubyGems (supercov, a gem per platform except arm64 Windows, which Ruby has no platform for), and the source to crates.io (supercov).
Supported test suites
Supercov uses exact per-test attribution where an adapter is available. For other supported runners, it reports aggregate structural coverage instead of guessing which test covered a path.
| Runner | Coverage attribution |
|---|---|
| Playwright | Exact per test, worker, retry, outcome, action, and assertion phase |
| Vitest | Exact per test, with setup execution kept separate |
| Jest | Exact per test, including parameterized tests; exact expect occurrence identity for assertion maps |
node:test |
Exact per test |
| AVA and Mocha | Aggregate structural coverage |
| Cargo's standard libtest runner | Exact test, attempt, and passing-assertion identity |
| rustdoc doctests | Exact per doctest |
| cargo-nextest | Exact test, attempt, retry, and binary identity |
| RSpec | Exact example and before/example/after phase identity |
| Minitest and test-unit | Exact test and setup/test/teardown identity |
| Cucumber | Exact scenario and hook-phase identity |
Supercov works with Vite, Next, Turbopack, Webpack, esbuild, SWC, and projects with no build step. One command can collect evidence from several supported runners into a single run.
See Supported languages and test suites for exact compatibility and attribution boundaries.
Read the result
# Recent runs and the latest summary
# The most useful open coverage obligations
# Details for a file or source location
# What changed between two runs
Collections accept --limit and --offset and print a copyable next-page command. Machine-readable output is available with --json when an integration needs it.
Local, private, and zero-edit
Everything Supercov writes lives under one hidden .supercov/ directory: run evidence in .supercov/runs/<run-id>/ and the isolated build cache in .supercov/workspaces/. It ignores itself in Git, so there is nothing to add to your .gitignore.
The Supercov CLI does not contact a Supercov service during a coverage run. Package tools such as npx may contact the npm registry to download Supercov when it is not already cached.
Supercov does not rewrite your source files, tests, imports, reporter list, runner configuration, dependency tree, or normal build output. An existing user-created supercov/ directory is never adopted.
Documentation
- Getting started
- Agent workflow
- Understanding assertions
- Troubleshooting
- CLI reference
- Supported languages and test suites
- Understanding coverage
- Runs and evidence
- Files, privacy, and cleanup
- Trusting a result
- Speed and storage
Free and open source
MIT licensed. Inspect, extend, and run it anywhere.