Configuration

The cappa.config.ts file controls how screenshots are captured, stored, and reviewed. Config files export a configuration created with defineConfig from @cappa/core.

defineConfig accepts either an object or a function that receives a ConfigEnv object with the current CLI command, mode, and environment variables. This is useful when you need to tailor the configuration in CI environments.

import { defineConfig } from '@cappa/core';
import { cappaPluginStorybook } from '@cappa/plugin-storybook';

export default defineConfig(({ env }) => ({
  outputDir: env.CAPPA_SCREENSHOT_DIR ?? 'screenshots',
}));

outputDir

• type: string
• default: 'screenshots'

Folder where screenshots and diffs are written. Cappa will create actual, expected, and diff directories within this folder.

retries

• type: number
• default: 2

The number of times to retry a screenshot if it fails. See the Screenshot retries guide for more information.

concurrency

• type: number
• default: 1

The number of parallel browser contexts to use when taking screenshots. Each context can process screenshots independently, significantly speeding up large screenshot runs.

Higher values will consume more system resources (CPU and memory).

logConsoleEvents

• type: boolean
• default: true

Controls whether Playwright console events are logged while captures run. Disable this when your stories emit frequent console output and you prefer quieter CLI logs.

screenshot

Screenshot configuration might get overwritten by plugins or more specific settings, while taking the screenshot.

screenshot.viewport

• type: { width: number; height: number }
• default: { width: 1920, height: 1080 }

The viewport to use for the screenshots.

screenshot.fullPage

• type: boolean
• default: true

Whether to take a full page screenshot. If false, the viewport will be used.

diff

Diff configuration sets different, global comparison settings for the images.

diff.threshold

• type: number
• default: 0.1
• range: 0-1

This affects how similar a pixel needs to be to the reference image to be considered the same.

diff.includeAA

• type: boolean
• default: false

Whether to include anti-aliased pixels in the diff count. For most users this should be false, because it makes comparisons very sensitive to sub-pixel differences of fonts and other UI elements.

diff.fastBufferCheck

• type: boolean
• default: true

Whether to use a fast buffer comparison for identical images. This is a performance optimization that skips the slower image comparison algorithm.

diff.maxDiffPixels

• type: number
• default: 0

The maximum number of different pixels before the comparison fails.

diff.maxDiffPercentage

• type: number
• default: 0
• range: 0-100

The maximum percentage of different pixels before the comparison fails. This is a relative value, so it is affected by the size of the images. A 100px image with a 10% difference is 10 pixels different, but a 1000px image with a 10% difference is 100 pixels different. On very large full page screenshots this can mean that small changes still slip through.

onFail

• type: (screenshots: FailedScreenshot[]) => void | Promise<void>
• default: undefined

Runs after a capture completes when using the cappa ci command (not cappa capture) if there are screenshots that failed comparison. The callback receives an array of failing screenshots, including both relative and absolute paths to the actual, expected, and diff images. Use this hook to upload diff images to object storage or integrate with CI systems.

onFail: async (screenshots) => {
  // Upload diff images to your storage provider
  for (const screenshot of screenshots) {
    if (screenshot.absoluteDiffPath) {
      await uploadToS3(screenshot.absoluteDiffPath);
      // etc
    }
  }
}

browser

Browser configuration sets different browser settings for playwright.

browser.type

• type: 'chromium' | 'firefox' | 'webkit'
• default: 'chromium'

The browser to use for the screenshots.

browser.headless

• type: boolean
• default: true

Whether to run the browser in headless mode.