configure-ux-testing

What this skill does

# /configure:ux-testing

Check and configure UX testing infrastructure with Playwright as the primary tool for E2E, accessibility, and visual regression testing.

## When to Use This Skill

| Use this skill when... | Use another approach when... |
|------------------------|------------------------------|
| Setting up Playwright E2E testing infrastructure for a project | Running existing Playwright tests (use `bun test:e2e` or test-runner agent) |
| Adding accessibility testing with axe-core to a project | Performing manual accessibility audits on a live site |
| Configuring visual regression testing with screenshot assertions | Debugging a specific failing E2E test (use system-debugging agent) |
| Setting up Playwright CLI or MCP for Claude browser automation | Writing individual test cases (use playwright-testing skill) |
| Creating CI/CD workflows for E2E and accessibility test execution | Configuring unit or integration tests (use `/configure:tests`) |

## Context

- Package manager: !`find . -maxdepth 1 \( -name 'package.json' -o -name 'bun.lockb' \)`
- Playwright config: !`find . -maxdepth 1 -name 'playwright.config.*'`
- Playwright installed: !`grep -l '@playwright/test' package.json`
- Axe-core installed: !`grep -l '@axe-core/playwright' package.json`
- E2E test dir: !`find . -maxdepth 2 -type d \( -name 'e2e' -o -name 'tests' \)`
- Visual snapshots: !`find . -maxdepth 4 -type d -name '__snapshots__'`
- MCP config: !`find . -maxdepth 1 -name '.mcp.json'`
- CI workflow: !`find .github/workflows -maxdepth 1 -name 'e2e*'`

**UX Testing Stack:**
- **Playwright** - Cross-browser E2E testing (primary tool)
- **axe-core** - Automated accessibility testing (WCAG compliance)
- **Playwright screenshots** - Visual regression testing
- **Playwright CLI** - Browser automation via CLI (preferred for AI agents with shell access)
- **Playwright MCP** - Browser automation via MCP (fallback for sandboxed environments)

## Parameters

Parse from command arguments:

- `--check-only`: Report status without offering fixes
- `--fix`: Apply all fixes automatically without prompting
- `--a11y`: Focus on accessibility testing configuration
- `--visual`: Focus on visual regression testing configuration

## Execution

Execute this UX testing configuration check:

### Step 1: Fetch latest tool versions

Verify latest versions before configuring:

