Why Accessibility Testing Belongs in CI/CD

Most teams wouldn’t dream of shipping without unit tests. But accessibility? That still gets punted to a manual audit three weeks after launch. A missing alt attribute or a broken focus order that slips into production can take 10x more effort to fix than one caught during a pull request review.

That’s changing. With WCAG enforcement appearing in legal settlements and government procurement requirements, teams can’t afford to treat accessibility as a post-launch audit. Shift-left accessibility testing means catching violations before they reach staging, let alone production.

The cost of late detection

Development phase: A developer fixes a contrast issue in 5 minutes
QA phase: A tester files a bug, a developer context-switches back to fix it — 30 minutes
Post-launch: Legal review, remediation planning, regression testing — days to weeks
Legal action: ADA lawsuits averaged $50,000+ in settlements in 2025

Automated accessibility checks in your pipeline pay for themselves fast.

What AccessHawk Scans For

AccessHawk combines three detection methods to catch accessibility issues that single-tool approaches miss:

1. Browser automation with Playwright

Every scan launches a real Chromium browser that loads your page exactly as a user would see it. AccessHawk captures:

Full-page screenshots for visual analysis (color contrast, text sizing, layout issues)
The accessibility tree — the same structure screen readers use to navigate your page
Raw HTML for structural analysis (heading hierarchy, landmark regions, form labels)

2. Lighthouse accessibility audits

Google Lighthouse runs its accessibility audit suite, checking dozens of WCAG criteria with deterministic rules. This catches clear-cut violations like:

Missing alt text on images
Insufficient color contrast ratios
Missing form labels and ARIA attributes
Incorrect heading hierarchy
Keyboard navigation issues

3. AI-powered contextual analysis

An LLM (Claude, GPT, or Gemini — your choice) analyzes the combined context from the screenshot, accessibility tree, HTML, and Lighthouse results. The AI catches nuanced issues that rule-based tools miss:

Decorative images incorrectly marked as informative
Ambiguous link text (“click here”, “read more”) without surrounding context
Logical reading order issues that pass automated checks but confuse screen readers
ARIA misuse where attributes are present but semantically wrong

Results include WCAG success criteria references, severity levels, and recommendations for fixing each issue.

How the API Integration Works

Up until now, AccessHawk has been a hands-on tool — paste a URL, kick off a scan, review the results in your browser. That works great for one-off audits, but it doesn’t scale when you’re shipping multiple times a day. So we built a public API. You can now trigger scans, retrieve results, and wire everything into your existing automation without ever opening the dashboard.

Here’s the high-level flow:

Authenticate — use an API key generated from your account settings
Submit a scan — send the target URL and configuration options
Get results — poll the status endpoint, or provide a webhook URL upfront and get notified when it’s done
Process the response — parse the structured JSON results for your pipeline logic

The API returns issues categorized by WCAG level (A, AA, AAA), severity, and specific success criteria (e.g., 1.4.3 Contrast). Each issue includes the element location, a description of the impact, and a recommendation for fixing it.

For full endpoint documentation, request/response schemas, and authentication details, see the API Documentation.

Pipeline Integration Patterns

Here’s where accessibility scanning fits in a typical CI/CD workflow:

GitHub Actions

name: Accessibility Check
on:
  pull_request:
    branches: [main]

jobs:
  a11y-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Wait for preview deployment
        # Wait for your preview/staging deployment to be ready
        run: ./scripts/wait-for-deploy.sh

      - name: Run AccessHawk scan
        env:
          ACCESSHAWK_API_KEY: ${{ secrets.ACCESSHAWK_API_KEY }}
        run: |
          # Submit scan against the preview deployment URL
          # Parse results and fail the check if critical issues found
          ./scripts/accesshawk-scan.sh "$PREVIEW_URL"

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: accessibility-report
          path: ./a11y-results.json

GitLab CI

accessibility_scan:
  stage: test
  needs: [deploy_staging]
  script:
    - ./scripts/accesshawk-scan.sh "$STAGING_URL"
  artifacts:
    paths:
      - a11y-results.json
    when: always
  rules:
    - if: $CI_MERGE_REQUEST_ID

General pattern

Regardless of your CI platform, the integration follows the same steps:

Deploy to a preview/staging environment
Run the AccessHawk scan against that URL
Parse the JSON results
Apply your threshold rules (e.g., fail on critical/high issues)
Post a summary as a PR comment or build annotation
Archive the full report as a build artifact

Working with Scan Results

The API returns structured JSON with each issue containing:

WCAG criteria — the specific success criterion violated (e.g., 1.4.3, 2.4.7)
Level — A, AA, or AAA
Severity — critical, high, medium, or low
Location — the element or selector involved
Impact — what’s wrong and how it affects users
Recommendation — how to fix it

This structured format makes it straightforward to write pipeline logic:

// Example: fail the build on critical or high-severity issues
const results = JSON.parse(fs.readFileSync('a11y-results.json', 'utf-8'));
const blocking = results.issues.filter(
  (issue) => issue.severity === 'critical' || issue.severity === 'high'
);

if (blocking.length > 0) {
  console.error(`Found ${blocking.length} blocking accessibility issues:`);
  blocking.forEach((issue) => {
    console.error(`  [${issue.severity}] ${issue.criteria}: ${issue.description}`);
  });
  process.exit(1);
}

For the complete response schema and all available fields, refer to the API Documentation.

Getting Started

One thing to know upfront: API access is a paid feature. It’s available on the Hobby, Pro, and Team plans, each with its own monthly scan quota. You can compare them on the pricing page. The free tier is great for one-off scans in the browser, but it doesn’t include API access.

With that out of the way, here’s how to get going:

Create an account — sign up if you haven’t already
Generate an API key — go to your Settings page and create an API key for CI/CD use
Review the API docs — the API Documentation has everything you need: endpoints, authentication, request/response schemas, and rate limits
Write your integration script — use the patterns above as a starting point
Add your API key as a CI secret — store it as ACCESSHAWK_API_KEY in your CI platform’s secrets

Best Practices

Scan staging before production

Run your first scan against a preview or staging deployment. That way you catch issues before real users are affected and have a chance to fix them before they ship. Scanning production too is still a good idea — it’s the only way to confirm everything looks right in the real environment — but staging should always come first in the pipeline.

Integrate with pull request checks

Make accessibility scans a required check on pull requests. This prevents regressions from being merged and gives developers immediate feedback while the code is fresh in their minds.

Set severity thresholds

Not every accessibility issue needs to block a deployment. A practical approach:

Critical and high issues — block the merge/deploy
Medium issues — warn in the PR comment but don’t block
Low issues — track for future sprints

Combine with manual audits

Automated scanning catches a lot, but it can’t replace human judgment entirely. Use AccessHawk for continuous automated checks and supplement with periodic manual audits for complex interactions, dynamic content, and user flow testing.

Monitor trends over time

Track your accessibility score across deployments. A gradually increasing issue count signals tech debt accumulating — address it before it becomes a bigger problem.

Accessibility testing in CI/CD is a quality practice, same as linting or security scanning. Catching issues early and automatically means fewer surprises in production and a better experience for everyone using your product.

Integrating AI-Powered WCAG Scanning into Your CI/CD Pipeline