AGENT SKILL

kb-playwright-testing

Reference data, not a reviewer. Browser accessibility testing using Playwright and @axe-core/playwright. Keyboard scans, contrast verification, and accessibility tree snapshots.

License 许可
MIT
最近更新
2026-11-06
Stars
★ 0
Forks
0

01 前言 Front Matter

name
kb-playwright-testing
license
MIT
metadata
{ "tier": "reference", "title": "Playwright Testing", "domain": "cross-cutting", "effort": "low", "output": "none" }
description
Reference data, not a reviewer. Browser accessibility testing using Playwright and @axe-core/playwright. Keyboard scans, contrast verification, and accessibility tree snapshots.
user-invocable
false
disable-model-invocation
true

02 资源文件 1

03 SKILL.md 正文

Playwright Accessibility Testing

Reusable knowledge module for browser-based accessibility testing using Playwright and @axe-core/playwright.

MCP Tools Available

Each tool, with its purpose and requires @axe-core or playwright.

Tool Purpose Requires @axe-core/playwright
run_playwright_keyboard_scan Tab-order traversal, keyboard trap detection No
run_playwright_state_scan Click triggers, scan revealed content with axe-core Yes
run_playwright_viewport_scan Multi-viewport axe-core + touch target measurement Yes
run_playwright_contrast_scan Computed-style contrast ratio after CSS cascade No
run_playwright_a11y_tree Browser accessibility tree snapshot No

@axe-core/playwright Patterns

Full Page Scan

import AxeBuilder from '@axe-core/playwright';

const results = await new AxeBuilder({ page })
  .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
  .analyze();

Scoped Element Scan

const results = await new AxeBuilder({ page })
  .include('.modal-content')
  .withTags(['wcag2a', 'wcag2aa'])
  .analyze();

Single Rule Verification

const results = await new AxeBuilder({ page })
  .include('#hero-image')
  .withRules(['image-alt'])
  .analyze();
expect(results.violations).toEqual([]);

Scan After Interaction

await page.click('[aria-expanded="false"]');
await page.waitForSelector('.accordion-content', { state: 'visible' });
const results = await new AxeBuilder({ page })
  .include('.accordion-content')
  .analyze();

Keyboard Traversal Patterns

Record Tab Sequence

const tabStops = [];
for (let i = 0; i < maxTabs; i++) {
  await page.keyboard.press('Tab');
  const info = await page.evaluate(() => {
    const el = document.activeElement;
    return {
      tagName: el?.tagName,
      role: el?.getAttribute('role'),
      name: el?.getAttribute('aria-label') || el?.textContent?.trim().slice(0, 50),
      id: el?.id,
      tabIndex: el?.tabIndex
    };
  });
  tabStops.push(info);
}

Detect Keyboard Traps

A keyboard trap is detected when the same element receives focus after consecutive Tab presses:

let trapCount = 0;
let lastSelector = '';
for (const stop of tabStops) {
  const currentSelector = `${stop.tagName}#${stop.id}`;
  if (currentSelector === lastSelector) {
    trapCount++;
    if (trapCount >= 3) { /* TRAP DETECTED */ }
  } else {
    trapCount = 0;
  }
  lastSelector = currentSelector;
}

Focus Management After Modal Open

await page.click('[data-modal-trigger]');
await page.waitForSelector('[role="dialog"]', { state: 'visible' });
const focusedRole = await page.evaluate(() =>
  document.activeElement?.closest('[role="dialog"]') ? 'inside-dialog' : 'outside-dialog'
);
// focusedRole should be 'inside-dialog'

Focus Management Test Templates

Modal Focus Trap Test

test('modal traps focus correctly', async ({ page }) => {
  await page.goto(url);
  await page.click('[data-open-modal]');
  await page.waitForSelector('[role="dialog"]', { state: 'visible' });

  // Focus should be inside the dialog
  const inDialog = await page.evaluate(() =>
    document.activeElement?.closest('[role="dialog"]') !== null
  );
  expect(inDialog).toBe(true);

  // Tab through dialog — should not escape
  for (let i = 0; i < 20; i++) {
    await page.keyboard.press('Tab');
    const stillInDialog = await page.evaluate(() =>
      document.activeElement?.closest('[role="dialog"]') !== null
    );
    expect(stillInDialog).toBe(true);
  }

  // Escape should close and return focus to trigger
  await page.keyboard.press('Escape');
  const focusedId = await page.evaluate(() => document.activeElement?.id);
  expect(focusedId).toBe('modal-trigger-id');
});

Skip Link Test

test('skip link moves focus to main content', async ({ page }) => {
  await page.goto(url);
  await page.keyboard.press('Tab'); // Focus skip link
  await page.keyboard.press('Enter'); // Activate it
  const focusedId = await page.evaluate(() => document.activeElement?.id);
  expect(focusedId).toBe('main-content');
});

