SupercovDocumentation

Documentation

Getting started

Give your coding agent a prompt to measure coverage and add a test.

JavaScript

Open your project in a coding agent that can run terminal commands, then paste this prompt:

Measure code coverage with npx supercov and write one missing test.
Only change tests. Rerun the full test suite and show me the test you
added and the before-and-after coverage.

Your agent can install Supercov if needed. It runs the commands and edits the tests; you don’t need to do those steps yourself.

When it finishes, review the test change and coverage comparison in your conversation. Ask separately if you want a commit or pull request.

No account, config file, import, custom reporter, or hosted service is required. Supercov supports JavaScript, TypeScript, Rust, Python, and Ruby today.

What the agent does

The commands below show how the agent measures coverage and checks its work. You can also run them yourself if you prefer using the terminal.

1. Run your real test command

The agent runs your repository’s complete test suite through Supercov:

npx supercov -- npm test

Everything after -- is the command Supercov measures. The agent should use the same complete command your project uses before merging or deploying. If the project has several suites, tell it which one to use.

Supercov runs that command in an isolated, instrumented copy of the project. The command keeps its normal arguments, environment, output, and exit status. If one command launches several supported runners, their evidence lands in one run.

2. Read the first result

The agent reads the newest run:

npx supercov runs latest

The summary answers three practical questions:

  1. Did the test command pass?
  2. How much behavior did the suite cover?
  3. Is anything genuinely uncovered, or was some code impossible to measure?

An uncovered gap is a candidate for a test. A measurement limit is different: it means Supercov cannot honestly account for that code yet. Do not try to test away a measurement limit.

3. Choose one useful gap

The agent asks for a short list of gaps, then inspects one file. It uses your project’s file paths in place of the examples:

npx supercov runs latest gaps --limit 10
npx supercov runs latest file app/checkout/session.js

It can use more specific queries to understand the gap:

npx supercov runs latest decision app/checkout/session.js:64
npx supercov runs latest line app/checkout/session.js:64

file is usually the best place to start. decision explains missing boolean outcomes and MC/DC witnesses. line shows the obligations and tests associated with one source line.

4. Add a test and prove the gain

The agent writes one focused test with a meaningful assertion. It then reruns the same complete command and compares the two runs:

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

A useful change leaves the suite passing and shows the expected gain without an unexplained loss elsewhere. Review what the new test actually checks, not just the percentage.

For a recorded example and prompts for longer runs, see Agent workflow.

Environment requirements

These requirements apply wherever the agent runs commands: your machine, a container, or a remote workspace. The agent can check them and tell you if anything is missing.

  • macOS (arm64 or x64), Linux (arm64 or x64, glibc 2.28 or newer or musl), or Windows (arm64 or x64);
  • Node.js 22 or newer when using the npm package;
  • a working test command, including its dependencies, environment variables, and any local services;

The agent can use npx supercov. The npm package downloads the native CLI for your operating system and architecture; nothing is compiled on install. Package installation may access its registry. Supercov itself does not upload your source or coverage evidence to a Supercov service.

Files and cleanup

Completed runs live under .supercov/runs/. Supercov also keeps an isolated workspace for instrumented builds. These files are local and ignored by Git. Supercov does not rewrite your source, tests, imports, runner configuration, dependencies, or ordinary build output.

npx supercov clean --dry-run   # preview what would be removed
npx supercov clean --keep 20   # keep the 20 newest runs
npx supercov clean             # remove all runs and the build cache

If the first run does not look right, go to Troubleshooting before changing the project.

Next