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.

# local capture only
cappa capture

# capture + onFail callback behavior
cappa capture --ci

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.

The onFail callback receives an array of failed screenshots with both relative and absolute paths to actual, expected, and diff images.

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.

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.

When a diff image is present, Cappa also carries over diff PNG metadata (for example cappa.diff.algorithm and related diff settings) into the approved expected PNG so the baseline retains the comparison context used to generate the accepted change.

If a baseline image no longer has a matching capture (for example, a scenario was removed), running cappa approve now cleans up the orphaned expected file along with any remaining diff image so that your repository stays in sync with the latest set of screenshots.

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.