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
- 参考文档agents/openai.yaml537 B
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
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.
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".
wireframe
Generate JSON wireframe with HTML preview
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.
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.
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.