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.

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.

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.

cappa status

Summarizes the state of your screenshot directory, showing how many files are pending approval and whether any captures are missing. This is useful for scripting custom checks or reporting in CI.

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