VARIANCE AUTHORITY
BrowseReview coverage on every pull request

Your test suite

Review coverage on every pull request

A Jest or Vitest library on GitHub can get one comment on each pull request that names the changed functions no test ran and what the change stopped running that its main branch ran. The comparison with the main branch is kept between runs in the GitHub Actions cache, and a badge on the README is one more line. Your workflow names your test command and one action.

Record your tests

The comment reads which functions each test ran, which your tests record when their configuration is wrapped. Install the recorder and the command line that reads what it records, with your package manager:

npm install --save-dev @variance-authority/sense @variance-authority/cli
pnpm add --save-dev @variance-authority/sense @variance-authority/cli
yarn add --dev @variance-authority/sense @variance-authority/cli

Keep the Jest configuration you have and wrap what it exports. Jest refuses two configuration files, so do not add a second one beside it. A jest.config.js in CommonJS:

// jest.config.js
const { withTestSelection } = require('@variance-authority/sense/jest');

module.exports = withTestSelection({
  preset: 'ts-jest',
  testEnvironment: 'node',
});

A preset and a transform with its own options stay as they are: the wrap keeps each transformer, on the same pattern with the same options, and wraps it, so copy nothing from a preset into your file. In a jest.config.mjs or jest.config.ts, import { withTestSelection } from '@variance-authority/sense/jest' and wrap the default export the same way. For Vitest, wrap defineConfig in the configuration you have:

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

export default withTestSelection(defineConfig({ test: {} }));

Then name the tests in variance.config.json at the repository root. unit is the name the workflow uses for them, and "carry": "actions-cache" keeps what they ran in the GitHub Actions cache between runs:

{
  "suites": { "unit": { "kind": "unit", "carry": "actions-cache" } }
}

In CI the action keeps its working files, the review and what each push ran, under .variance/ in the checkout. Add .variance/ to your .gitignore, so those files are never committed from a checkout where they were made.

Check it on your machine

The CLI needs Node 22.15 or newer, on your machine as in CI. Raise only the Node you run: .nvmrc, and node-version in the workflow. Leave engines in package.json alone; it says what your library asks of its users. Run your tests once with your usual command, then name a source file they import, in place of src/index.ts:

variance covering --file src/index.ts

On the first run it says it is building its source index from the checkout; that line is expected. Then it prints the suite, unit (unit):, the file with how many recorded ranges and named tests reached it, and how long ago that run landed. Named tests on the file mean the wrap recorded them; no line for unit means the tests ran without the wrap. On your machine the record is kept under node_modules/.cache/, not under .variance/.

Add the job

This is the whole workflow, for npm and Jest. If you already have a test job, replace its test step with the action rather than adding this workflow beside it, or your tests run twice. When that job runs a matrix of Node versions, keep it as it is and add the review job beside it, once, in the same workflow:

name: tests
on:
  push:
    branches: [main] # your default branch: master, if that is its name
  pull_request:

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read # the checkout, and nothing it could write with
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0 # the review reads the change from where it starts
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 24 # the CLI needs 22.15 or newer
      - run: npm ci
      - uses: Variance-Authority/action/review@v1
        with:
          suite: unit
          test: npx jest
          comment: 'false' # hand the review to the job below

  post:
    needs: review
    if: ${{ !cancelled() && needs.review.result != 'skipped' }}
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write # the comment
    steps:
      - uses: Variance-Authority/action/review@v1
        with:
          from: variance-review

The action runs test, reviews what it ran, and saves the record: which functions each test ran. A push to the default branch saves the record every pull request compares with. A pull request's push saves what the next push of the same pull request reads. A failing test still gets its comment, then fails the job with the test's exit code.

Two jobs, because the first runs the pull request's code: a test, or a package it installs, can read whatever token its job holds, and GitHub stops what a step left running only when the job ends. So that job can read and nothing more, and the post job, which checks nothing out and runs no code of the pull request, holds the write token and posts what the first handed it.

test and the install step are your own; the action installs nothing, so whatever your tests need first, such as a build, is a step before it. Keep the steps that set up your package manager, such as pnpm/action-setup and setup-node's cache:. With pnpm, run pnpm install --frozen-lockfile and set test: pnpm exec jest or pnpm exec vitest run; with Yarn, yarn install --immutable (--frozen-lockfile on Yarn 1) and test: yarn jest.

The first runs

Until your default branch has run the job once, the comment says it has nothing to compare with, and still names the changed functions this run's tests did not reach. Merge the workflow, let the default branch run it, and the next pull request compares with that record. On a push there is no pull request, so the review goes to the job's summary.

A pull request from a fork gets a token that cannot comment. The review is still in the job's summary, and the post job warns rather than fails.

Require it, or show a badge

Both are inputs of the review job's step:

- uses: Variance-Authority/action/review@v1 # in `review`
  with:
    suite: unit
    test: npx jest
    comment: 'false'
    fail-on-uncovered: 'true'
    badge: 'true'

fail-on-uncovered fails the review job, after it hands the review on, when a changed function holds code no test ran. Name the review job as a required check in your branch rule, and such a pull request cannot merge until a test runs it.

badge publishes, on every push to the default branch, the share of regions your tests ran: a region is a function, a branch, or a run of statements with no decision in it, so the figure is lower than line coverage. The action pushes it as one file to the git ref refs/badge/<default-branch>, replaced each time, for a shields.io endpoint badge. The review job counts the figure and hands it on; the post job pushes it, so give that one contents: write beside pull-requests: write. Put the badge in your README with your owner, repository and default branch:

[![regions run](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2F<owner>%2F<repo>%2Frefs%2Fbadge%2F<default-branch>%2Fregions-run.json)](https://github.com/<owner>/<repo>/actions)

The badge is for a public repository: shields.io cannot read a private one.

Go deeper