Pa11y Accessibility CI
Teach agents to automate accessibility testing in CI with pa11y and pa11y-ci, including thresholds, sitemap crawling, GitHub Actions gating, and WCAG rule tuning.
- License 许可
- MIT
- 最近更新
- 2026-11-04
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- Pa11y Accessibility CI
- tags
- [ "pa11y", "accessibility", "ci", "wcag", "regression", "github-actions" ]
- agents
- [ "claude-code", "cursor", "github-copilot", "windsurf", "codex", "aider", "continue", "cline", "zed", "bolt", "gemini-cli", "amp" ]
- author
- thetestingacademy
- domains
- [ "web" ]
- license
- MIT
- version
- 1.0.0
- languages
- [ "javascript", "typescript" ]
- frameworks
- []
- description
- Teach agents to automate accessibility testing in CI with pa11y and pa11y-ci, including thresholds, sitemap crawling, GitHub Actions gating, and WCAG rule tuning.
- testingTypes
- [ "accessibility", "regression" ]
03 SKILL.md 正文
Pa11y Accessibility CI Skill
You are an accessibility automation engineer who adds reliable pa11y and pa11y-ci checks to web delivery pipelines without treating scanners as a replacement for manual WCAG review.
Core Principles
- Gate on real user impact: Fail builds on violations that block keyboard, screen reader, contrast, form, landmark, or document structure usage.
- Keep the scan target stable: Run pa11y against a deterministic preview environment, not a developer laptop with unknown data.
- Start narrow, then expand: Begin with smoke URLs, add sitemap discovery, then add authenticated flows when the signal is clean.
- Use thresholds intentionally: A threshold is temporary debt tracking, not a permanent permission to ship inaccessible pages.
- Pin WCAG standard explicitly: Use
WCAG2AAor stricter rules in config so upgrades do not silently change expectations. - Record evidence: Save pa11y output as CI artifacts so failures can be triaged without rerunning the job.
- Separate scanner limits from product bugs: Document rules that require manual verification and never claim total accessibility compliance from pa11y alone.
- Review ignored selectors: Every ignore must include a reason, owner, and expiry date in a nearby comment or issue.
Setup
Install pa11y-ci into the web project.
npm install --save-dev pa11y pa11y-ci start-server-and-test
npm pkg set scripts.a11y='pa11y-ci --config .pa11yci.cjs'
npm pkg set scripts.preview='vite --host 127.0.0.1'
npm pkg set scripts.a11y:local='start-server-and-test preview http://127.0.0.1:5173 a11y'
Use a dedicated config file instead of long CLI flags.
// .pa11yci.cjs
const baseUrl = process.env.PREVIEW_URL || 'http://127.0.0.1:5173';
module.exports = {
defaults: {
standard: 'WCAG2AA',
timeout: 30000,
wait: 500,
chromeLaunchConfig: {
args: ['--no-sandbox', '--disable-dev-shm-usage'],
},
hideElements: '.third-party-chat, .cookie-banner-test-only',
},
urls: [
`${baseUrl}/`,
`${baseUrl}/pricing`,
`${baseUrl}/login`,
`${baseUrl}/dashboard`,
],
threshold: 0,
reporters: ['cli', 'json'],
};
Recommended Project Structure
Create a small accessibility automation area that the whole team can understand.
.
.github/
workflows/
accessibility.yml
accessibility/
urls.json
crawl-sitemap.mjs
known-issues.md
.pa11yci.cjs
package.json
Sitemap Crawling Workflow
Use sitemap crawling when the product has many public pages.
- Fetch
sitemap.xmlfrom the preview deployment. - Keep only HTML routes that are safe for unauthenticated scanning.
- Exclude logout, destructive, or parameterized pages.
- Write a URL list that pa11y-ci can consume.
- Keep a hard maximum for CI time.
// accessibility/crawl-sitemap.mjs
import { writeFile } from 'node:fs/promises';
const origin = process.env.PREVIEW_URL || 'http://127.0.0.1:5173';
const sitemapUrl = `${origin}/sitemap.xml`;
const response = await fetch(sitemapUrl);
if (!response.ok) {
throw new Error(`Could not fetch sitemap: ${response.status}`);
}
const xml = await response.text();
const urls = [...xml.matchAll(/<loc>(.*?)<\/loc>/g)]
.map((match) => match[1])
.filter((url) => url.startsWith(origin))
.filter((url) => !url.includes('/logout'))
.slice(0, Number(process.env.PA11Y_MAX_URLS || 50));
await writeFile('accessibility/urls.json', `${JSON.stringify(urls, null, 2)}\n`);
console.log(`Wrote ${urls.length} URLs for pa11y-ci`);
Point the config at the generated list when required.
// .pa11yci.cjs
const urls = require('./accessibility/urls.json');
module.exports = {
defaults: {
standard: 'WCAG2AA',
timeout: 30000,
},
urls,
threshold: Number(process.env.PA11Y_THRESHOLD || 0),
};
GitHub Actions Gate
Run the accessibility gate after the app builds and the preview server starts.
name: accessibility
on:
pull_request:
push:
branches: [main]
jobs:
pa11y:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm run build
- run: npm run a11y:local
- uses: actions/upload-artifact@v4
if: always()
with:
name: pa11y-results
path: pa11y-ci-results.json
Rule Tuning
Use ignore only when there is a documented reason.
module.exports = {
defaults: {
standard: 'WCAG2AA',
ignore: [
// Temporary until design system token QA-1284 is fixed.
'color-contrast',
],
},
urls: ['http://127.0.0.1:5173/'],
threshold: 0,
};
CI Failure Triage
When pa11y fails, inspect the page, selector, context, and rule.
- Reproduce locally with
npm run a11y:local. - Open the failing route in a browser.
- Inspect the reported selector.
- Confirm whether the violation is visible to users.
- Fix markup first, then test config.
- Add a regression URL for the page if it was not already covered.
Reference Table
| Need | Pa11y Choice | Agent Action |
|---|---|---|
| Small public site | Static urls list |
Keep direct route coverage explicit |
| Large marketing site | Sitemap crawler | Cap URL count and exclude unsafe paths |
| Pull request gate | threshold: 0 |
Fail new violations immediately |
| Legacy app | Temporary threshold | Track debt and lower threshold over time |
| Third-party widget noise | hideElements |
Hide only non-product widgets |
| Rule exception | ignore |
Require issue link and expiry |
Common Mistakes
- Treating pa11y as proof of WCAG compliance.
- Scanning only the home page.
- Leaving
thresholdhigh forever. - Ignoring color contrast globally for one design bug.
- Running against production when the pull request preview exists.
- Forgetting authenticated routes that customers actually use.
- Hiding product UI with
hideElements. - Failing to upload JSON reports from CI.
- Mixing flaky server startup with accessibility failures.
- Not pinning Node and browser versions in CI.
Checklist
- [ ] The config uses inline URL lists or a generated sitemap list.
- [ ] The standard is explicitly set to
WCAG2AAor stricter. - [ ] CI fails on new violations with a clear threshold.
- [ ] Reports are uploaded as artifacts.
- [ ] Ignored rules have owners and expiry dates.
- [ ] Destructive routes are excluded from crawls.
- [ ] Authenticated routes have a separate plan.
- [ ] The team knows scanner results do not replace manual audits.
- [ ] Local reproduction commands are documented.
- [ ] The gate runs before merge.
04 同仓库更多 Skills
nemoclaw-user-reference
Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. Use when looking up architecture, agent integration, plugin structure, or blueprint design. Trigger keywords - nemoclaw architecture, nemoclaw agent architecture, nemoclaw plugin blueprint structure, nemoclaw vs openshell, which cli, nemoclaw cli, openshell cli, sandbox commands, nemoclaw cli commands, nemoclaw command reference, nemoclaw network policy, sandbox egress control operator approval, nemoclaw troubleshooting, nemoclaw debug sandbox issues.
nemoclaw-user-overview
Explains how OpenClaw, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond the community sandbox, and when to prefer NemoClaw versus integrating OpenShell and OpenClaw directly. Use when users ask about the relationship between OpenClaw, OpenShell, and NemoClaw, or when to use NemoClaw versus OpenShell. Trigger keywords - nemoclaw ecosystem, openclaw openshell, nemoclaw vs openshell, sandboxed openclaw, how nemoclaw works, nemoclaw sandbox lifecycle blueprint, nemoclaw overview, openclaw always-on assistants, nvidia openshell, nvidia nemotron, nemoclaw release notes, nemoclaw changelog.
nemoclaw-user-monitor-sandbox
Inspects sandbox health, traces agent behavior, and diagnoses problems. Use when monitoring a running sandbox, debugging agent issues, or checking sandbox logs. Trigger keywords - monitor nemoclaw sandbox, debug nemoclaw agent issues.
nemoclaw-user-manage-sandboxes
Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence.
nemoclaw-user-manage-policy
Adds, removes, or modifies allowed endpoints in the sandbox policy. Use when customizing network policy, changing egress rules, or configuring sandbox endpoint access. Trigger keywords - customize nemoclaw network policy, sandbox egress policy configuration, nemoclaw integration policy examples, post-install policy setup, openshell approval workflow, policy preset, nemoclaw approve network requests, sandbox egress approval tui.
nemoclaw-user-get-started
Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time. Trigger keywords - nemoclaw quickstart, install nemoclaw openclaw sandbox, nemohermes quickstart, hermes agent nemoclaw, run hermes openshell sandbox, nemoclaw prerequisites, nemoclaw supported platforms, nemoclaw hardware software, nemoclaw windows wsl2 setup, nemoclaw install windows docker desktop.