/visual-regression

name: visual-regression
description: Setup visual regression testing with Storybook stories, configuration, and CI/CD workflows. Supports Chromatic, Percy, BackstopJS. Auto-invoke when user says "set up visual regression", "add Chromatic tests", "add screenshot testing", or "set up Percy".
allowed-tools: Read, Write, Bash, Glob
version: 1.0.0
triggers:
  - "set up visual regression"
  - "add chromatic tests"
  - "create visual tests"
  - "configure visual regression"
  - "add screenshot testing"
  - "set up percy"
  - "add backstopjs"

Visual Regression Testing Setup Skill

---

Skill Purpose

Generate complete visual regression testing setup with Storybook stories, configuration files, and CI/CD workflows.

**Supports**: Chromatic, Percy, BackstopJS **Frameworks**: React, Vue, Svelte (TypeScript/JavaScript) **CI/CD**: GitHub Actions, GitLab CI, CircleCI

---

What This Skill Does

1. **Detects existing setup**: Storybook version, VR tool, CI platform 2. **Validates component**: Extract props, variants, states 3. **Generates stories**: Complete `.stories.tsx` with all variants 4. **Creates config files**: Chromatic, Percy, or BackstopJS configuration 5. **Sets up CI/CD**: Auto-generate workflow files 6. **Provides instructions**: Next steps for API tokens, first baseline

---

Workflow

Step 1: Validate Project Setup

**Execute**: `vr_setup_validator.py`

**Check**:

• Framework (React/Vue/Svelte) from package.json
• Existing Storybook config (.storybook/ directory)
• Existing VR tool (chromatic, percy, backstopjs in dependencies)
• CI platform (.github/, .gitlab-ci.yml, .circleci/)
• Component file exists and is valid

**Output**:

{
  "framework": "react",
  "storybook_version": "7.6.0",
  "vr_tool": "chromatic",
  "ci_platform": "github",
  "component": {
    "path": "src/components/ProfileCard.tsx",
    "name": "ProfileCard",
    "props": [...],
    "valid": true
  },
  "dependencies": {
    "installed": ["@storybook/react", "@storybook/addon-essentials"],
    "missing": ["chromatic", "@chromatic-com/storybook"]
  }
}

**If Storybook not found**: Ask user if they want to install Storybook first, provide setup instructions.

**If multiple VR tools found**: Ask user which to use (Chromatic recommended).

---

Step 2: Generate Storybook Stories

**Execute**: `story_generator.py`

**Process**: 1. Parse component file (TypeScript/JSX/Vue SFC) 2. Extract props, prop types, default values 3. Identify variants (size, variant, disabled, etc.) 4. Generate story file from template 5. Add accessibility tests (@storybook/addon-a11y) 6. Add interaction tests (if @storybook/test available)

**Template**: `templates/story-template.tsx.j2`

**Example output** (`ProfileCard.stories.tsx`):

import type { Meta, StoryObj } from '@storybook/react';
import { ProfileCard } from './ProfileCard';

const meta = {
  title: 'Components/ProfileCard',
  component: ProfileCard,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    size: { control: 'select', options: ['sm', 'md', 'lg'] },
    variant: { control: 'select', options: ['default', 'compact'] },
  },
} satisfies Meta<typeof ProfileCard>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Default: Story = {
  args: {
    name: 'John Doe',
    avatar: 'https://example.com/avatar.jpg',
    bio: 'Software Engineer',
    size: 'md',
    variant: 'default',
  },
};

export const Small: Story = {
  args: {
    ...Default.args,
    size: 'sm',
  },
};

export const Large: Story = {
  args: {
    ...Default.args,
    size: 'lg',
  },
};

export const Compact: Story = {
  args: {
    ...Default.args,
    variant: 'compact',
  },
};

// Accessibility test
Default.parameters = {
  a11y: {
    config: {
      rules: [
        { id: 'color-contrast', enabled: true },
        { id: 'label', enabled: true },
      ],
    },
  },
};

**Write to**: `{component_directory}/{ComponentName}.stories.tsx`

---

Step 3: Generate Configuration Files

**Execute**: `chromatic_config_generator.py` (or percy/backstop equivalent)

For Chromatic:

**Generate 3 files**:

1. **chromatic.config.json**:

{
  "projectId": "<PROJECT_ID_PLACEHOLDER>",
  "buildScriptName": "build-storybook",
  "exitZeroOnChanges": true,
  "exitOnceUploaded": true,
  "onlyChanged": true,
  "externals": ["public/**"],
  "skip": "dependabot/**",
  "ignoreLastBuildOnBranch": "main"
}

2. **Update .storybook/main.js** (add addon):

module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@chromatic-com/storybook', // ← Added
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
};

3. **Update package.json** (add scripts):

{
  "scripts": {
    "chromatic": "npx chromatic",
    "chromatic:ci": "npx chromatic --exit-zero-on-changes"
  }
}

**For Percy**: Generate `.percy.yml` instead **For BackstopJS**: Generate `backstop.config.js` instead

---

Step 4: Generate CI/CD Workflow

**Execute**: `ci_workflow_generator.py`

**Detect CI platform** from existing files:

• `.github/workflows/` → GitHub Actions
• `.gitlab-ci.yml` → GitLab CI
• `.circleci/config.yml` → CircleCI
• None → Ask user, default to GitHub Actions

GitHub Actions Example:

**Generate**: `.github/workflows/chromatic.yml`

name: Visual Regression Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Required for Chromatic

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run Chromatic
        uses: chromaui/action@latest