browser-ui-testing

Browser UI Testing

When to use which tool

Context	Tool
Live Claude Code session, exploratory, no commit needed	Chrome DevTools MCP
Generated test artifact that runs in CI	Playwright
Existing app-level E2E flows (login, campaign creation, etc.)	Cypress 14 — do not port

Chrome DevTools MCP is already installed and requires zero project dependencies. Playwright is added to the project when you first scaffold a component E2E test.

Chrome DevTools MCP recipes

Light + dark screenshots

mcp__chrome-devtools__new_page
mcp__chrome-devtools__navigate_page (url: http://localhost:4200/your-route)
mcp__chrome-devtools__take_screenshot                         ← light mode
mcp__chrome-devtools__evaluate_script (script: "document.body.classList.add('dark-theme')")
mcp__chrome-devtools__take_screenshot                         ← dark mode

Save screenshots to .ui-design/reviews/{review_id}/ as light.png and dark.png.

Run Lighthouse

mcp__chrome-devtools__lighthouse_audit (url: http://localhost:4200/your-route)

Interpret: performance, accessibility, best-practices, seo scores. Accessibility score below 100 is a blocker. Performance below 90 warrants investigation. Save the JSON result to .ui-design/reviews/{review_id}/lighthouse.json.

Run axe-core in-page

// Via evaluate_script
const script = `
  const script = document.createElement('script');
  script.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.8.3/axe.min.js';
  document.head.appendChild(script);
  await new Promise(r => script.onload = r);
  return await axe.run();
`;
mcp__chrome-devtools__evaluate_script (script)

Parse violations from the result. Classify by impact (critical > serious > moderate > minor). Mark as "runtime" vs "static" in your audit report.

Performance trace

mcp__chrome-devtools__performance_start_trace
// ... user interaction sequence ...
mcp__chrome-devtools__performance_stop_trace
mcp__chrome-devtools__performance_analyze_insight

Playwright setup

Install (if not yet in the project)

pnpm add -D @playwright/test @axe-core/playwright playwright-lighthouse
npx playwright install --with-deps

Print this command to the user rather than installing silently if Playwright isn't detected.

playwright.config.ts baseline for Fastlane

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

export default defineConfig({
  testDir: './apps/web/e2e/components',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 2 : undefined,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:4200',
    screenshot: 'only-on-failure',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],
});

Place at apps/web/playwright.config.ts. Run via npx playwright test — separate from pnpm test (Jest/Cypress) so CI stages don't conflict.

@axe-core/playwright

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

test('my-component is WCAG AA compliant', async ({ page }) => {
  await page.goto('/your-component-route');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

Tag these tests with @a11y for selective CI execution: npx playwright test --grep @a11y.

playwright-lighthouse

import { playAudit } from 'playwright-lighthouse';
import { chromium } from 'playwright';

test('performance and a11y gate', async () => {
  const browser = await chromium.launch({ args: ['--remote-debugging-port=9222'] });
  const page = await browser.newPage();
  await page.goto('http://localhost:4200/your-route');

  await playAudit({
    page,
    port: 9222,
    thresholds: {
      performance: 90,
      accessibility: 100,
      'best-practices': 90,
      seo: 80,
    },
  });

  await browser.close();
});

Run selectively (not on every commit): npx playwright test --grep @lighthouse.

Visual regression with Playwright

test('my-component snapshot @visual', async ({ page }) => {
  await page.goto('/your-component-route');

  // Disable animations for stable snapshots
  await page.addStyleTag({ content: '*, *::before, *::after { animation-duration: 0s !important; transition-duration: 0s !important; }' });

  // Light mode snapshot
  await expect(page).toHaveScreenshot('my-component-light.png', {
    maxDiffPixels: 100,
  });

  // Dark mode snapshot
  await page.evaluate(() => document.body.classList.add('dark-theme'));
  await expect(page).toHaveScreenshot('my-component-dark.png', {
    maxDiffPixels: 100,
  });
});

Run: npx playwright test --grep @visual. Update baselines: npx playwright test --update-snapshots.

Mask dynamic regions (dates, usernames): page.locator('.dynamic-timestamp').

Shadow DOM traversal

Angular Material components use shadow DOM for some internals. Use Playwright's >> piercing selector:

const internalInput = page.locator('mat-form-field >> input');

Encapsulate traversal in helper functions; never duplicate selector strings across tests.

Pangea-specific testing

Token resolution assertion

// Verify a token resolves to a value (not empty string)
const tokenValue = await page.evaluate(() =>
  getComputedStyle(document.documentElement)
    .getPropertyValue('--color-primary').trim()
);
expect(tokenValue).toBeTruthy();

Dark mode toggle in tests

await page.evaluate(() => document.body.classList.add('dark-theme'));
// Assert something changed
const bgBefore = /* light bg */;
const bgAfter = await page.evaluate(() =>
  getComputedStyle(document.body).backgroundColor
);
expect(bgAfter).not.toEqual(bgBefore);

Status icon class assertions

const icon = page.locator('mat-icon.status-success');
await expect(icon).toBeVisible();
await expect(icon).toHaveText('check_circle');

CI gate ordering

1. Jest unit tests (fastest) — fail fast
2. Playwright component E2E (with @axe-core/playwright)
3. Playwright a11y-tagged tests (--grep @a11y)
4. Playwright Lighthouse-tagged tests (--grep @lighthouse) — run selectively, not on every commit
5. Cypress 14 app-level E2E — existing suites, unchanged

What NOT to do

• Don't add Playwright as a substitute for Cypress 14 app-level E2E — Playwright handles new component-level tests; Cypress keeps existing app flows.
• Don't run Lighthouse on every CI commit — gate it behind a @lighthouse tag and run it on schedule or pre-merge for important routes.
• Don't commit Chrome DevTools MCP artifacts (screenshots, Lighthouse JSON from exploratory sessions) — they live under .ui-design/ which should be in .gitignore.
• Don't test implementation internals (signal values, CSS class names as state proxies) — test observable behavior via role queries and visual snapshots.