VARIANCE AUTHORITY
BrowsePackage reference

Package reference

@variance-authority/distill

Find the code one test loads but never uses, and get a concrete substitution to try.

Part of Variance Authority. Point your coding agent at llms.txt.

What this is for

A checkout test renders your whole app — App, TopNav, Clock, an analytics module, and the CheckoutForm it came for. It passes. It does not show which of that it needed.

distill answers that by subtraction. One recording lists what the test's execution loaded and ran. A second lists which elements the test deliberately queried, clicked, read or asserted on — the elements it addressed. Everything in the first that is missing from the second is what is worth trying to remove:

what the run loaded and ran  −  what the test demonstrably interacts with
= the boundary this test may not need

You get an ordered list of files. For a file whose import ran but whose functions never did, you also get the substitution to try: the module to mock in that test's file, and why. How to write the mock is your runner's, so the reading names no runner's call.

distill reads files and prints. It does not open a browser, run a test, or edit your source, and it reads no project configuration. Rerunning the test after you make a substitution is what settles whether the boundary can go.

Install

npm install --save-dev @variance-authority/distill

For the command line instead of the API, install the CLI, which calls the same analyzer and printer:

npm install --save-dev @variance-authority/cli

The record you need first

distill reads one file, the record your own test run writes. It does not come from distill, and it does not come from variance run. The record holds two readings of each case.

The case index — which files and which functions inside them each test covered, meaning ran code in rather than merely imported. Install @variance-authority/sense and wrap your Vitest config:

npm install --save-dev @variance-authority/sense
// vitest.config.ts
import { defineConfig } from 'vitest/config';
import { withTestSelection } from '@variance-authority/sense/vitest';

export default withTestSelection(
  defineConfig({ test: { include: ['src/**/*.test.ts'] } }),
);

Every wrapped run writes the per-case recording into its record, coverage.bin, and distill reads that record as it is. A test file that runs in a page is recorded per file only, so a browser-mode run does not write the file distill needs.

The Eyes journals — which elements each case addressed, and the React component behind each one. In a Playwright suite wrapped in withTestSelection, install @variance-authority/eyes and extend test with its fixtures after the recording's own:

npm install --save-dev @variance-authority/eyes @variance-authority/react @variance-authority/playwright-test
// test/fixtures.ts
import { test as base } from '@playwright/test';
import { varianceFixtures } from '@variance-authority/playwright-test';
import { eyesFixtures } from '@variance-authority/eyes/playwright';

export const test = base.extend(varianceFixtures).extend(eyesFixtures);

Each attempt's journal lands in the record under the case that ran it. A case Playwright retried keeps one journal per attempt, numbered from 1, and the attempt is never part of the case id.

One id joins the two readings

distill joins the two readings on exact case id and guesses nothing — not by title, not by file. Sense keys a case by its coordinate: the repository-relative test file, then the describe path and the test name, joined by >.

test/checkout.spec.ts > checkout > submits

The Eyes fixture takes its case from the recording, so both readings carry that id without anything for you to build. An id the record does not hold is refused, and the refusal lists some of the ids it does:

The record holds no case with id checkout submits. No title or file join was guessed.

Arrange, Act and Assert are read, not guessed

distill reports the addressed elements phase by phase because your test marks where the phases are. Eyes records the boundaries you declare and infers none of them from a library call or an API name. This is an excerpt — attention is the value Eyes' watchTest returns for the current test, and render, screen and expect come from your own suite:

attention.log.phase('arrange');
render(<Checkout />);
attention.log.phase('act');
screen.getByRole('button', { name: 'Place order' }).click();
attention.log.phase('assert');
expect(screen.getByRole('status')).toHaveTextContent('Order placed');

A test with no phase markers still works. Its observations are reported under unphased.

Run it

From the command line, in the checkout that ran the test, naming the case and the file that declares it:

variance distill --file test/checkout.spec.ts --test 'checkout > submits'

--test takes the case's id, or its whole title, its describe blocks and its name joined with >. --file takes the test file's path, relative to the checkout or absolute, and names that file alone. When more than one case fits, the command prints their ids and stops, and you pass one of them to --test. --file alone reads the whole file instead: the modules it loaded that no case, or only some of its cases, entered, each module no case entered under the import that made the file load it.

distill reads the nearest record this machine holds and fetches nothing: this checkout's own, else the mainline's as last fetched here, else, in a worktree, the primary checkout's. --suite <name> picks one declared suite's, and --execution <path> names another record, or a case index another tool exported as JSON. Add --format json for the analyzer result instead of the text.

From Node, distill takes the readings already in hand. Here a case index another tool exported as JSON, and one journal for its only attempt:

import { readFile } from 'node:fs/promises';
import { parseEyesJournal } from '@variance-authority/eyes/archive';
import { distill, formatDistillation, parseExecutionIndex }
  from '@variance-authority/distill';

const test = 'test/checkout.spec.ts > checkout > submits';
const execution = parseExecutionIndex(
  JSON.parse(await readFile('execution.json', 'utf8')),
);
const journal = parseEyesJournal(JSON.parse(await readFile('journal.json', 'utf8')));

console.log(formatDistillation(distill({
  test,
  execution,
  eyes: [{ case: test, attempt: 1, journal }],
})));

parseExecutionIndex and parseEyesJournal validate untyped JSON at the process boundary and throw naming the offending field. Pass an ExecutionIndex you already have and it returns it unchanged.

What you get

For a checkout test that set a quantity, clicked to place the order, and rendered analytics and a chart it never touched — abridged, since the printed text also closes with a substitution rule and an opportunity rule restating that neither finding is permission to delete anything:

checkout submits — test/checkout.test.tsx [test/checkout.test.tsx > checkout submits]
Eyes journal, attempt 1: complete.
2 target snapshot(s); 0 had no live React Fiber.

