Skip to main content
Skip to docs content

CI/CD Integration

Run Speakable in your build pipeline to catch accessibility regressions on every pull request. Works with any framework that produces HTML output.

Installation

Install Speakable as a dev dependency in your project:

Terminal
npm install --save-dev @reticular/speakable

GitHub Actions

Add this workflow to run accessibility checks on every push. The audit step catches issues, and the diff step detects regressions against a baseline. For a broader view of where CI fits in your testing strategy, see the dedicated guide.

.github/workflows/a11y.yml
name: Accessibility Check

on: [push, pull_request]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 18

      - run: npm ci

      - name: Run accessibility audit
        run: npx @reticular/speakable ./dist/index.html -f audit

      - name: Check for regressions
        run: npx @reticular/speakable ./dist/index.html --diff ./baseline.html -f text

GitLab CI

.gitlab-ci.yml
accessibility:
  stage: test
  image: node:18
  script:
    - npm ci
    - npx @reticular/speakable ./dist/index.html -f audit
    - npx @reticular/speakable ./dist/index.html --diff ./baseline.html -f text

Exit Codes

Use exit codes in CI to fail builds on regressions or errors.

CodeMeaning
0Analysis completed successfully, no regressions
1User error: invalid arguments or options
2Content error: accessibility issues found, or diff detected changes
3System error: file not found, I/O failure

JSON Output

Use -f json to get machine-readable output for programmatic comparison:

JSON Output
{
  "version": { "major": 1, "minor": 0 },
  "root": {
    "role": "button",
    "name": "Submit",
    "state": {},
    "focus": { "focusable": true },
    "children": []
  },
  "metadata": {
    "extractedAt": "2026-04-02T12:00:00Z"
  }
}

Baseline Workflow

Save a baseline of your current accessibility state, then compare against it after making changes. This is the recommended workflow for regression detection.

Step 1 - Save baseline
# Save the current accessibility model as a baseline
speakable page.html -f json -o baseline.json
Step 2 - Make changes and compare
# After making HTML changes, diff against the baseline
speakable page.html --diff baseline.html

# Or get text-formatted diff output
speakable page.html --diff baseline.html -f text
Step 3 - Automate in CI
# In your CI pipeline, fail on regressions
npx @reticular/speakable ./dist/index.html --diff ./baseline.html || echo "Accessibility regression detected"

Commit baseline.html to your repository. When the diff detects changes, the CLI exits with code 2, which fails the CI step. Update the baseline intentionally when accessibility changes are expected. See the testing ecosystem page to learn how Speakable CI checks complement runtime tools like Guidepup. For CLI options and programmatic usage, check the usage guide.

Related Pages

Frameworks

Integrate Speakable into React, Angular, Svelte, or Web Component workflows.

Testing Ecosystem

How Speakable fits alongside Guidepup, axe-core, and manual testing.

Testing Strategy

Plan a layered accessibility testing approach that balances speed and confidence.

Usage Guide

CLI options, programmatic API, and output formats for Speakable.