Assertion coverage — Supercov docs

A test can run a calculation without checking its answer. Assertion coverage helps you find those cases. It works across JavaScript, TypeScript, Python, Ruby and Rust.

A passing test can miss a wrong result

This function confirms an order and calculates its total:

export function checkout(price, quantity) {
  const total = price * quantity;
  return { status: 'confirmed', total };
}

The test checks the status, but not the total:

import assert from 'node:assert/strict';
import test from 'node:test';
import { checkout } from './checkout.js';

test('confirms an order', () => {
  const order = checkout(25, 2);
  assert.equal(order.status, 'confirmed');
});

Every line runs and the test passes. It would also pass if the total were 49 instead of 50. The missing check is:

assert.equal(order.total, 50);

Now a wrong total fails the test. Line coverage hasn’t changed, but the test checks something it didn’t check before.

What Supercov and your agent each do

Supercov records which statements ran and which assertions passed in each test. Your agent reads the tests and source, then maps the assertions to the code they check. In this example, it should notice that nothing checks order.total.

Supercov checks that map against the recorded run. A statement needs a current explanation, execution and a passing assertion in the same test to count. The map is saved as assertions.json; you don’t need to write it yourself.

After a test changes, the agent reruns the suite and updates the map. Supercov reuses compatible mappings and flags explanations that need review.

Try it in your project

Paste this into your usual coding agent:

Read npx supercov docs assertion-agent. Run the full test suite through
Supercov, then build and validate its assertion map. Find one useful
missing check and add an assertion for the expected behavior.
Only change tests; do not weaken existing checks. Rerun the same suite
and update the map. Show the test change, before-and-after assertion
coverage, and any uncertainty or missing evidence.

The agent should show you the assertion it added and explain which wrong result would now fail. That explanation matters more than the score by itself.

Check assertion coverage yourself

First, measure the tests. Replace this example test command with yours:

npx supercov -- npm test
npx supercov runs latest

On the first run of the checkout example, before a map has been built, the assertion summary says:

Assertions not assessed — No recorded flow explanations

This isn’t 0% coverage. The run has assertions, but Supercov doesn’t yet have explanations linking them to the code they check. Ask your agent to build the map, using the prompt above.

Once the agent has saved and reviewed the map, you can validate it and check it against that run. Replace <run-id> with the ID the agent mapped:

npx supercov runs <run-id> assertions validate
npx supercov runs <run-id> assertions check --require-mappings
npx supercov runs <run-id>

These commands don’t write the explanations for you. They check the map the agent has already built. In a recorded checkout example with status checks but no assertion on the total, the summary then shows:

Assertions 75.00% (3/4) — agent-assessed statements, whole run

To inspect individual statements in that file:

npx supercov runs <run-id> assertions report --view statements --file src/session.js

The report returns JSON. These are the relevant fields for the calculation in that response:

{
  "at": {
    "file": "src/session.js",
    "line": 3,
    "text": "const total = price * quantity;"
  },
  "covered": true,
  "asserted": false,
  "flows": []
}

covered: true means the calculation ran. asserted: false means it has no credited assertion mapping. The empty flows list shows that the map contains no explanation linking an assertion to this statement. It is a place to investigate, not proof that the tests are missing a check.

After adding a check on the total and a test for an expired session, rerun the suite and have the agent update and review the map. In the example, the assertion section becomes:

Assertions 100.00% (4/4) — agent-assessed statements, whole run

The totals differ by language because the measured statements differ. Some runs also include declarations or test code that the example map doesn’t credit, so the final score isn’t always 100%. The recordings include the source, tests, maps and full responses behind these excerpts.

Understand the score

Assertions is the percentage of measured source statements linked to passing assertions by the agent’s map. It is not a count of assertions. Statements that never ran still count toward the total.

An unmapped statement is a place to investigate, not proof of a missing test. The agent may not have mapped an existing check yet.

The strength of the check matters too. assert.ok(order.total) accepts both 49 and 50; assert.equal(order.total, 50) distinguishes them.

Supercov does not generate or execute mutated code to test whether an assertion catches a bug. It checks the agent’s map against execution; the explanation of what an assertion means still involves the agent’s judgment.

A passing test can miss a wrong result

What Supercov and your agent each do

Try it in your project

Check assertion coverage yourself

Understand the score

Read more in the terminal