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

Context

• Package manager: !find . -maxdepth 1 \( -name 'package.json' -o -name 'bun.lockb' \)
• Playwright config: !find . -maxdepth 1 -name 'playwright.config.*'
• Playwright installed: !find . -maxdepth 1 -name 'package.json' -exec grep -l '@playwright/test' {} +
• Axe-core installed: !find . -maxdepth 1 -name 'package.json' -exec grep -l '@axe-core/playwright' {} +
• 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 . -path '*/.github/workflows/*' -maxdepth 3 -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

Run the detection script to scan the project for Playwright / axe-core signals (package.json deps + config globs), the e2e dir / __snapshots__ / e2e workflow, and the playwright MCP-server entry:

bash "${CLAUDE_SKILL_DIR}/scripts/configure-ux-testing.sh" --home-dir "$HOME" --project-dir "$(pwd)"

Parse STATUS= and the ISSUES: block from the output. The KEY=VALUE lines report PLAYWRIGHT_CONFIG, PLAYWRIGHT_DEP, AXE_CORE_DEP, E2E_DIR, VISUAL_SNAPSHOTS, E2E_WORKFLOW, PLAYWRIGHT_MCP, and the rollup PLAYWRIGHT_DETECTED / UX_SIGNALS_PRESENT.

Step 3: 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 4: 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 5: 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 6: 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 7: 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 8: 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 9: 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 10: 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 11: 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 12: 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

Flags

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

configure-ux-testing Reference

Compliance Report Format

UX Testing Compliance Report
=============================
Project: [name]
Framework: Playwright

Playwright Core:
  @playwright/test        package.json               [INSTALLED | MISSING]
  playwright.config.ts    configuration              [EXISTS | MISSING]
  Desktop browsers        chromium, firefox, webkit  [ALL | PARTIAL]
  Mobile viewports        iPhone, Pixel              [CONFIGURED | OPTIONAL]
  WebServer config        auto-start dev server      [CONFIGURED | MISSING]
  Trace on failure        debugging support          [ENABLED | DISABLED]

Accessibility Testing:
  @axe-core/playwright    package.json               [INSTALLED | MISSING]
  a11y test files         tests/a11y/                [FOUND | NONE]
  WCAG level              AA (recommended)           [CONFIGURED | NOT SET]
  Violations threshold    0 (strict)                 [STRICT | LENIENT]

Visual Regression:
  Screenshot tests        toHaveScreenshot()         [FOUND | OPTIONAL]
  Snapshot directory      __snapshots__              [CONFIGURED | N/A]
  CI handling             GitHub Actions artifact    [CONFIGURED | MISSING]

Browser Automation:
  Playwright CLI          global / package.json      [INSTALLED | OPTIONAL]
  Playwright MCP          .mcp.json                  [CONFIGURED | OPTIONAL]

Overall: [X issues found]

Recommendations:
  - Install @axe-core/playwright for accessibility testing
  - Add mobile viewport configurations
  - Configure visual regression workflow

Playwright Configuration Template (playwright.config.ts)

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [
    ['html', { open: 'never' }],
    ['json', { outputFile: 'test-results/results.json' }],
    ['junit', { outputFile: 'test-results/junit.xml' }],
  ],
  timeout: 30000,
  expect: {
    timeout: 5000,
    toHaveScreenshot: {
      maxDiffPixels: 100,
      threshold: 0.2,
    },
  },
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    actionTimeout: 10000,
    navigationTimeout: 30000,
  },
  projects: [
    // Desktop browsers
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    // Mobile viewports
    {
      name: 'mobile-chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'mobile-safari',
      use: { ...devices['iPhone 13'] },
    },
    // Accessibility tests (single browser)
    {
      name: 'a11y',
      testMatch: /.*\.a11y\.spec\.ts/,
      use: { ...devices['Desktop Chrome'] },
    },
  ],
  webServer: {
    command: 'bun run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
    timeout: 120000,
  },
});

Accessibility Test Helper (tests/e2e/helpers/a11y.ts)

import { Page, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

export interface A11yOptions {
  /** WCAG conformance level: 'wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa' */
  level?: 'wcag2a' | 'wcag2aa' | 'wcag21aa' | 'wcag22aa';
  /** Specific rules to include */
  includeRules?: string[];
  /** Specific rules to exclude */
  excludeRules?: string[];
  /** Selectors to exclude from analysis */
  excludeSelectors?: string[];
}

/**
 * Run accessibility scan on page and assert no violations
 */
export async function expectNoA11yViolations(
  page: Page,
  options: A11yOptions = {}
): Promise<void> {
  const {
    level = 'wcag21aa',
    includeRules = [],
    excludeRules = [],
    excludeSelectors = [],
  } = options;

  let builder = new AxeBuilder({ page })
    .withTags([level, 'best-practice']);

  if (includeRules.length > 0) {
    builder = builder.include(includeRules);
  }

  if (excludeRules.length > 0) {
    builder = builder.disableRules(excludeRules);
  }

  if (excludeSelectors.length > 0) {
    for (const selector of excludeSelectors) {
      builder = builder.exclude(selector);
    }
  }

  const results = await builder.analyze();

  // Format violations for readable output
  const violationSummary = results.violations.map((v) => ({
    rule: v.id,
    impact: v.impact,
    description: v.description,
    nodes: v.nodes.length,
    elements: v.nodes.map((n) => n.html).slice(0, 3),
  }));

  expect(
    results.violations,
    `Found ${results.violations.length} accessibility violation(s):\n${JSON.stringify(violationSummary, null, 2)}`
  ).toHaveLength(0);
}

/**
 * Run accessibility scan and return detailed report
 */
export async function getA11yReport(
  page: Page,
  options: A11yOptions = {}
): Promise<{
  violations: number;
  passes: number;
  incomplete: number;
  details: unknown;
}> {
  const { level = 'wcag21aa' } = options;

  const results = await new AxeBuilder({ page })
    .withTags([level, 'best-practice'])
    .analyze();

  return {
    violations: results.violations.length,
    passes: results.passes.length,
    incomplete: results.incomplete.length,
    details: results,
  };
}

Example Accessibility Test (tests/e2e/homepage.a11y.spec.ts)

import { test, expect } from '@playwright/test';
import { expectNoA11yViolations, getA11yReport } from './helpers/a11y';

test.describe('Homepage Accessibility', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/');
  });

  test('should have no WCAG 2.1 AA violations', async ({ page }) => {
    await expectNoA11yViolations(page, {
      level: 'wcag21aa',
    });
  });

  test('should have no violations after interaction', async ({ page }) => {
    // Interact with page elements
    await page.getByRole('button', { name: /menu/i }).click();

    // Check accessibility after state change
    await expectNoA11yViolations(page);
  });

  test('should generate full accessibility report', async ({ page }) => {
    const report = await getA11yReport(page);

    console.log(`Accessibility Report:
      - Violations: ${report.violations}
      - Passes: ${report.passes}
      - Incomplete: ${report.incomplete}
    `);

    expect(report.violations).toBe(0);
  });
});

