Speed and storage

A Supercov run includes your test command and evidence publication, and for a compiled language an instrumented build, which repeated passes can reuse when the relevant inputs have not changed. A JavaScript project has no such build: the command runs as given, and a build inside it is part of the command's time.

See where the time went

npx supercov runs latest

The summary separates:

The line Supercov prints when a run ends also reports publication: analysing the evidence once for the stored query views, the summary and the assertion map. That is why the first query after a run opens at once rather than analysing the evidence itself.

Installing or first invoking the selected package may also download it. That download happens before Supercov starts and is not coverage-engine overhead.

Keep an agent loop fast

• Keep the isolated build cache between passes.
• Avoid changing dependencies, build configuration, or toolchains during the loop unless the test requires it.
• Query the stored run instead of rerunning merely to open another view.
• Write one related test at a time, then rerun.
• Use a focused test command while iterating when appropriate, but finish with the same complete command used for the baseline.

Supercov reuses an instrumented build only when source, dependencies, configuration, toolchain, build mode, and instrumenter identity match. A possible mismatch triggers a fresh build rather than risking stale coverage. A build inside a JavaScript project's command is the command's own and runs every time, as it does without Supercov.

Use focused runs carefully

A narrow test command can shorten the inner loop:

npx supercov -- npx vitest run app/checkout/session.test.js

That run has a narrower evidence set than the complete suite. Before reporting success, rerun the repository’s full command and compare against a full-suite baseline.

Measure overhead in your project

Compare the original and wrapped command under similar cache conditions:

/usr/bin/time -p npm test
/usr/bin/time -p npx supercov -- npm test

Alternate the two commands several times and compare typical runs. Do not compare a cold package, browser, build, or VM cache with a warm one. Supercov never runs the test command a second time automatically because suites may write data, call paid services, or be intentionally non-repeatable.

Python subprocesses

Interpreter count matters as well as test count. Each child initializes the Python runtime before executing user code, so a suite that launches thousands of short-lived interpreters can have more overhead than a single-process suite with the same number of tests. Tight child-startup deadlines can also expire before the child produces its first output.

Supercov prepares the run’s probe index once and lets later interpreters load file and decision data as needed. The compiled-module cache is separate: it avoids compiling unchanged measured source, while the prepared index avoids repeatedly parsing and indexing the entire coverage plan.

Optional unittest and concurrency adapters install when their libraries are imported, rather than importing those libraries into every helper process. Libraries already loaded when measurement starts are patched immediately.

For development, python3 scripts/python-startup-benchmark.py measures cold initialization and repeated child startup against a synthetic plan. Use --runtime /path/to/checkout/runtime/python to compare implementations. This isolates startup cost; it does not predict a complete suite’s slowdown, which also includes measured execution, concurrency and evidence publication.

For an end-to-end subprocess workload, build a release binary and run:

cargo build --release -p supercov
python3 scripts/python-subprocess-benchmark.py \
  --output /tmp/supercov-subprocess-benchmark \
  --children 1000 --tests 400 \
  --binary candidate="$PWD/target/release/supercov"

Use a new output directory for each experiment. The fixture defaults to 321 source files and saves plain/measured timings, CLI phase timings, child latency, test outcomes and coverage summaries. Add another --binary label=/path to compare builds; measured coverage and outcomes must agree. Vary --calls for hot execution, --statements for plan size, --decision-width for wider MC/DC regions, or --workers for concurrent children. --mode noop isolates helpers that run no measured source; --mode script exercises native entry scripts and allows the corrected unmeasured-file denominator to differ between versions.

Understand disk usage

Each completed run stores compressed evidence and metadata under .supercov/runs/<run-id>/. Query views are derived from that evidence rather than stored as a full report for every filter.

Most of a large run is its query index, query-index.v1.bin: on a suite of about 400 tests with per-test evidence, 160 MB of a 216 MB run, beside 58 MB of evidence. The index is a cache. Supercov builds it again from the evidence the first time the run is queried without it, so a CI job that keeps runs as an artifact can leave it out:

tar czf supercov-runs.tgz --exclude 'query-index.v1.bin' .supercov/runs

A merged run holds a copy of each run’s evidence and an index of its own, so merging adds about as much again. To hand a run to a reviewer, the HTML report (npx supercov report) is usually the smaller artifact.

The isolated workspace may be larger because it can contain an instrumented build cache. Supercov does not delete history in the background.

npx supercov runs clean --dry-run
npx supercov runs clean --keep 20
npx supercov runs clean

Use --dry-run to preview cleanup. Keep enough run history for active reviews and automation; remove an existing build cache only when reclaiming space matters more than reusing it.

Keep assertion assessments fast and cheap

assertions assess asks only questions it has not answered before; answers live in .supercov/assertions/ and are reused across runs whenever the question is the same. --workers N raises the requests in flight (default 8) for a faster, slightly costlier pass. --dry-run prints the estimate without sending anything.