# Variance Authority > Open-source tools for developers and coding agents: source intelligence, live test inspection, test selection and reduction, UI analysis, and change verification. Every documented page serves the Markdown it is built from beside it: append `/index.md` to the page's path. Links within that Markdown point at the Markdown of the page they name. ## Start here - Install the CLI: `npm install --save-dev @variance-authority/cli`. It installs the `variance` command and ships the agent skills under `node_modules/@variance-authority/cli/skills/`. - [Link the agent skills](https://variance-authority.dev/agents/cli/index.md#point-an-agent-at-it) into your agent's own skills directory. - [Choose an agent workflow](https://variance-authority.dev/agents/index.md): Three questions with three different owners: a hung test, a screenshot that changed, and a symbol you cannot name. Only the last can be answered without a run behind it. Each is matched below to the reading it needs and the guide that sets that reading up. - [Visual review integrations](https://variance-authority.dev/start/index.md): One question picks your guide: which harness already puts the app in the UI state you want to review — a Playwright spec, a built Storybook, a served route, a jsdom unit test, Vitest browser mode, an Rstest suite, or a mount nobody else owns. Whichever row of the table below you land on ends the same way: that state gets a baseline image you approved, and a later run that moves pixels reports the component that drew them and the file:line it was written at. - [Source](https://github.com/Variance-Authority/variance-authority): every package's README, beside the code it documents. ## Examples Repositories to clone and run, each installing the published packages. - [example-playwright](https://github.com/Variance-Authority/example-playwright): visual review from inside a Playwright test - [example-storybook](https://github.com/Variance-Authority/example-storybook): visual review of every story in a Storybook - [example-vitest](https://github.com/Variance-Authority/example-vitest): visual review from a unit test - [example-running-app](https://github.com/Variance-Authority/example-running-app): visual review against an application that is already running - [example-static-site](https://github.com/Variance-Authority/example-static-site): visual review of a built static site - [example-divergence](https://github.com/Variance-Authority/example-divergence): one input rendered two ways, and where the renderings part - [example-history](https://github.com/Variance-Authority/example-history): what a design token has drifted to across many approved reviews - [example-tribunal](https://github.com/Variance-Authority/example-tribunal): a storefront read twice and reviewed once in the review console - [example-workers](https://github.com/Variance-Authority/example-workers): test selection across Cloudflare Workers, joined by a Sentry trace - [example-tester-army](https://github.com/Variance-Authority/example-tester-army): end-to-end tests with coverage-based test selection, on a local model ## Documentation - [Questions](https://variance-authority.dev/docs/index.md): Pick the question that brought you here. Each path below tells you what evidence it needs, what answer it can produce, and where that answer stops. Use one path on its own or combine several as the investigation grows. - [Theory](https://variance-authority.dev/docs/theory) - [Reference](https://variance-authority.dev/docs/reference) - [Comparisons and case studies](https://variance-authority.dev/docs/comparisons) - [All pages](https://variance-authority.dev/docs/all) ## Theory - [Tests preserve the paths we care about](https://variance-authority.dev/docs/tests/index.md): A test turns one path through your product into a repeatable proof: the same starting conditions, the same action, the outcome you expected. What you earn is confidence that this one promise has been preserved under the conditions the test ran under. That is worth stating precisely, because it is also the boundary of what a green run can show you. - [On testing](https://variance-authority.dev/docs/on-testing/index.md): A test earns its place by producing credible information soon enough to change a decision. Its level, speed, coverage and age matter through that job. A suite is not strong because it owns many tests or because each test is small. It is strong when each important risk has evidence at the cheapest boundary that can still expose the real failure, and when you can tell what each test adds. - [On dependencies](https://variance-authority.dev/docs/on-dependencies/index.md): An import looks like one line of syntax. Added up, the imports of a repository are its "uses" relation, and the shape of that relation decides which parts of the system can be built, tested and understood without the rest. Software design has argued for a direction in that relation for fifty years, and dependency-analysis tools have long extracted it from code. Variance Authority uses that derived structure as a review signal: it shows when an ordinary import changes the dependency hierarchy before anyone has to declare what that hierarchy should be. - [Coverage-based test selection](https://variance-authority.dev/docs/coverage-test-selection/index.md): Coverage-based test selection runs, after a change, only the tests that executed the code you changed, according to a recording of an earlier run. Variance Authority records that relation on the suite you already run, for no more than 8% of its run time, and parses each changed file as it was recorded and as your diff leaves it before it selects a test. On an unmodified Zod checkout, a one-line edit selects 6 test files, 8 runs in all, where rerunning every file that loads the changed module selects 197. - [See what changed](https://variance-authority.dev/docs/changed/index.md): A diff records what you edited, and a screenshot or an assertion records the result. When a change goes wrong, what you need is the path between them: which branch ran, which component rendered, which input changed. That path exists only while the program runs. Variance Authority records it during the run, so you answer what did this change actually do? from the record instead of running the suite again to find out. - [Follow the reasoning loop](https://variance-authority.dev/docs/reasoning/index.md): You already have visual regression covered — toHaveScreenshot, Chromatic, Percy, jest-image-snapshot — and the question you bring to a red build is rarely did these pixels change. It is which tests this edit could affect, whether the change on screen is the change somebody authored, or why one state keeps disagreeing with itself. Variance Authority answers those from different readings — a parse of the source, a completed run report, a record of what each test covered, a suite still running — and asking the wrong one pays for a full suite render to get an answer a source reading already had. This page is how you pick the reading before you pay for it. - [Use the evidence you have](https://variance-authority.dev/docs/evidence-field/index.md): A red build from toHaveScreenshot, Chromatic, Percy or Argos hands back a count of differing pixels and two images; every question after that — which component drew the region, whether the same state reads the same way twice, whether your edit could reach it at all — is answered by somebody opening the diff. This page is about those later questions, and about answering them from readings the run already took rather than from a second tool asked to take them again. - [What one run leaves you](https://variance-authority.dev/docs/great-data/index.md): Your build went green, or you approved the diff and closed the report. Everything a Variance Authority run observed while getting there is still there, and most of what you can now ask it has nothing to do with pixels. - [Evidence instruments](https://variance-authority.dev/docs/instruments/index.md): A subject came back changed. Whether that difference is real, and what caused it, are two further questions, and by eye they are answered one image at a time. The instruments catalogued here are the repeatable alternative: each one holds everything still, varies exactly one thing, and reads a representation cheap enough to read again. - [Why it does so many things](https://variance-authority.dev/docs/adjacent-possible/index.md): Variance Authority starts with visual regression and does not end there. It also shows you where to start in an unfamiliar codebase, selects the tests a change needs, names the tests that run a line, helps you shrink an oversized test, and records what a Java service ran for each test. Visual regression no longer defines it, the same way guitars do not define Yamaha. One phrase explains the list: self-reinforcing adjacent possibilities. Solving one problem builds a capability, and that capability makes the next problem cheap. - [Why visual review costs less here](https://variance-authority.dev/docs/visual-review-cost/index.md): A visual regression suite costs you twice: machine time for every picture it takes, and an engineer's time for every difference it shows. Both grow with one number — how many comparisons the suite makes, and how many of those it puts in front of a person. A screenshot tool takes every picture first and compares afterwards, so that number is fixed before anything clever runs. Variance Authority runs beside the tool and the tests you already have, and decides earlier. It runs only the specs and stories that executed the code you changed, settles a state whose DOM and styles are unchanged without painting a pixel, and when it does show you a difference, it names the component and the file:line that drew it. - [Extend what you already use](https://variance-authority.dev/docs/extend-what-you-use/index.md): You already have tools built around how your software works. Your test runner runs the suite. Playwright drives a browser. React Testing Library helps tests address the interface. Your visual regression service compares screenshots and records approvals. Your debugger, editor, search tools and documentation service answer other questions. Replacing any one of them is a separate decision. ## Code exploration - [Find where to start](https://variance-authority.dev/docs/orientation/index.md): Orientation turns a question about an unfamiliar codebase into an address you can inspect: a source name, a file, an import neighbourhood, or a captured UI subject. It comes before diagnosis and editing. Its answer is where to read next, not a claim that the code is correct. - [Find a name in source](https://variance-authority.dev/agents/workspace-api/index.md): rg tells you where text is written. This server tells you which name matches your words in the part of the import graph you are working in — an exported name first, then one a file keeps to itself — then gives you its declaration, signature and documentation, and for an exported name its import line and existing import sites. It answers from a dated workspace generation — no build, run, generated API site, or variance.config.json in between. - [Use the packages your project already installed](https://variance-authority.dev/docs/tech-stack/index.md): Your project's tech stack is the packages its code builds on and builds with. Variance Authority reads it from your checkout: which packages the file you are editing can already use, which installed package does a job, the signature of a name at the version in nodemodules, and the agent skills a package's authors ship with it. Your agent asks with variance ask stack, search and symbol, or through the same tools on the MCP server, before it writes code against a library. Every answer comes from the files you installed. Nothing is fetched and nothing is installed for you. - [Find the subject you mean](https://variance-authority.dev/docs/locate/index.md): You know which thing you want to look at. You do not know what it is called. - [How subject search works](https://variance-authority.dev/docs/lexicon/index.md): This is the recorded-vocabulary half of orientation: use it when you can describe a captured UI state but do not know its subject id. For source names in the current checkout, use the workspace API. - [See the structure your imports build](https://variance-authority.dev/docs/boundaries/index.md): variance layers numbers every package by the longest chain of packages it imports beneath it, and tells you in a pull request which packages changed number. It needs no declaration of an architecture: it derives the depth from the imports already in the source index, so the layers are the ones your code has, not the ones a config says it should have. Declare a few line budgets and it also places every package in a tier by how much code it pulls in. variance restrictions adds policy when you want to state a relationship, a depth limit or a size limit that must hold. Neither asks you to tag packages. ## Your test suite - [Make a test suite faster and more reliable](https://variance-authority.dev/docs/better-tests/index.md): While a test runs, the machinery under it can observe which code executed, which elements the test queried or clicked, and what setup ran before it began. Teardown is normally where all of that disappears, and the run ends with a pass, a fail and a pixel count. Variance Authority keeps the record instead. - [Own fewer tests](https://variance-authority.dev/docs/own-fewer-tests/index.md): Your suite only grows. Every test in it was justified when it was written, and a merged coverage report cannot tell you which of them are still worth keeping: it shows that a line ran, not which tests ran it, not whether six of them ran it for the same reason. Variance Authority records the half coverage drops: for each test case, which regions of your source that case covered. Point at a line and it hands back the named cases that walked it, which is where the question why do all of these tests need this code? starts having an answer. - [Test-level coverage](https://variance-authority.dev/docs/test-level-coverage/index.md): Ordinary coverage is a union: every region some test covered, with nothing left recording which test covered it. Test-level coverage keeps the relation that union was folded from — for each named test case, the regions of your source that case walked — so a line answers which tests walk me rather than did anybody. It is one axis added to a recording your suite can already make, and it is what separates a question you can act on from a percentage you can only watch. - [Record the state each test ran under](https://variance-authority.dev/docs/case-preconditions/index.md): Test-level coverage tells you which tests ran a piece of code. A case precondition records the state each of those tests ran it under: a feature flag, what a mock returns, which user a fixture signs in. Coverage gives you the code path; case preconditions give that path its scenario. A breadcrumb records the other side: the value the code under test read, so you can check that the scenario a test claims is the one that ran. - [Run relevant work](https://variance-authority.dev/docs/run-relevant-work/index.md): Not every subject in your suite can be touched by the file you just edited. Variance Authority rules out the ones that cannot, before a browser opens. - [Run the tests an edit needs](https://variance-authority.dev/docs/test-an-edit/index.md): Set VARIANCEAUTHORITYSINCE and the Vitest or Jest run you already call leaves out every test file a recorded run shows never executed the code you changed. Nothing goes on the command line and no script sits between you and the runner, so the edit-and-test loop you or your coding agent already runs stays the same loop, only shorter. - [How test selection works](https://variance-authority.dev/docs/selecting/index.md): A change to a few lines should not run every test that imports the file. With execution recording, Variance Authority records which parts each test actually covered. It selects the tests that reached those lines and shows when no test did — what a record shows that no graph can. - [Split a suite across CI jobs](https://variance-authority.dev/docs/sharding/index.md): Shard a Vitest, Jest or Playwright suite with --shard k/n, and each shard takes whole test files by how long they took on the last recorded run, not by how many there are. Each file goes in turn, longest first, to the shard with the least time so far, so the shards finish close together. Each shard computes the split from the record it reads and the files it collects, without talking to the others, so shards that read one record at one commit run every file in exactly one shard. A Playwright setup or teardown project is the exception: Playwright runs it in every shard that keeps a test depending on it. - [Changes before and beyond](https://variance-authority.dev/docs/changes-before-and-beyond/index.md): Two changes widen a run that no import graph can narrow: a config file nothing imports, and a package you never wrote. Selection answers from the names files import from each other, so a change with no name in those imports is either the whole suite or nothing at all — and which of the two is a choice you make rather than one the walk makes for you. This page is about those two changes, about the files a suite ignores because none of its results can move with them, and selection is about everything between them. - [Measure test distance](https://variance-authority.dev/docs/distance/index.md): After a source change, test selection narrows your suite to the test files that change could have reached. On a shared module that narrowed set is still most of the suite, and nothing in it tells you which file to run first. Distance orders it: for each selected test file it counts the import steps — hops — between the changed source and that test, so you can run the closest files first and read an answer while the edit is still fresh. - [Select Java tests from the methods each one ran](https://variance-authority.dev/docs/jvm/index.md): A Java agent records which methods each test entered, so a change to a Java method runs only the tests that reached it. A test is a JUnit test class, or a Jest case or browser spec that reached the method in a service over HTTP. The record is one row per test, and variance select answers a diff from it without an import graph, which a request to another process never shows. - [Make one test cost less](https://variance-authority.dev/docs/optimize-a-test/index.md): Selection decides which tests run after an edit. It does not change what one of them costs while it runs, and it does not change how often the next edit reaches it. Both of those are properties of the boundary the test loads. - [Distil a test to what it witnesses](https://variance-authority.dev/docs/distill/index.md): A checkout test may render a navigation bar, a clock and an order form, whether that markup comes from React, another framework, or no framework at all. But which elements does it actually use to set up the order, submit it and check the result? Rendering the whole page does not make every part of it part of the promise the test protects. ## Visual review integrations - [Visual review integrations](https://variance-authority.dev/start/index.md): One question picks your guide: which harness already puts the app in the UI state you want to review — a Playwright spec, a built Storybook, a served route, a jsdom unit test, Vitest browser mode, an Rstest suite, or a mount nobody else owns. Whichever row of the table below you land on ends the same way: that state gets a baseline image you approved, and a later run that moves pixels reports the component that drew them and the file:line it was written at. - [Playwright](https://variance-authority.dev/start/playwright/index.md): The state you want to review only exists after your test has navigated, logged in and waited for it — so keep all of that. This page adds one Variance Authority observation and one assertion inside the test body, at the point where the page is already right, and the locator you pass becomes a subject with a baseline image of its own. - [Storybook](https://variance-authority.dev/start/storybook/index.md): Story ids already name your UI states, and storybook-static/index.json already lists every one. This page turns that list into screenshots you approved — build, run, review, accept, rerun — and a story whose pixels move afterwards is reported by the component that changed and its file:line. - [Application routes](https://variance-authority.dev/start/routes/index.md): A server owns your routing and page state here, and the route as it ships — not a component mounted alone — is what you want under an approved image. Name one URL, run it, approve the first image, and watch the second run come back unchanged. That loop is the whole of this page. - [Vitest or Jest (jsdom)](https://variance-authority.dev/start/unit/index.md): Your Vitest or Jest tests already mount components in jsdom and assert on them. This path puts those same mounted states into visual review: the test writes a capture, a later process paints it in Chromium, and the screenshot is compared against an approved baseline. You get visual coverage of the components you already cover, without writing and maintaining a second Playwright or Storybook suite for them. - [Vitest browser mode](https://variance-authority.dev/start/vitest-browser/index.md): Vitest browser mode has already mounted your component in a real browser, which is the expensive part. This page spends one call and one assertion on top of it: the mounted subtree is read as a document rather than photographed, repainted by a Chromium the Vitest process owns, and compared against an image you approved. - [Rstest](https://variance-authority.dev/start/rstest/index.md): Rstest runs a suite two ways, and each one is a different adoption of visual review. - [Custom collectors](https://variance-authority.dev/start/custom/index.md): Whatever renders your states can go under approved baselines, provided a state's name is the only input to the bytes it produces. This page is that route for a harness nobody wrote an adapter for: one module you write, then a new verdict, an approval, and unchanged on the rerun — every step after that module identical to a built Storybook's. - [Visual review from the CLI](https://variance-authority.dev/start/cli/index.md): Four commands make the review loop, and @variance-authority/cli is all four: ## Investigate a run - [Understand an execution](https://variance-authority.dev/docs/understand-execution/index.md): A comparison or an assertion has shown you that something changed, and now you need to find out where. This page indexes what the same run kept about the execution behind that answer: one test's work, from the moment your runner starts it to the moment it ends, across every process it touched. - [Watch a run that has not finished](https://variance-authority.dev/docs/vantage/index.md): Your suite is still running and one test has been on the same line for longer than it should. Variance Authority can show you what that test has heard, and from whom, while it is still in flight rather than after teardown has thrown all of it away. - [See what a test addressed](https://variance-authority.dev/docs/eyes/index.md): A passing test proves that its assertion succeeded. It does not reveal which UI the test deliberately operated, which React work arrived alongside that interaction, or which executed source was merely present. Eyes records that missing surface as one authored Arrange–Act–Assert chronology. - [Read the path an execution took](https://variance-authority.dev/docs/journeys/index.md): Three stories mount CartCard. One of them clicks Remove. The onClick body is a region the other two have never been inside — same file, same import graph, same props — and no reading of the file can distinguish the three, because the difference is not in the file. It is in what each execution did with it. - [Follow a test into other services](https://variance-authority.dev/docs/across-dimensions/index.md): A test runs in one process, and the code it checks often runs in others: a gateway it calls, the services behind that gateway, a JVM backend, a Worker behind a service binding. Each process, runtime or language one test passes through is a dimension of that test. This page is for a suite whose tests cross them. It explains why no import graph can tell which of those tests a change beyond the first process reaches, and how Variance Authority follows each test's execution into the other processes and joins what they ran back to the test after the run. - [Compare state transitions](https://variance-authority.dev/docs/scenarios/index.md): A snapshot test checks that one UI state looks the way it did. It cannot check that clicking Delete does the same thing on a page with one article as on a page with two. A runtime scenario records that: a named starting state, a fixed sequence of authored steps, and what the UI looked like after each one. Read this page when you want to compare two such recordings. - [Understand an interface](https://variance-authority.dev/docs/understand-interface/index.md): Three readings describe a rendered interface without comparing it to anything: the measured relationships of the layout, the elements your test actually addressed, and the React component that owns each of them. All three read one live page inside a Playwright or Vitest run you already have, and none of them needs a previous image, an approved baseline, or a stored comparison. - [Inspect presentation relationships](https://variance-authority.dev/docs/presentation/index.md): You make a UI edit and the screenshot changes, which shows that the interface changed, but not what changed about the way it reads. One repeated row may have drifted from its peers, a heading may no longer stand apart from its body, or two groups may have become hard to tell apart even though every word is still present. Measure those relationships before the edit and again after it, and a person or a coding agent can say whether the edit did what it was meant to do. - [React state and effects](https://variance-authority.dev/docs/framework/index.md): A form renders correctly and its screenshot passes. A child component declared inside the form is nevertheless rebuilt on every parent render, so the next validation update discards what the user typed. Before that interaction, the stable and broken versions produce the same document. The capture describes what is on screen; it cannot show whether that component will survive. - [Explain variance](https://variance-authority.dev/docs/explain-variance/index.md): Something moved, and the report you are reading names a region but not a reason. Which page helps depends on the kind of explanation that is missing: a component name, the input that changed, a second reading that disagrees with the first, or a declaration that the region was never the subject. Each row below names one and the page that produces it. - [Trace a visible change to source](https://variance-authority.dev/docs/attribution/index.md): A pixel differ answers one question — how many pixels differ — and 5482 cannot be read, cannot be assigned, and leaves you opening the image to look, which is the expensive act the tool was supposed to replace. Attribution turns the count into this region, inside Toggle, in main → region "Todos" → item 2 of 3, written at examples/todomvc/src/ds/components.tsx:107. - [Compare A with B](https://variance-authority.dev/docs/a-b-testing/index.md): Before you read a comparison of A with B, you need to know what is different between them. When one thing differs, every difference in the result belongs to it. When two things differ, nothing in the result shows which one you are looking at. Every pair that Variance Authority compares states the one thing that differs between its sides — the revision, the time, the page it was read on, an authored Act, or the subject itself — and a pair where a second, undeclared thing also differs is refused rather than reported. - [Which input changed, not just which pixels](https://variance-authority.dev/docs/parting/index.md): A diff shows that a
rendered a

