supercov-cli 0.0.45

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

npx supercov -- npm test

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:

npx supercov runs latest gaps --limit 10

After your agent adds a test, rerun the complete suite and prove the gain:

npx supercov -- npm test
npx supercov diff <previous-run-id> latest

Use whichever complete test command the repository already trusts:

npx supercov -- npx playwright test
npx supercov -- pnpm test:e2e
npx supercov -- cargo test
npx supercov -- cargo nextest run
npx supercov -- pytest
npx supercov -- python -m unittest
npx supercov -- bundle exec rspec

Map what assertions check

Each normal test run creates an assertion map automatically. An agent can optionally fill in what the assertions check:

npx supercov runs latest assertions --json
# Pin the returned run ID. Inspect assertions and the source that ran:
npx supercov runs <run> assertion <assertion-id>
npx supercov runs <run> source src/example.ts
# Edit assertions.json, then validate and acknowledge:
npx supercov runs <run> assertions validate --json
# Copy examined expectedBasis tokens into assertions.json; save again.
npx supercov runs <run> assertions check --require-mappings --require-observed --json
npx supercov runs <run>  # includes the assertion percentage in the regular report

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

1. Run the real suite. Supercov executes the command after -- in an isolated workspace.
2. Find one useful gap. Short, paginated queries show uncovered files, lines, branches, decisions, and value paths without loading a large HTML report into context.
3. Write one focused test. The coding agent changes tests—not application code or coverage configuration.
4. Rerun and prove the gain. diff shows exactly what the new test covered.
5. 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/catch and 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:

npx supercov -- npm test                          # npm
uvx --from supercov-cli supercov -- pytest        # PyPI
gem install supercov && supercov -- bundle exec rspec   # RubyGems
cargo binstall supercov && supercov -- cargo test  # crates.io

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

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.

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.

JavaScript, TypeScript, Python, Ruby and Rust suites are verified on Linux, macOS and Windows -- CPython 3.12, 3.13 and 3.14, and Ruby 3.3, 3.4 and 4.0 on every one. 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.

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
npx supercov runs --limit 5
npx supercov runs latest

# The most useful open coverage obligations
npx supercov runs latest gaps --limit 10

# Details for a file or source location
npx supercov runs latest file app/checkout/session.ts
npx supercov runs latest decision app/checkout/session.ts:64
npx supercov runs latest line app/checkout/session.ts:64

# What changed between two runs
npx supercov diff <previous-run-id> latest

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.

npx supercov clean --dry-run   # preview cleanup
npx supercov clean --keep 20   # keep the 20 newest runs
npx supercov clean             # remove all runs and the build cache

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.