Visual Testing

The catalogue integrates with Playwright for visual regression testing. Screenshots are captured for each scenario across themes and breakpoints.

Setup

Install Playwright

npm install -D @playwright/test
npx playwright install

Configure Breakpoints

In catalogue.config.ts:

export default {
  playwright: {
    breakpoints: [
      { name: 'mobile', width: 375, height: 667 },
      { name: 'tablet', width: 768, height: 1024 },
      { name: 'desktop', width: 1280, height: 800 },
    ],
    themes: ['light', 'dark'],
    screenshotDir: './screenshots',
  },
};

Running Tests

Basic Test Run

catalogue test

This will:

1. Validate the registry
2. Build the static site
3. Generate test cases for all scenarios
4. Run Playwright tests
5. Compare against baseline screenshots

Update Baselines

When you intentionally change component appearance:

catalogue test --update

Debug Mode

Run with browser visible:

catalogue test --headed

Test Matrix

Tests are generated for each combination of:

• Scenarios: All scenarios in the registry
• Themes: light and dark (configurable)
• Breakpoints: Configured viewport sizes

For example, with 10 scenarios, 2 themes, and 3 breakpoints:

10 × 2 × 3 = 60 screenshot tests

Harness Routes

Each scenario has a harness URL for direct access:

/#/harness/<scenario-id>

Query Parameters

Parameter	Description	Example
theme	Theme override	?theme=dark
w	Width in pixels	?w=375
h	Height in pixels	?h=667
bg	Background color	?bg=%23f5f5f5

Examples:

/#/harness/button-primary
/#/harness/button-primary?theme=dark
/#/harness/button-primary?theme=light&w=320&h=480
/#/harness/card-default?bg=%23000000

Screenshot Organization

Screenshots are saved to the configured directory:

screenshots/
├── button-button-primary-light-default.png
├── button-button-primary-dark-default.png
├── button-button-primary-light-375x667.png
├── button-button-primary-dark-375x667.png
├── button-button-primary-light-1280x800.png
└── button-button-primary-dark-1280x800.png

Naming format: {componentId}-{scenarioId}-{theme}-{viewport}.png

Scenario-Specific Viewports

Override viewport per scenario:

{
  "id": "button-small-viewport",
  "componentId": "button",
  "viewport": {
    "width": 200,
    "height": 100
  },
  "render": {
    "element": "my-button",
    "slots": { "default": "Click" }
  }
}

Custom Backgrounds

Set scenario background:

{
  "id": "dark-card",
  "componentId": "card",
  "background": "#1a1a1a",
  "render": {
    "element": "my-card"
  }
}

CI Integration

GitHub Actions

name: Visual Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '23'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright
        run: npx playwright install --with-deps chromium

      - name: Run visual tests
        run: npx catalogue test

      - name: Upload screenshots
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: screenshots
          path: |
            screenshots/
            playwright-report/

Updating Screenshots in CI

For PRs that intentionally change visuals:

- name: Update screenshots
  if: contains(github.event.pull_request.labels.*.name, 'update-screenshots')
  run: npx catalogue test --update

Playwright Configuration

The catalogue generates a Playwright config at .catalogue-tests/playwright.config.ts. You can extend it by adding a playwright.config.ts at your project root.

Default Configuration

// Generated config
export default {
  testDir: '.catalogue-tests',
  snapshotDir: './screenshots',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  use: {
    baseURL: 'http://localhost:5173',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
  webServer: {
    command: 'npx vite preview --port 5173',
    port: 5173,
  },
};

Troubleshooting

Screenshots Don’t Match

1. Font rendering: Different OS render fonts differently
   • Use web fonts or Docker for consistent rendering
2. Animations: Disable or wait for animations
3. Dynamic content: Mock dates, random data

Tests Timeout

Increase timeout in config:

export default {
  playwright: {
    // Tests might need more time
  },
};

Missing Browsers

npx playwright install chromium

Best Practices

1. Baseline Management
   • Commit screenshots to version control
   • Review diffs in PRs
   • Use meaningful scenario names
2. Consistent Environment
   • Use Docker for CI
   • Pin browser versions
   • Use web fonts
3. Focused Tests
   • One visual state per scenario
   • Avoid testing layout (browser-dependent)
   • Focus on component appearance
4. Maintenance
   • Update baselines intentionally
   • Document visual changes in PRs
   • Clean up unused scenarios

Next Steps

• CLI Reference
• Configuration