CLI Workflow

Cappa provides a focused CLI with commands that mirror the visual regression lifecycle. Each command operates on the screenshots defined in your cappa.config.ts file.

cappa capture

Runs Playwright to render every configured scenario and writes the resulting images to the configured outputDir. Use flags such as --log-level to adjust verbosity when diagnosing flaky tests.

Use --ci to run capture in CI mode. In CI mode, Cappa executes the onFail callback after capture, if any screenshots fail comparison.

# capture screenshots locally
cappa capture

Cappa also enables the same CI mode automatically when CI=true is set in the environment, so cappa capture behaves like cappa capture --ci in most CI/CD pipelines.

Use --filter (or -f) to capture only tasks whose id matches a glob pattern. This is useful when you want to iterate on a single component without re-capturing everything. The pattern is matched against each task’s id using Node’s built-in glob matching.

# capture only button stories
cappa capture --filter "button*"

# capture a single story by exact id
cappa capture -f "card--default"

When a filter is active, Cappa displays a hint box and logs how many tasks matched per plugin so you can verify the pattern is selecting what you expect.

cappa review

Launches an interface for comparing the latest screenshots against the approved baseline. The review step highlights diffs so you can decide whether the change is expected. Screenshots are grouped and sorted by status so that new, deleted, changed, and finally passed screenshots appear in a predictable order while you browse the UI. Pair it with your preferred branching strategy to share reviews with teammates.

The review UI supports batch approval: in grid or list view you can select multiple screenshots (with checkboxes and “Select all”), then use Approve selected to promote them to the baseline in one action. On category pages (e.g. New or Changed), Approve all in category approves every screenshot in the current view at once.

When diff.interpret is enabled, changed screenshots also show a severity badge, a summary banner and interactive, color-coded region overlays on the diff view so you can see at a glance what changed and where.

cappa approve

Promotes the currently reviewed screenshots to the baseline. This command is typically run after a manual review or as a final step in an automated pipeline when the diffs are accepted.

During approval Cappa re-compares the latest actual image against the existing baseline and only updates the expected file when they truly differ. This prevents identical images with minor binary differences from needlessly churning in version control and keeps your baseline commits tidy.

Use --filter to approve only a subset of screenshots by name or path. Matching is a case-insensitive substring search, so --filter button matches Button/Primary, Button/Secondary, and so on. Pass the flag multiple times to supply more than one pattern — a screenshot is approved if it matches any of them.

cappa approve --filter Button --filter Input

cappa status

Summarizes the state of your screenshot directory, showing how many files are pending approval and whether any captures are missing. When any screenshots are new, changed, or deleted, the command exits with code 1, making it suitable as a CI/script gate:

cappa status && deploy.sh

When diff.interpret is enabled, status also prints a per-screenshot breakdown of the changed screenshots, including the diff percentage, severity, region count and a human-readable summary of what changed.

Tip: combine the commands with npm scripts to make common workflows easy to discover for the rest of your team.