How to Run Accessibility Tests in GitHub Actions

Accessibility regressions are invisible until a user hits them; axe-core surfaces a large class of them automatically in CI.

Serve the app, then run @axe-core/cli (or axe via Playwright) against the URLs you care about so violations exit non-zero.

Steps

• Build and serve the site (or start the dev server).
• Run @axe-core/cli against the target URLs.
• Fail the job on any reported violation.
• Optionally scope rules to a WCAG level with tags.

Workflow

name: A11y
on: [pull_request]
jobs:
  axe:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci && npm run build
      - run: npx serve -l 8080 dist &
      - run: npx wait-on http://localhost:8080
      - run: npx @axe-core/cli http://localhost:8080 --exit

Notes

• The --exit flag makes axe return non-zero when violations are found.
• Automated checks catch only part of WCAG; pair them with manual review.

Related guides