configure-ux-testing

/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 or npm
2. @axe-core/playwright: Check npm
3. @playwright/cli: Check npm
4. playwright MCP: Check npm

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.

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

# 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.

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.

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.

Step 9: Add npm scripts

Update package.json with test scripts:

{
  "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.

# 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):

{
  "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 REFERENCE.md.

Step 12: Update standards tracking

Update .project-standards.yaml:

components:
  ux_testing: "2025.1"
  ux_testing_framework: "playwright"
  ux_testing_a11y: true
  ux_testing_a11y_level: "wcag21aa"
  ux_testing_visual: true
  ux_testing_cli: true
  ux_testing_mcp: false

Step 13: Report configuration results

Print a summary of configuration applied, scripts added, and CI/CD setup. Include next steps for starting the dev server, running tests, updating snapshots, and opening the interactive UI.

For the results report format, see REFERENCE.md.

Agentic Optimizations

Context	Command
Quick compliance check	/configure:ux-testing --check-only
Auto-fix all issues	/configure:ux-testing --fix
Accessibility focus only	/configure:ux-testing --a11y
Visual regression focus only	/configure:ux-testing --visual
Run E2E tests compact	bunx playwright test --reporter=line
Run a11y tests only	bunx playwright test --project=a11y --reporter=dot

Flags

Flag	Description
--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

Error Handling

• No package manager found: Cannot install dependencies, provide manual steps
• Dev server not configured: Warn about manual baseURL configuration
• Browsers not installed: Prompt to run bunx playwright install
• Existing config conflicts: Preserve user config, suggest merge

See Also

• /configure:tests - Unit and integration testing configuration
• /configure:all - Run all compliance checks
• Skills: playwright-testing, playwright-cli, accessibility-implementation
• Agents: ux-implementation for implementing UX designs
• Playwright documentation: https://playwright.dev
• axe-core documentation: https://www.deque.com/axe