test.describe('Form Accessibility', () => {
  test('login form should be accessible', async ({ page }) => {
    await page.goto('/login');

    // Check form has proper labels
    await expect(page.getByLabel('Email')).toBeVisible();
    await expect(page.getByLabel('Password')).toBeVisible();

    // Check submit button is accessible
    await expect(page.getByRole('button', { name: /sign in/i })).toBeEnabled();

    // Run full a11y scan
    await expectNoA11yViolations(page);
  });
});

Example Visual Regression Test (tests/e2e/visual.spec.ts)

import { test, expect } from '@playwright/test';

test.describe('Visual Regression', () => {
  test('homepage matches snapshot', async ({ page }) => {
    await page.goto('/');

    // Wait for dynamic content to load
    await page.waitForLoadState('networkidle');

    // Full page screenshot
    await expect(page).toHaveScreenshot('homepage.png', {
      fullPage: true,
    });
  });

  test('header matches snapshot', async ({ page }) => {
    await page.goto('/');

    // Component screenshot
    const header = page.locator('header');
    await expect(header).toHaveScreenshot('header.png');
  });

  test('responsive layouts match snapshots', async ({ page }) => {
    await page.goto('/');

    // Desktop
    await page.setViewportSize({ width: 1920, height: 1080 });
    await expect(page).toHaveScreenshot('homepage-desktop.png');

    // Tablet
    await page.setViewportSize({ width: 768, height: 1024 });
    await expect(page).toHaveScreenshot('homepage-tablet.png');

    // Mobile
    await page.setViewportSize({ width: 375, height: 667 });
    await expect(page).toHaveScreenshot('homepage-mobile.png');
  });

  test('dark mode matches snapshot', async ({ page }) => {
    await page.goto('/');

    // Enable dark mode (adjust selector for your app)
    await page.emulateMedia({ colorScheme: 'dark' });

    await expect(page).toHaveScreenshot('homepage-dark.png', {
      fullPage: true,
    });
  });
});

CI/CD Workflow Template (.github/workflows/e2e.yml)

name: E2E Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  e2e:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Install Playwright Browsers
        run: bunx playwright install --with-deps

      - name: Run E2E tests
        run: bunx playwright test

      - name: Upload test results
        uses: actions/upload-artifact@v7
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

      - name: Upload screenshots
        uses: actions/upload-artifact@v7
        if: failure()
        with:
          name: test-screenshots
          path: test-results/
          retention-days: 7

  a11y:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Install Playwright Browsers
        run: bunx playwright install chromium --with-deps

      - name: Run accessibility tests
        run: bunx playwright test --project=a11y

      - name: Upload a11y report
        uses: actions/upload-artifact@v7
        if: always()
        with:
          name: a11y-report
          path: playwright-report/
          retention-days: 30

Results Report Format

UX Testing Configuration Complete
===================================

Framework: Playwright
Accessibility: axe-core (WCAG 2.1 AA)
Visual: Screenshot comparisons

Configuration Applied:
  @playwright/test installed
  @axe-core/playwright installed
  playwright.config.ts created
  Desktop and mobile projects configured
  WebServer auto-start configured

Accessibility Testing:
  a11y helper functions created
  Example accessibility tests added
  WCAG 2.1 AA level configured

Visual Regression:
  Screenshot test examples created
  Responsive breakpoint tests included
  Dark mode test included

Scripts Added:
  bun run test:e2e (run all E2E tests)
  bun run test:a11y (accessibility only)
  bun run test:visual (visual regression)
  bun run test:visual:update (update snapshots)

CI/CD:
  GitHub Actions workflow created
  Parallel E2E and a11y jobs
  Artifact upload for reports

Next Steps:
  1. Start dev server:
     bun run dev

  2. Run E2E tests:
     bun run test:e2e

  3. Run accessibility scan:
     bun run test:a11y

  4. Update visual snapshots:
     bun run test:visual:update

  5. Open interactive UI:
     bun run test:e2e:ui

Documentation:
  - Playwright: https://playwright.dev
  - axe-core: https://www.deque.com/axe
  - Skill: playwright-testing, accessibility-implementation