Assertion map format

Edit a run’s assertions.json to record which assertions check which source statements. Start with Understanding assertion coverage if you want an agent to create the map for you. This reference covers the fields and commands used to inspect, update and validate it.

Open the run’s map

npx supercov runs latest assertions --json

The response gives you data.run and data.map. Use that run ID throughout the edit. A normal run creates the file automatically and inherits compatible work from earlier runs of the same test command and language.

Only edit assertions.json. Keep assertions.state.json and the run’s evidence unchanged. Use current project files that match the run when investigating.

Describe an assertion and its flow

This illustrative draft maps an equality check to a return statement:

{
  "schemaVersion": 2,
  "assertions": [{
    "id": "a_example",
    "at": {
      "file": "tests/value.test.ts",
      "line": 5,
      "column": 3,
      "text": "assert.equal(value(), 1)"
    },
    "observes": ["The returned number equals one."],
    "flows": [{
      "id": "return-value",
      "basis": null,
      "appliesTo": [{ "file": "tests/value.test.ts", "name": "value" }],
      "explanation": "value() returns the number compared by the assertion.",
      "nodes": [{
        "id": "return",
        "at": {
          "file": "src/value.ts",
          "line": 2,
          "column": 3,
          "text": "return 1;"
        }
      }],
      "edges": [{ "from": "return", "to": "$assertion", "kind": "data" }],
      "countsAsAsserted": ["return"],
      "watch": []
    }]
  }]
}

Use the actual assertion IDs, test names and source locations from your run. The example remains a draft until its references match and its flow has been examined and acknowledged.

Source anchors use project-relative paths with /, one-based lines and one-based UTF-8 byte columns. Preserve exact text, including multiline expressions. IDs use letters, digits, _, - or .. Edge basis is optional explanatory text; it is separate from the flow’s review token.

Every counted node needs a path through the recorded edges to $assertion and must match a measured statement exactly. Counting an if statement does not also count every statement inside it. Nodes that only provide context can stay in the graph without appearing in countsAsAsserted.

Test selectors must be unambiguous. An empty appliesTo supplies no execution credit. For a shared assertion, select the applicable test cases explicitly. An absence or fixture-only check can use countsAsAsserted: []; explain what was observed and, for absence, the ordering and observation window.

Validate and acknowledge your edits

npx supercov assertions schema --json
npx supercov assertions validate --file <map-path> --json
npx supercov runs <run-id> assertions validate --json

The first command exports the editor schema. File validation checks JSON shape. Run validation also checks IDs, source anchors, graph links, selected tests and changed inputs. It does not edit the map or prove the explanation.

After examining a flow, copy its returned expectedBasis into that flow’s basis, save the file, and run check. Treat the token as an opaque value; do not generate it yourself. Editing a claim or its dependencies makes the old token stale.

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

Use --require-observed when every mapped site is expected to run. Skipped, TODO and untaken cases can make it fail even when their explanations are useful. Neither gate establishes that every possible flow has been found.

validate exits with code 2 for syntax or reference errors. A null or stale review token alone is not a syntax error. check exits with code 2 when a requested requirement is unmet.

Understand statement credit

The percentage counts the union of explicitly claimed measured statements with current flows, a passing assertion and execution in the same selected passing test. Duplicate claims count once. Unexecuted statements remain in the denominator. A line receives assertion credit only when all measured statements on it receive credit.

TypeScript imports known to disappear during compilation are excluded. Inspect their locations with:

npx supercov runs <run-id> assertions report --view excludedStatements

This includes explicit import type and, for supported tsc/tsx/ts-node settings, imports used only as types. Runtime, mixed and side-effect imports remain. Preserving compiler settings and configurations that Supercov cannot resolve keep ambiguous imports in the denominator. Older runs keep their recorded totals.

An assertion detail explains each node’s credit decision. In JSON, computed nodeCredit entries include the decision, reason codes, matched statement IDs and matching tests. Keep these report fields out of the editable map. See Investigating assertion evidence for missing execution, shared setup and asynchronous cases.

A numeric result can come from a partial map. current means the flow has no freshness, reference or question blockers; it does not mean all source nodes receive credit or every relevant flow is known. The normal report shows counts of assertions without flows and flows still needing attention beside the score.

JSON regular reports put the summary at data.assertionCoverage.summary. Assertion reports use data.summary. A summary.status of available supplies a percentage; notAssessed, pending, unavailable and notApplicable do not. The assertion summary always covers the whole run, even when other coverage metrics or the returned items are filtered.

Find the next part to investigate

Use --file <path> to filter applicable list views; the summary still describes the whole run. Lists support --offset, --limit and --json. Follow the printed next-page command or JSON pagination.nextOffset until it is null. Restart a paged read if revision changes while you are reading it.

An assertion detail pages whole flows by default. For a large individual flow, use --flow <flow-id> --view nodes and --view edges. Add --compact to omit repeated source text while retaining locations. Read that text with source; do not save compact report objects into the map.

Large validation results support --view flows, --view changes or --view errors. Each page still reports validity for the entire map. The source command pages lines; JSON source output uses {line, text} objects for integrations.

Update the map after a change

Run the same test command again, then edit the new run’s map. Supercov carries forward compatible mappings and leaves the previous run unchanged. If a newer map cannot be reused, inheritance.skipped explains the fallback.

Each flow depends on its assertion file, selected test files, node files and extra watch files. A change to any of those files requires another look at that flow, even if only a comment changed. Independent sibling flows can stay current. Changing the assertion or its observation affects all its flows. Dependency, configuration and instrumentation changes can affect many flows.

Start with assertions report --view changes. Investigate every listed change, including effects on flows that did not yet watch the changed file. Add a response in the map’s top-level changeAssessments array:

{
  "changeAssessments": [{
    "id": "c_copy_from_changes_view",
    "basis": null,
    "affectedFlows": ["a_example/return-value"],
    "explanation": "The edit affects the returned value. The independent sibling calculation is unchanged."
  }]
}

This is an excerpt to add to your existing map. Include every entry in knownFlows that still exists and any additional affected flows. An empty list needs an explanation of why existing claims are unaffected; it does not mean the changed code is tested.

Save the assessments and graph edits, validate, and copy the examined change tokens. Save again, then validate once more before copying final flow tokens. Assessing a change can make another flow stale, so the order matters. Removing an assessment or reverting a file does not by itself clear an unresolved change.

Keep removed or ambiguous assertion records for review under retiredAssertions. Follow the supplied questions when inheriting older maps. Do not invent source links or evidence to clear a warning.

Keep queries fast

Reports reuse a disposable assessment cache while checking that sources still match. Editing the map invalidates the cached assessment automatically. Queries never acknowledge flows or change the authored map. See Speed and storage for keeping repeated investigation fast.