testing-suite

What this skill does

# Testing Suite Skill

## Overview

Set up and configure comprehensive testing for Storybook 10 components, including interaction tests with play functions, accessibility testing with axe-core, and visual regression testing with Playwright.

This skill provides guidance on implementing modern component testing patterns using Storybook 10's integrated testing capabilities.

## What This Skill Provides

### Testing Strategy Guidance
Configure the right testing setup based on:
- **Project requirements**: Unit, integration, or end-to-end testing
- **Framework choice**: React Testing Library, Vue Testing Library, Svelte Testing Library
- **Testing scope**: Interaction tests, accessibility, visual regression
- **CI/CD integration**: GitHub Actions, GitLab CI, CircleCI

### Interaction Testing
Set up and write interaction tests using:
- **Play functions**: Simulate user interactions in stories
- **Testing Library**: Query elements by role, text, label
- **User events**: Click, type, keyboard, hover, focus
- **Assertions**: Verify component behavior and state

### Accessibility Testing
Configure accessibility validation with:
- **axe-core integration**: WCAG 2.1 compliance checking
- **ARIA validation**: Roles, labels, descriptions
- **Keyboard navigation**: Tab order, focus management
- **Screen reader support**: Semantic HTML, announcements
- **Color contrast**: WCAG AA/AAA compliance

### Visual Regression Testing
Set up visual regression tests with:
- **Playwright integration**: Real browser screenshots
- **Snapshot comparisons**: Detect unintended visual changes
- **Cross-browser testing**: Chromium, Firefox, WebKit
- **Responsive testing**: Multiple viewport sizes

## Testing Levels

### Level 1: Basic Stories
Stories with args and controls only (no automated tests).

**Best for:**
- Component showcases
- Design system documentation
- Quick prototyping

**Setup:**
```typescript
export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Button',
  },
};
```

### Level 2: Interaction Tests
Stories with play functions that test user interactions.

**Best for:**
- Form components
- Interactive widgets
- State management verification

**Setup:**
```typescript
import { expect, userEvent, within } from 'storybook/test';

export const WithInteraction: Story = {
  args: { children: 'Click me' },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');

    await expect(button).toBeInTheDocument();
    await userEvent.click(button);
    await expect(button).toHaveFocus();
  },
};
```

### Level 3: Accessibility Tests
Stories with axe-core validation rules.

**Best for:**
- Public-facing applications
- Compliance requirements (WCAG 2.1)
- Accessible component libraries

**Setup:**
```typescript
export const AccessibilityValidation: Story = {
  args: { children: 'Button' },
  parameters: {
    a11y: {
      config: {
        rules: [
          { id: 'button-name', enabled: true },
          { id: 'color-contrast', enabled: true },
          { id: 'focus-visible', enabled: true },
        ],
      },
    },
  },
};
```

### Level 4: Full Testing Suite
Combination of interaction tests, accessibility tests, and visual regression.

**Best for:**
- Production applications
- Component libraries
- Critical user flows

## Storybook 10 Testing Features

### Vitest Integration
Storybook 10 uses Vitest as the default test runner:

**Benefits:**
- ⚡ Fast: Runs in real browsers (not JSDOM)
- 📦 Zero config: Works out of the box
- 🎯 Isolated: Each story runs in isolation
- 🔄 Watch mode: Instant feedback on changes

**Setup:**
Add to `package.json`:
```json
{
  "scripts": {
    "test-storybook": "test-storybook"
  }
}
```

### Portable Stories

Run stories directly in unit tests (Vitest/Jest) - perfect for reusable component libraries.

**Why use it:**
- Reuse stories as test cases (no duplication)
- Args, decorators, play functions work automatically
- Test outside Storybook in CI pipelines
- Share components across projects with tests included

**Setup:**
```typescript
// Button.test.tsx
import { composeStories } from '@storybook/react';
import { render, screen } from '@testing-library/react';
import * as stories from './Button.stories';

// Convert all stories to testable components
const { Primary, Disabled, WithIcon } = composeStories(stories);

describe('Button', () => {
  it('renders primary variant', () => {
    render(<Primary />);
    expect(screen.getByRole('button')).toHaveClass('btn-primary');
  });

  it('runs interaction test from story', async () => {
    const { container } = render(<WithIcon />);

    // Play function from story runs automatically
    await WithIcon.play?.({ canvasElement: container });

    expect(screen.getByRole('button')).toHaveFocus();
  });

  it('respects disabled state', () => {
    render(<Disabled />);
    expect(screen.getByRole('button')).toBeDisabled();
  });
});
```

**Single story:**
```typescript
import { composeStory } from '@storybook/react';
import meta, { Primary } from './Button.stories';

const PrimaryButton = composeStory(Primary, meta);

test('primary button', () => {
  render(<PrimaryButton />);
  // Test with all decorators and args applied
});
```

**With custom args override:**
```typescript
const { Primary } = composeStories(stories);

test('custom label', () => {
  render(<Primary>Custom Text</Primary>);
  expect(screen.getByText('Custom Text')).toBeInTheDocument();
});
```

### Playwright Integration
Real browser testing with Playwright:

**Benefits:**
- 🌐 Real browsers: Chromium, Firefox, WebKit
- 📸 Screenshots: Visual regression testing
- 🎬 Video recording: Debug test failures
- 🔍 Tracing: Step-by-step execution

**Setup:**
Storybook 10 includes Playwright by default. Configure in `.storybook/test-runner-jest.config.js`:

```javascript
export default {
  browsers: ['chromium', 'firefox', 'webkit'],
  screenshot: 'only-on-failure',
  video: 'retain-on-failure',
};
```

### Testing Library Integration
Query components using accessible selectors:

**Recommended queries (in order of preference):**
1. `getByRole()` - Semantic HTML roles
2. `getByLabelText()` - Form labels
3. `getByPlaceholderText()` - Input placeholders
4. `getByText()` - Visible text content
5. `getByTestId()` - Last resort only

**Example:**
```typescript
const button = canvas.getByRole('button', { name: /submit/i });
const input = canvas.getByLabelText('Email address');
const heading = canvas.getByRole('heading', { level: 1 });
```

## Common Test Patterns

### Button Component Tests
```typescript
export const ButtonInteraction: Story = {
  args: {
    onClick: fn(),
    children: 'Click me',
  },
  play: async ({ args, canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');

    // Test rendering
    await expect(button).toBeInTheDocument();

    // Test click
    await userEvent.click(button);
    await expect(args.onClick).toHaveBeenCalledTimes(1);

    // Test disabled state
    await expect(button).not.toBeDisabled();
  },
};
```

### Input Component Tests
```typescript
export const InputInteraction: Story = {
  args: {
    label: 'Username',
    onChange: fn(),
  },
  play: async ({ args, canvasElement }) => {
    const canvas = within(canvasElement);
    const input = canvas.getByLabelText('Username');

    // Test typing
    await userEvent.type(input, 'john.doe');
    await expect(input).toHaveValue('john.doe');

    // Test change handler
    await expect(args.onChange).toHaveBeenCalled();

    // Test validation
    await userEvent.clear(input);
    await expect(input).toHaveValue('');
  },
};
```

### Modal Component Tests
```typescript
export const ModalInteraction: Story = {
  args: {
    isOpen: true,
    onClose: fn(),
    title: 'Confirm Action',
  },
  play: async ({ args, canvasElement }) => {
    const canvas = within(canvasElement);
    const dialog = canvas.getByRole('dia