arrange:
  components: CheckoutForm
  source: src/checkout/form.tsx
act:
  components: CheckoutForm
  source: src/checkout/form.tsx

React update initiators:
  act: 1 commit(s)
    inside addressed component paths: CheckoutForm
    outside addressed component paths: Clock

Runtime phase attribution: unavailable; ExecutionIndex retains test crossings, not AAA intervals.
Runtime journey: 3 source file(s) covered by exact case id.
  depth 0 — src/analytics.ts
  depth 0 — src/checkout/form.tsx
  depth 0 — src/heavy-chart.tsx
Covered with no addressed target attributed to the same file: 2.
  distillation opportunity at depth 0 — src/analytics.ts
  distillation opportunity at depth 0 — src/heavy-chart.tsx

Loaded but not covered: 1 module(s).
  src/heavy-chart.tsx — the import ran its top level and this test covered nothing below it
    never covered: HeavyChart (lines 5-8)
    substitution to try: mock src/heavy-chart.tsx in this test's file; loading it is all this test used of it. Stand in for what it exports: an automock loads the module to read its shape

Reading it:

  • The phase blocks name what the test addressed, and where that markup came from in your source. Everything else the run touched is absent from them.
  • React update initiators are the component instances whose state queues scheduled a commit. One outside the addressed paths — Clock here — means code the test did not address started work during the same authored phase. It names an instance, not the source statement that called a setter.
  • Runtime phase attribution: unavailable is not a failure. The execution index records what each test covered across the whole test, not per phase, so covered files are never split across Arrange, Act and Assert.
  • depth is a call depth from the test. Every entry the Vitest recorder writes sets it to 0; the field exists for a recorder that measures one.
  • substitution to try names the module, not a call. Write it the way the test file's runner mocks a module.
  • The two finding lines are the two classes of answer, below.

The two classes of finding

A distillation opportunity is a file the test covered with no addressed element attributed to it. The test ran code in that file and never touched anything the file rendered. That is a place to look, and not more: an unaddressed component can still shape the result the assertion reads.

Loaded but not covered is the stronger reading. An import is not a use. import { HeavyChart } from './heavy-chart' runs that module's top level, and nothing else in it runs unless something calls in — the branch that would have rendered it was never taken, or a spy answered in its place. Both leave one trace: the module's top level ran, every declaration below it untouched. That is the case distill names a substitution for.

Neither class is a verdict, and that is the position rather than a shortfall. Mocking takes the top level with the rest, so a top level that registers a handler, installs a polyfill, or builds a singleton is one the test is standing on. Make the substitution, rerun that exact test, and compare the new reading against this one before you keep the edit.

Without Eyes journals

A record whose run did not use Eyes, or a JSON case index, still gives you the covered-source reading and the loaded-but-not-covered finding, which is what makes a plain Node unit test or a non-React harness worth distilling.

The opportunity comparison is then reported unavailable rather than empty. A test whose attention was never recorded and a test that addressed nothing are different situations, and distill will not print one as the other. A complete Eyes journal that happens to be empty and the comparison proceeds with a measured-empty addressed surface.

API

ExportWhat it is
distill(input)DistillInput in, Distillation out. Throws when the execution index holds no case that fits test and file, or more than one.
formatDistillation(result)The text above. The CLI and MCP adapters print exactly this.
parseExecutionIndex(value)Validates untyped execution JSON, throwing on the first bad field.
distillFile(input)FileDistillInput in, FileDistillation out: the modules one test file loaded that no case, or only some cases, entered. Throws when the record holds no test file at exactly file.
LoadCauseWhy a file loaded a module no case entered: the one import every path to it runs through, shared with the file where its paths part, or unseen by any static import. Set when FileDistillInput.relations gives the file graph.
formatFileDistillation(result)The text of a file reading, as the CLI prints it for --file alone.
scopeRows(input)ScopeDistillInput in, one ScopeRow a test file out, as variance distill --format jsonl writes them: the file's suite, cases, what it loaded and its lines, and what no case of it unentered, or withheld with the reason. Throws when the scope holds no recorded test file.

DistillInput names the case by test, file, or both — file alone when the file holds one case — and carries the execution index, an optional root, and optional eyes: one EyesAttempt per recorded attempt, each a case, an attempt numbered from 1, and its journal. The case is found in the index alone, and the journals are read by its id. attempts on the result carries each attempt's attention. Distillation is a plain data result: attention is the per-phase AddressedPhase and UpdatePhase records, and execution lists EnteredFile by file and EnteredModule region by region. A Region is one instrumented declaration — a module's top level, or a function — with its name and line range. On an EnteredModule, entered and unentered split those regions, and loadedOnly is the flag behind the loaded-but-not-covered finding.

FileDistillInput carries the test file's repository-relative path as file, the record's bytes as record — its coverage rows and its case index, as the run wrote them — and optionally the file graph as relations. The cases and the regions a charge reads come from the record itself. ScopeDistillInput carries one record per suite. The records are read once, by the native addon, however many test files a scope asks about.

distillFile, distillScope and scopeRows require the @variance-authority/sense native addon, which installs as an optional dependency on macOS arm64, Linux arm64 and x64, and Windows x64. Where it did not install, they throw and name why. FileDistillation counts what the file loaded and their lines, and lists LoadedModule entries — file, lines, and entered, how many of the file's cases entered the module — fewest entered first, then most lines, then by path. modules is absent, and withheld says why, when the index keeps no cases for the file, when a case stopped or did not say whether it finished, or when the file's coverage row is incomplete.

Ordering is deterministic. The same record produces the same answer.


@variance-authority/distill is part of Variance Authority — documentation · GitHub · MIT