How to Run axe-core Accessibility Tests in GitHub Actions

@axe-core/cli loads a URL in headless Chrome, runs the axe ruleset, and exits non-zero when it finds violations.

Build and serve the site, then point @axe-core/cli at the local URL. A non-zero exit on violations fails the job automatically.

Steps

• Install @axe-core/cli (it bundles a headless Chrome driver).
• Start the app and wait for the port to be reachable.
• Run axe <url> so violations exit non-zero and fail the job.

Workflow

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - run: npx serve -l 3000 dist & npx wait-on http://localhost:3000
      - run: npx @axe-core/cli http://localhost:3000 --exit

Gotchas

• The --exit flag is what makes axe return a non-zero code; without it the job stays green.
• Automated rules catch roughly a third of WCAG issues; pair them with manual review.

Related guides