on one side and a on the other. That is a symptom, and acting on it means opening the component, guessing which branch ran, and guessing why. partingOf takes those two readings and names the input that sent them apart — a prop, a context value, an external store, or a hook cell — along with the component that changed it. Read on when you have a difference in hand and want its cause rather than its coordinates. - [Compare related states](https://variance-authority.dev/docs/variations/index.md): Your suite has variants: a feature flag's second version, the same page in the dark scheme, a story at a narrow viewport, a route whose backend answers with the empty state. What each of them does to the page is the difference you care about, and it is the one difference an ordinary run never reports. This page is for making a run measure it instead. - [Group repeated changes](https://variance-authority.dev/docs/composition/index.md): One token edit turns forty stories red, and every comparison you have is one subject — a story, route, fixture or data value your config names — against its own baseline: two revisions of one thing, forty times, with nothing marking the forty as one change. Composition is the other axis — many subjects, one revision, joined on the components they share — and there is no baseline anywhere in it. - [Trace instability to its owner](https://variance-authority.dev/docs/flakiness/index.md): Visual regression becomes hard to trust when several different causes are all reported as “flake.” When a subject changes, the run varies one condition at a time: again holds the world and advances time to test whether the subject drifts in place; when again agrees, alone rebuilds the world at the same time to test whether the shared session changed it. These are evidence-producing checks, never retries. A moving animation, a changed environment, an unstable component, and leaked state need different responses; treating them alike leads to tolerances that may quiet the report without explaining what happened. - [Page stabilization](https://variance-authority.dev/docs/stabilization/index.md): A spinner caught mid-turn, a web font that arrived late, a scrollbar one machine draws and another does not: any of them reports a change your code did not make. A run, one execution of npx variance run or one observation in your test, holds your page still before it reads it, so that two readings of an unchanged UI agree. Read on for what it does to get your page there, what you can change about it, and how far into your page it goes. - [Wait for content that loads late](https://variance-authority.dev/docs/late-content/index.md): A component that loads its code or its data after its first render shows a placeholder, then its content, and a screenshot records whichever of the two is on screen. A run waits for the late content React reports as pending: a React.lazy component, a promise read with use() inside , a server-rendered route that has not hydrated. When that wait runs out, or React is stuck with nothing left arriving that could unstick it, the run refuses the subject: it records nothing for it and fails with a message that names what is still pending. Content an effect sets after it loads something is not pending anywhere React can report, so the run records the placeholder and says nothing. This page shows both kinds on one component, and how to turn the second kind into the first. None of the ways is a sleep. - [Choose which changes matter](https://variance-authority.dev/docs/sensitivity/index.md): A route test that goes red every time a colour token changes is a route test nobody reads, and the usual cure — a looser threshold — also stops it noticing that the sidebar collapsed. A sensitivity is the other answer: it names the kinds of change a subject is under test for, so a route test and a component test can assert on different things without either one going quiet. - [Exclude noise without hiding it](https://variance-authority.dev/docs/ignores/index.md): Some of what a page renders is not the subject. A clock, a carousel, an embed somebody else controls — they change on every run, and no amount of correctness elsewhere makes a suite usable while they do. - [Compose an observation](https://variance-authority.dev/docs/compose-observation/index.md): Wiring an observation into a suite you already have is four separate decisions: which of your harnesses sets up the state, what gets captured and where the pixels are painted, where the answer is consumed and how long it is kept, and who stores the baseline between runs. This page is the index to those four. If you have not run anything yet, your first run takes one UI state through capture, review and acceptance end to end. - [Start from the state you have](https://variance-authority.dev/docs/cases/index.md): You can already get to the state you want to watch: a story renders it, a Playwright test drives to it, a Vitest test mounts it. Which of those supplies it decides what travels into a run, where the pixels are painted, and what your baselines end up named, so the choice below starts from the lifecycle you already trust. New to Variance Authority? Your first run takes one UI state through capture, review and acceptance end to end. - [Compose the evidence flow](https://variance-authority.dev/docs/flows/index.md): Six levels run from comparing two revisions inside a single run up to keeping a history that can tell a recurring flake from a slow drift, and each step costs infrastructure somebody has to operate. Pick the smallest one that answers the question your team actually asks: where approved baselines are kept, who reviews a change, and which machine paints the images. - [Place and compare baselines](https://variance-authority.dev/docs/placement/index.md): Approved images have to sit somewhere between runs, one per subject — the named UI state a baseline belongs to, such as a story or a test — and there are three places to put them: committed to the repository, tracked through git-LFS, or stored by a service. They differ in what a clone costs, who can approve a change, and what happens to the repository as history grows. This page is the reference for choosing one while you set a project up. - [Record why a baseline changed](https://variance-authority.dev/docs/changelog/index.md): A baseline PNG records what the interface should look like. It records nothing about the change you approved to get there, so the explanation is written down beside it and npx variance changelog reads it back later. Start here if you own baseline updates and somebody will eventually ask why an image looks the way it does. - [Find changes that keep returning](https://variance-authority.dev/docs/history/index.md): Every run writes a report and does not keep the one before it. A history service keeps them, so drift that no single comparison was wrong about can still be asked about as a sum. - [Share evidence across systems](https://variance-authority.dev/docs/sharing/index.md): A share is a store where CI publishes what each run found, for commands on your checkout to read. variance ask and variance serve answer questions about CI's latest run from the report that run wrote, when your checkout has no run of its own. variance select names the test files a change lets you skip, and variance review counts the changed code no test covered; where your checkout has no recording to measure the change from, both read which tests ran which lines on your mainline, the branch your other branches merge into. variance share publishes a run, or prints how far the mainline's latest publish is from your checkout. - [Choose where the cache lives](https://variance-authority.dev/docs/cache/index.md): The cache is one directory where variance-authority keeps what it can rebuild from your checkout or fetch again from a share: the test-selection recording, the source index, the renders a run took, the suite indexes a share publishes, what a git share fetched, and the suite records select and review read from your mainline. You set where it is with cacheRoot in the variance.config.json at the repository root. When cacheRoot is not set, it is nodemodules/.cache/variance-authority inside the checkout. Every command, every test runner integration and every function that takes a cacheRoot option read that one answer, so a recording written by yarn test is the recording variance select reads. - [Fit into a screenshot suite](https://variance-authority.dev/docs/replacing/index.md): Taking a suite off Percy, Chromatic or Argos is not one decision but one per harness, and the toHaveScreenshot assertions that already work are usually worth keeping. This page takes one harness at a time and says what stays yours, what you add, what the change buys and what it costs, so you can adopt at a single boundary instead of rebuilding the workflow around it. For the vendor tradeoffs in full, see how it compares and where a build gate fits; for the exact APIs, the surface reference. - [Build gates and execution](https://variance-authority.dev/docs/gates/index.md): A hosted visual-regression service bills per snapshot and keeps your baselines on its side of the network. Variance Authority runs that comparison in your own build job, against baselines in your own repository. ## Agents - [Choose an agent workflow](https://variance-authority.dev/agents/index.md): Three questions with three different owners: a hung test, a screenshot that changed, and a symbol you cannot name. Only the last can be answered without a run behind it. Each is matched below to the reading it needs and the guide that sets that reading up. - [Everything an agent can ask](https://variance-authority.dev/agents/questions/index.md): Start from what you kept — a finished report, a watcher still attached to the suite, a record that keeps Eyes journals, or a checkout alone — and take the entrance you have: - [Review a change against what the code did](https://variance-authority.dev/agents/code-review/index.md): A review has the diff, and the diff is the one thing that cannot show whether the changed lines are watched. Two readings answer that from the same change set: the execution record records which named cases covered each changed region, and composition counts how many of the subjects it affected are one decision. Both join a change set against what a run recorded at one revision, with no baseline anywhere in them, which is why an agent holding a patch can ask both before it forms an opinion. - [Read what one test ran](https://variance-authority.dev/docs/test-stories/index.md): A test story is the order one test ran its code in, written out as numbered steps: each function the test ran, the branch it took at each if, how many times each loop ran, the values each function was handed, and the lines the code printed. Every run already records which code each test ran. A story adds the order, the counts, the values and the printed lines, and you read it from top to bottom. When a test fails only on some runs, you compare the stories of runs that passed with runs that failed. When one test passes and another fails, such as the same checkout with a feature flag off and on, you compare the stories of the two tests. Either way what each function was handed is compared with the rest, and any other value you suspect you print from the code under test, never from the test. - [Ask about the code and its runs from the command line](https://variance-authority.dev/agents/cli/index.md): variance ask answers an agent's questions from a shell, with no client configuration. Questions about the code read the checkout and need nothing else: with no run yet, start with variance ask packages, which lists what each package publishes and how much of it other packages import. Questions about a run read the report it wrote, or the report CI published for your branch or mainline when none is on disk: start with variance ask summary. Other questions read a suite that is still running, or how long each part of the suite took on the mainline's last build, and variance distill reads one finished test's Eyes and Sense evidence. Each command calls the same analyzer its MCP counterpart calls. - [Query evidence over MCP](https://variance-authority.dev/agents/mcp/index.md): A finished run leaves .variance/report.json, and an agent handed that file by copy and paste only ever sees the part you pasted. Connected over MCP it reads the whole report itself — what changed, and what changed it. The server answers only from the report it is given: it never runs a test, re-renders a state, or promotes a baseline. - [Inspect a live run](https://variance-authority.dev/agents/live-run/index.md): While your suite is running there is no file to open. The only account of which tests have started, what each has announced, and which announced work has not ended is in the memory of a watcher process that was listening at the time — so start one before the suite, read it from a shell or an MCP client while the run is in flight, and expect that account to end when the watcher does. - [Interrogate a test where it stands](https://variance-authority.dev/agents/interrogate/index.md): A failure that will not reproduce by hand is only visible while the test is still standing in it. You can stop a Playwright test at a line you choose — page up, network in whatever state the test left it — and look at that moment from another shell, or hold a request open to see what the UI does with a reply that has not come. ## Comparisons - [Compare with the tool you have](https://variance-authority.dev/reference/comparison/index.md): Variance Authority keeps a record of what your code did: which tests ran which parts of which modules, what each captured UI state painted, and which component and source file drew each part of it. Several kinds of tool you may already run answer one of those questions, each from its own data. This page sends you to the comparison for the tool you have, and each of those pages ends with how to run Variance Authority beside it. - [Compare visual review tools](https://variance-authority.dev/reference/compare-visual-review/index.md): You are weighing Playwright's built-in toHaveScreenshot, Percy, Chromatic, Argos, Applitools and Variance Authority against each other, and their own pages do not agree on which axes decide it. This page sets the six side by side on what each captures for a subject, where its pixels are painted, who approves a diff, and what that costs in privacy, browser coverage and money. §6 is where you install beside the tool you already have. For test selection and coverage reporting, compare with the tool you already have. - [Compare coverage services](https://variance-authority.dev/docs/compare-coverage/index.md): You probably report coverage already, with Codecov, Coveralls, or a CI step that prints the Istanbul or c8 summary. Those tools report how many lines ran, added up over the whole suite. So they cannot tell you which test ran a line, whether a line runs only under your end-to-end tests, or why the number fell on this pull request. Variance Authority counts the same kind of number from a record that keeps which test ran each part of each module, so the answer to all three is in the report: ## Case studies - [Zod: 57% fewer test file runs](https://variance-authority.dev/docs/selection-zod/index.md): Zod is one package, and 196 of its 202 test files reach the code they exercise through a single barrel. A selector that decides at the grain of a package therefore has nothing to say about it, and a selector that decides at the grain of a file has little more: change one line in the core and either one selects most of the suite. Run the suite once through Variance Authority and a one-line edit selects 8 runs, because the record shows which of the files that reach a module covered the lines you changed. - [TanStack Query: 78% fewer test file runs than Nx](https://variance-authority.dev/docs/selection-tanstack-query/index.md): TanStack Query is 27 packages, so a package-grain selector already has a useful answer: change query-core and it runs the 24 packages that depend on it. That is the correct answer to the question a graph answers, and it is 168 of the 188 test files. Run the suite once through Variance Authority and the record answers the question you wanted asked — which tests covered the lines you changed — with 9. ## Reference - [Source index format](https://variance-authority.dev/docs/source-index/index.md): Two scans of the same unchanged checkout should not do the same work twice. The source index is where the first one leaves its answer for the second. - [Source structures](https://variance-authority.dev/docs/source-structures/index.md): Set source: { relations: true } in your config and variance run --since stops running the whole suite for every edit. It walks from the files the diff touched to the components that rest on them, and prints the chain it walked: - [Source scan](https://variance-authority.dev/docs/source/index.md): The source scan is what stands behind a report that names a component your change did not obviously touch. It reads your checkout without executing any of it, and everything that decides what work a change can affect walks what it wrote. - [Execution record](https://variance-authority.dev/docs/execution-record/index.md): This page is the reference for the file your suite writes when it runs. The record holds which parts each test actually covered, so a changed line can select from witnessed execution instead of every test a static import graph can reach. Blocks, the coverage file, and journals make that distinction queryable. - [How the test-to-code map stays small](https://variance-authority.dev/docs/how-selection-scales/index.md): Selection needs a record of which tests covered which code. Recorded naively that is one entry for every test against every line it touched, which no large repository can store. Variance Authority records it differently, and you want to know what that costs before you put it on a tree that size. - [How different languages are handled](https://variance-authority.dev/docs/polyglot/index.md): Variance Authority is built for React frontends, and that is what most of these pages are about. That does not mean it only reads JavaScript. Its own checkout is TypeScript over a Rust scanner, so the first repository it could not read in full was its own — and it now reads JavaScript and TypeScript in every dialect, stylesheets, Python, Rust, Java, Kotlin and Swift. One reader per language writing into one graph with one kind of node is what polyglot means here, and a diff that spans several of them is answered in one walk. - [Presentation evidence](https://variance-authority.dev/docs/presentation-reference/index.md): This page is the field reference for presentation evidence: measurements of how one rendered interface groups, separates, aligns, repeats, paints and emphasizes its content. Read it when you are choosing an entry point, reading a field of a report, or working out which rule fired and on what measurement. The evidence gives a person or a coding agent numbers they can inspect and challenge; it never supplies a global score, a preferred density, or a design verdict. - [React framework evidence](https://variance-authority.dev/docs/framework-reference/index.md): @variance-authority/react reads React's own record of a page — the fibers react-dom leaves behind on the DOM nodes it created — so a comparison can report differences the rendered document does not contain: a dropped memo, a list keyed by array position, a component rebuilt where it should have been updated. - [Observability contracts](https://variance-authority.dev/docs/observability/index.md): A finished run (one execution of variance run) gives you one bit per subject — one named UI state you asked for and can ask for again, whether that is a story, a route, a fixture or a value — and that bit is pass or fail. Read this page to decide which of the other things a run can keep are worth keeping, and what each one is and is not evidence of. - [Connect a suite](https://variance-authority.dev/docs/surface/index.md): You already have a suite that gets the app into the UI states you care about. To put those states under review by Variance Authority, you install one package built for your host, and keep everything else. - [Records and retention](https://variance-authority.dev/docs/information/index.md): Run variance run once and look at what it leaves on disk: a report at .variance/report.json, PNGs beside it, an approved baseline directory it only updates when you accept a change, and entries in your cache. - [Architecture](https://variance-authority.dev/docs/architecture/index.md): Three questions decide how much machinery you need: is there anything to do at all, what exactly changed, and will this subject — one named UI state you point the tools at, a story, a route, a fixture or a value — even hold still. One set of tools covers all three, and this page is how they fit together and which package each one lives in. - [Metric definitions](https://variance-authority.dev/docs/metrics/index.md): This page specifies nine metrics — M1–M9 — for judging visual-regression evidence, giving the unit, denominator and evidence boundary of each. It reports no readings. The readings the repository can substantiate, with their counts, timings and the test files that produce them, are in Evidence instruments; replacement gates turns those readings into an adoption decision, and product comparison covers capability and ownership differences. - [Repository scale](https://variance-authority.dev/docs/scale/index.md): You are sizing this for a repository of several hundred thousand files and want to know whether it fits before you commit to it. Deciding which tests a change can skip obliges you to keep files on disk; below are what they weigh, what a question against them costs, and where the answer stops being worth having. - [Repository scanning performance](https://variance-authority.dev/docs/performance/index.md): Before a Variance Authority run can decide which subjects — a subject is one named UI state you asked for and can ask for again — a change could have reached, something has to read your repository: every module opened, parsed, and every specifier in it resolved. It is the part of a run that grows with your repository rather than with your suite, and a suite of any size pays it once. - [Native code](https://variance-authority.dev/docs/native-code/index.md): Installing Variance Authority does not need a compiler. There is no cargo, no rustc, no node-gyp and no build step on install: the compiled code arrives as prebuilt binaries that your package manager downloads for your platform, and no package in this product runs an install or postinstall script. - [Package reference](https://variance-authority.dev/reference/packages) ## Package reference - [cli](https://variance-authority.dev/reference/packages/cli/index.md): Run the Variance Authority workflow from a project config: collect subjects, compare, render what changed, report, accept. - [core](https://variance-authority.dev/reference/packages/core/index.md): The Variance Authority format, rules, comparison, attribution and verdicts. Pure data in, pure data out, no DOM and no I/O. - [distill](https://variance-authority.dev/reference/packages/distill/index.md): Find the code one test loads but never uses, and get a concrete substitution to try. - [dom](https://variance-authority.dev/reference/packages/dom/index.md): Extract a Variance Authority capture from a mounted element, under jsdom or a browser, with CSS applicability pruning. - [editors](https://variance-authority.dev/reference/packages/editors/index.md): The Variance Authority plugins for VS Code and JetBrains IDEs, built and ready to install: which test cases went through each line, in the gutter. - [event](https://variance-authority.dev/reference/packages/event/index.md): Announce what the code decided, so a test waits for the decision instead of guessing when it was made. - [eyes](https://variance-authority.dev/reference/packages/eyes/index.md): Record which DOM elements a test addresses and preserve their React attribution before the rendered tree changes under it. - [help](https://variance-authority.dev/reference/packages/help/index.md): Find the public name, signature, documentation, consumers and import sites of an exported workspace symbol, over MCP. - [history](https://variance-authority.dev/reference/packages/history/index.md): Retain visual-regression observations across runs and answer churn, flakiness, reach and token-drift questions. - [ioc](https://variance-authority.dev/reference/packages/ioc/index.md): Wiring a test run drives and a production build ignores: declare how a module resets its own state, and let the runner decide when. - [isolator](https://variance-authority.dev/reference/packages/isolator/index.md): A build transform that gives a module's mutable state one value per session, so each test, request or run starts from the values the module was loaded with. - [jest-transformer](https://variance-authority.dev/reference/packages/jest-transformer/index.md): Run a project's own Jest transformer inside yours: loaded the way Jest loads it, handed its own options, and asked which files Jest calls tests. - [jsx-source](https://variance-authority.dev/reference/packages/jsx-source/index.md): Carry the file and line that wrote a JSX element as far as the rendered DOM node. - [mcp](https://variance-authority.dev/reference/packages/mcp/index.md): Let an agent ask questions about a test run that has already finished. - [observe](https://variance-authority.dev/reference/packages/observe/index.md): Compare render documents or rasters and receive one Variance Authority observation, whatever produced the images. - [package](https://variance-authority.dev/reference/packages/package/index.md): Read a TypeScript workspace API surface as data: every entrypoint a manifest opens and what each one exports, for release and breaking-change checks. - [playwright](https://variance-authority.dev/reference/packages/playwright/index.md): A persistent Playwright harness and renderer for Variance Authority: one browser per run, documents turned into rasters. - [playwright-test](https://variance-authority.dev/reference/packages/playwright-test/index.md): Add a source-aware visual observation to a Playwright test that already gets the app into the state. - [png](https://variance-authority.dev/reference/packages/png/index.md): Decode, compare and diff PNGs without a browser: two buffers in, a mask out. - [png-sharp](https://variance-authority.dev/reference/packages/png-sharp/index.md): Faster PNG decoding for Variance Authority through sharp, for runtimes that can load a native addon. - [presentation](https://variance-authority.dev/reference/packages/presentation/index.md): Measure how a rendered interface groups, separates, aligns and emphasizes its content, and return those measurements as data a test or an agent can read. - [raster](https://variance-authority.dev/reference/packages/raster/index.md): Measure a difference that was never zero, watch it drift, and refuse to photograph a subject that will not hold still. - [react](https://variance-authority.dev/reference/packages/react/index.md): Read React provenance from rendered DOM nodes: owner chains, props digests and portals, without importing the app’s React. - [reads](https://variance-authority.dev/reference/packages/reads/index.md): Say, on the element that shows it, which files a page showed, so an edit to one of them photographs only the pages that show it. - [remote](https://variance-authority.dev/reference/packages/remote/index.md): Run a Variance Authority renderer or baseline store on the other side of an HTTP hop. - [report](https://variance-authority.dev/reference/packages/report/index.md): The shape a Variance Authority run leaves behind, so a person, a pull request and an agent read one format. - [route-collector](https://variance-authority.dev/reference/packages/route-collector/index.md): Turn pages your application already serves into Variance Authority subjects. - [scenario](https://variance-authority.dev/reference/packages/scenario/index.md): Record runtime scenarios as AAA state machines and assess variance across witnessed transitions. - [sense](https://variance-authority.dev/reference/packages/sense/index.md): Which components and tests a source change reaches: test selection and impact analysis from a versioned index of a checkout. - [server](https://variance-authority.dev/reference/packages/server/index.md): A self-hosted HTTP history service for Variance Authority observations and approvals. - [session](https://variance-authority.dev/reference/packages/session/index.md): Run many Variance Authority subjects in one standing DOM world, and detect cross-pollution rather than prevent it. - [store](https://variance-authority.dev/reference/packages/store/index.md): Variance Authority baselines on a filesystem, in a plain directory or through git-LFS. - [storybook](https://variance-authority.dev/reference/packages/storybook/index.md): Storybook index parsing, subject planning and a host-neutral preview driver. - [storybook-collector](https://variance-authority.dev/reference/packages/storybook-collector/index.md): Turn a built or already-served Storybook into Variance Authority subjects. - [tribunal](https://variance-authority.dev/reference/packages/tribunal/index.md): A self-hosted review service for Variance Authority baselines, history and per-subject decisions. - [unit-test](https://variance-authority.dev/reference/packages/unit-test/index.md): Put the states your unit suite already mounts in jsdom into visual regression review, without launching a browser in the test process. - [vantage](https://variance-authority.dev/reference/packages/vantage/index.md): What a run has reported, while it is still running. Kept in a process that outlives the test, so a suite in flight is something to look at rather than something to wait for. - [vitest-browser](https://variance-authority.dev/reference/packages/vitest-browser/index.md): Observe a component against its baseline from inside a Vitest browser-mode test, without leaving the test body. - [wire](https://variance-authority.dev/reference/packages/wire/index.md): How a process under test answers the run that started it: one id per execution, one address to answer on, and nothing written down.