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 this command for local development when you don’t need to trigger failure callbacks. Use flags such as --log-level to adjust verbosity when diagnosing flaky tests.

Note: This command does not execute the onFail callback even if failures are detected.

cappa ci

Runs the same capture process as cappa capture, but also automatically executes the onFail callback if any screenshots fail comparison. This command is designed for use in CI/CD pipelines where you want to report failures (e.g., upload diff images to storage or notify external systems).

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.

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.