1. **@playwright/test**: Check [playwright.dev](https://playwright.dev/) or [npm](https://www.npmjs.com/package/@playwright/test)
2. **@axe-core/playwright**: Check [npm](https://www.npmjs.com/package/@axe-core/playwright)
3. **@playwright/cli**: Check [npm](https://www.npmjs.com/package/@playwright/cli)
4. **playwright MCP**: Check [npm](https://www.npmjs.com/package/@playwright/mcp)

Use WebSearch or WebFetch to verify current versions.

### Step 2: Detect existing UX testing infrastructure

Check for each component:

| Indicator | Component | Status |
|-----------|-----------|--------|
| `playwright.config.*` | Playwright | Installed |
| `@axe-core/playwright` in package.json | Accessibility testing | Configured |
| `@playwright/test` in package.json | Playwright Test | Installed |
| `tests/e2e/` or `e2e/` directory | E2E tests | Present |
| `*.spec.ts` files with toHaveScreenshot | Visual regression | Configured |
| `@playwright/cli` globally or in package.json | Playwright CLI | Installed |
| `.mcp.json` with playwright server | Playwright MCP | Configured |

### Step 3: Analyze current testing state

Check for complete UX testing setup across four areas:

**Playwright Core:**
- `@playwright/test` installed
- `playwright.config.ts` exists
- Browser projects configured (Chromium, Firefox, WebKit)
- Mobile viewports configured (optional)
- WebServer configuration for local dev
- Trace/screenshot/video on failure

**Accessibility Testing:**
- `@axe-core/playwright` installed
- Accessibility tests created
- WCAG level configured (A, AA, AAA)
- Custom rules/exceptions documented

**Visual Regression:**
- Screenshot assertions configured
- Snapshot directory configured
- Update workflow documented
- CI snapshot handling configured

**Browser Automation:**
- Playwright CLI installed (preferred for agents with shell access)
- Playwright MCP server in `.mcp.json` (fallback for sandboxed environments)
- Browser automation available to Claude

### Step 4: Generate compliance report

Print a formatted compliance report showing status for Playwright core, accessibility testing, visual regression, and MCP integration.

If `--check-only` is set, stop here.

For the compliance report format, see [REFERENCE.md](REFERENCE.md).

### Step 5: Install dependencies (if --fix or user confirms)

```bash
# Core Playwright
bun add --dev @playwright/test

# Accessibility testing
bun add --dev @axe-core/playwright

# Install browsers
bunx playwright install
```

### Step 6: Create Playwright configuration

Create `playwright.config.ts` with:
- Desktop browser projects (Chromium, Firefox, WebKit)
- Mobile viewport projects (Pixel 5, iPhone 13)
- Dedicated a11y test project (Chromium only)
- WebServer auto-start for local dev
- Trace/screenshot/video on failure settings
- JSON and JUnit reporters for CI

For the complete `playwright.config.ts` template, see [REFERENCE.md](REFERENCE.md).

### Step 7: Create accessibility test helper

Create `tests/e2e/helpers/a11y.ts` with:
- `expectNoA11yViolations(page, options)` - Assert no WCAG violations
- `getA11yReport(page, options)` - Generate detailed a11y report
- Configurable WCAG level (wcag2a, wcag2aa, wcag21aa, wcag22aa)
- Rule include/exclude support
- Formatted violation output

For the complete a11y helper code, see [REFERENCE.md](REFERENCE.md).

### Step 8: Create example test files

Create example tests:

1. **`tests/e2e/homepage.a11y.spec.ts`** - Homepage accessibility tests (WCAG 2.1 AA violations, post-interaction checks, full report)
2. **`tests/e2e/visual.spec.ts`** - Visual regression tests (full page screenshots, component screenshots, responsive layouts, dark mode)

For complete example test files, see [REFERENCE.md](REFERENCE.md).

### Step 9: Add npm scripts

Update `package.json` with test scripts:

```json
{
  "scripts": {
    "test:e2e": "playwright test",
    "test:e2e:headed": "playwright test --headed",
    "test:e2e:debug": "playwright test --debug",
    "test:e2e:ui": "playwright test --ui",
    "test:a11y": "playwright test --project=a11y",
    "test:visual": "playwright test visual.spec.ts",
    "test:visual:update": "playwright test visual.spec.ts --update-snapshots",
    "playwright:codegen": "playwright codegen http://localhost:3000",
    "playwright:report": "playwright show-report"
  }
}
```

### Step 10: Configure browser automation (optional)

Choose the appropriate browser automation approach based on the agent's environment:

**Option A: Playwright CLI (preferred when shell access is available)**

Playwright CLI (`@playwright/cli`) is 4-10x more token-efficient than MCP for AI agent browser automation (~27K vs ~114K tokens per task). Snapshots and screenshots are saved to disk instead of injected into context.

```bash
# Global install
npm install -g @playwright/cli@latest

# Or project-local
bun add --dev @playwright/cli
```

This enables Claude to navigate pages, take screenshots, fill forms, click elements, and capture page snapshots via CLI commands. See the `playwright-cli` skill for command reference.

**Option B: Playwright MCP (for sandboxed environments without shell access)**

Use MCP when running in environments without shell access (Claude Desktop, browser-based agents):

```json
{
  "mcpServers": {
    "playwright": {
      "command": "bunx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}
```

### Step 11: Create CI/CD workflow

Create `.github/workflows/e2e.yml` with parallel jobs for:
- E2E tests (all browsers)
- Accessibility tests (Chromium only)
- Artifact upload for reports and failure screenshots

For the complete CI workflow template, see