CI Integration

GitHub Actions with Playwright

name: Accessibility Tests
on: [push, pull_request]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - name: Start dev server
        run: npm run dev &
        env:
          CI: true
      - name: Wait for server
        run: npx wait-on http://localhost:3000 --timeout 30000
      - name: Run accessibility tests
        run: npx playwright test tests/a11y/
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: a11y-test-results
          path: test-results/

Playwright Config for Accessibility Tests

// playwright.config.js (a11y section)
export default {
  testDir: './tests/a11y',
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
    // Use Chromium only — @axe-core/playwright is Chromium-validated
    browserName: 'chromium',
  },
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
};

Graceful Degradation

Detection Pattern

let _playwrightAvailable = null;
async function isPlaywrightAvailable() {
  if (_playwrightAvailable !== null) return _playwrightAvailable;
  try {
    await import('playwright');
    _playwrightAvailable = true;
  } catch {
    _playwrightAvailable = false;
  }
  return _playwrightAvailable;
}

Degradation Matrix

Each playwright, with its @axe-core or playwright and available scans.

Playwright @axe-core/playwright Available Scans
Yes Yes All 5 tools (keyboard, state, viewport, contrast, tree)
Yes No 3 tools (keyboard, contrast, tree)
No — None — fall back to code review + axe-core CLI

User-Facing Messages

When unavailable:

Playwright not installed. Behavioral testing (keyboard traversal, dynamic states,
responsive viewport, rendered contrast) is unavailable.

Install: npm install -D playwright @axe-core/playwright && npx playwright install chromium

When partially available:

@axe-core/playwright not installed. State scanning and viewport scanning are
unavailable. Keyboard, contrast, and accessibility tree scans will proceed.

Install: npm install -D @axe-core/playwright

WCAG Coverage Map

Each WCAG SC, with its description and playwright tool.

WCAG SC Description Playwright Tool
1.3.1 Info and Relationships a11y tree, state scan
1.4.3 Contrast (Minimum) contrast scan
1.4.6 Contrast (Enhanced) contrast scan
1.4.10 Reflow viewport scan
2.1.1 Keyboard keyboard scan
2.1.2 No Keyboard Trap keyboard scan
2.4.3 Focus Order keyboard scan
2.4.7 Focus Visible keyboard scan
2.5.5 Target Size (Enhanced) viewport scan
2.5.8 Target Size (Minimum) viewport scan
4.1.2 Name, Role, Value a11y tree, state scan

04 同仓库更多 Skills

mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

frontend-slides

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

design-dna

Extract, define, and apply design DNA across three dimensions: design system (tokens), design style (qualitative feel), and visual effects (Canvas, WebGL, 3D, particles, shaders, scroll effects, etc.). Use this skill when: (1) a user wants to see the full 3-dimension design structure/schema, (2) a user provides images, screenshots, or URLs of reference designs and wants them analyzed into a structured JSON profile covering all three dimensions, (3) a user has a Design DNA JSON and content and wants a design generated from it, or (4) any combination of these phases. Triggers on "design DNA", "extract design style", "analyze design", "design tokens from reference", "generate design from JSON", "design system from screenshot", "design profile", "style guide JSON", "visual effects analysis", "design with effects", "3d design analysis".

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

wireframe

Generate JSON wireframe with HTML preview

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

social-publishing

Schedule and publish social media posts across 13 platforms (X, LinkedIn, Instagram, Facebook Pages, TikTok, Discord, Telegram, YouTube, Reddit, WordPress, Pinterest) via the SocialClaw API. Use when the user wants to publish, schedule, or manage social media content programmatically. Requires SOCIALCLAW_API_KEY.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

hermes-tweet

Install and operate Hermes Tweet, a Hermes Agent plugin for X/Twitter research, timeline reading, tweet analysis, and approval-gated private or state-changing operations. Use this skill when installing Hermes Tweet, researching X/Twitter accounts, monitoring launch signals, investigating mentions, auditing giveaways, or preparing gated X operations. Use proactively when a Hermes Agent workflow needs current X/Twitter context. Requires XQUIK_API_KEY for read and action tools.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

refactoring-ui

Audit and fix visual hierarchy, spacing, color, and depth in web UIs. Use when the user mentions "my UI looks off" (or amateur/unprofessional), "fix the design", "Tailwind styling", "color palette", "visual hierarchy", "design system", "spacing scale", or "component styling". Also trigger when building consistent design tokens, creating dark mode themes, improving data-visualization clarity, or polishing UI details before launch. Covers grayscale-first workflow, constrained design scales, shadows, and component styling. For typeface selection, see web-typography. For usability audits, see ux-heuristics.

★ 0