Accessibility Testing: Tools, Automation & CI/CD

# Install axe-core CLI
npm install -g @axe-core/cli

# Run an audit on a local URL
npx axe http://localhost:3000 --save report.json

# Run on a production URL
npx axe https://example.com --exit

// Programmatic usage in Node.js
const { axe } = require('axe-core');
const { JSDOM } = require('jsdom');

async function auditPage(html) {
  const { window } = new JSDOM(html);
  const results = await axe.run(window.document, {
    runOnly: ['wcag2a', 'wcag2aa', 'wcag22aa'],
    resultTypes: ['violations', 'incomplete'],
  });

  console.log(`Found ${results.violations.length} violations`);
  results.violations.forEach(v => {
    console.log(`\n[${v.impact.toUpperCase()}] ${v.help}`);
    console.log(`  WCAG: ${v.tags.filter(t => t.startsWith('wcag')).join(', ')}`);
    console.log(`  Nodes: ${v.nodes.length}`);
    v.nodes.forEach(n => {
      console.log(`  → ${n.target.join(', ')}`);
      console.log(`    ${n.failureSummary}`);
    });
  });

  return results;
}

# Lighthouse CLI
npx lighthouse https://example.com --output=json --output-path=report.json

# Only run accessibility audit
npx lighthouse https://example.com --only-categories=accessibility

# Install Pa11y
npm install -g pa11y

# Run a single-page audit
pa11y https://example.com

# Run with configuration
pa11y --config .pa11yrc https://example.com

{
  "standard": "WCAG2AA",
  "runners": ["axe", "htmlcs"],
  "hideElements": ".cookie-banner",
  "ignore": [
    "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail"
  ]
}

# .github/workflows/lighthouse-ci.yml
name: Lighthouse CI
on: [pull_request]
jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build
      - name: Start server
        run: npm run start & sleep 5
      - name: Run Lighthouse CI
        run: |
          npm install -g @lhci/cli
          lhci autorun --config=./lighthouserc.js

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      url: ['http://localhost:3000'],
      numberOfRuns: 3,
      settings: {
        onlyCategories: ['accessibility'],
      },
    },
    assert: {
      assertions: {
        'categories:accessibility': ['error', { minScore: 0.9 }],
      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

# .github/workflows/axe-a11y.yml
name: Accessibility - axe-core
on: [pull_request]
jobs:
  axe:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build
      - name: Start preview
        run: npx serve out &
      - name: Run axe
        uses: dequelabs/axe-github-action@v3
        with:
          urls: |
            http://localhost:3000
            http://localhost:3000/products
            http://localhost:3000/contact
          output: axe-report.json
      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: axe-report
          path: axe-report.json

# .github/workflows/pa11y-ci.yml
name: Accessibility - Pa11y CI
on: [pull_request]
jobs:
  pa11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup
        run: npm ci
      - name: Build & Start
        run: |
          npm run build
          npx serve out &
          sleep 5
      - name: Run Pa11y CI
        run: npx pa11y-ci --config .pa11yci.json

{
  "defaults": {
    "timeout": 30000,
    "standard": "WCAG2AA",
    "runners": ["axe"]
  },
  "urls": [
    "http://localhost:3000/",
    "http://localhost:3000/products",
    "http://localhost:3000/blog",
    "http://localhost:3000/contact"
  ]
}

// Component.test.js
import { axe, toHaveNoViolations } from 'jest-axe';
import { render } from '@testing-library/react';
import ProductCard from './ProductCard';

expect.extend(toHaveNoViolations);

describe('ProductCard accessibility', () => {
  it('should have no accessibility violations', async () => {
    const { container } = render(
      <ProductCard
        title="Doda Browser"
        description="A fast, secure browser"
        price="$0"
      />
    );

    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });

  it('should announce price changes', async () => {
    const { container, rerender } = render(
      <ProductCard title="Test" price="$10" />
    );

    rerender(
      <ProductCard title="Test" price="$15" />
    );

    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
});

// cypress/e2e/a11y.cy.js
describe('Accessibility tests', () => {
  beforeEach(() => {
    cy.visit('/');
    cy.injectAxe();
  });

  it('Home page has no violations', () => {
    cy.checkA11y(null, {
      runOnly: ['wcag2a', 'wcag2aa', 'wcag22aa'],
    });
  });

  it('Navigation is accessible', () => {
    cy.checkA11y('nav', {
      runOnly: ['wcag2a', 'wcag2aa'],
    });
  });

  it('Form page has no violations', () => {
    cy.visit('/contact');
    cy.injectAxe();
    cy.checkA11y();

    // Test after form submission with errors
    cy.get('button[type="submit"]').click();
    cy.checkA11y(null, {
      includedImpacts: ['critical', 'serious'],
    });
  });
});

// a11y.spec.js
const { test, expect } = require('@playwright/test');
const { AxeBuilder } = require('@axe-core/playwright');

test.describe('Accessibility', () => {
  test('homepage should not have accessibility violations', async ({ page }) => {
    await page.goto('/');

    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
      .analyze();

    expect(results.violations).toEqual([]);
  });

  test('product page should have no critical violations', async ({ page }) => {
    await page.goto('/products/1');

    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa'])
      .options({ resultTypes: ['violations'] })
      .analyze();

    const criticalViolations = results.violations.filter(
      v => v.impact === 'critical' || v.impact === 'serious'
    );

    expect(criticalViolations).toEqual([]);
  });
});

## Manual Accessibility Testing Checklist

### Keyboard Testing
- [ ] Can I Tab through all interactive elements?
- [ ] Is the focus indicator always visible?
- [ ] Can I activate all elements with Enter/Space?
- [ ] Can I navigate dropdowns with arrow keys?
- [ ] Can I close modals with Escape?
- [ ] Does focus return to the trigger after closing a modal?
- [ ] Is there a skip link and does it work?
- [ ] Is there no keyboard trap (focus stuck)?

### Screen Reader Testing
- [ ] Does the page title describe the content?
- [ ] Can I navigate by headings (H1-H6)?
- [ ] Can I navigate by landmarks?
- [ ] Are all images described via alt text?
- [ ] Are form fields announced with labels?
- [ ] Are error messages announced?
- [ ] Is dynamic content (modal, update) announced?
- [ ] Does the reading order match the visual order?

### Zoom Testing
- [ ] Can I zoom to 200% without losing content?
- [ ] Can I zoom to 400% and still read text?
- [ ] Does the layout remain usable at all zoom levels?
- [ ] Does text reflow without horizontal scrolling?

### Color and Contrast
- [ ] Does all text pass 4.5:1 contrast minimum?
- [ ] Are error states conveyed with more than color?
- [ ] Are links distinguishable from body text?
- [ ] Do focus indicators have 3:1 contrast with background?

### Mobile Testing
- [ ] Are touch targets at least 24×24px (ideally 44×44px)?
- [ ] Is content not obscured by notch/status bar?
- [ ] Can the site be used in both portrait and landscape?
- [ ] Does VoiceOver/TalkBack read everything correctly?

## iOS Accessibility Testing (VoiceOver)

### Setup
1. Enable: Settings → Accessibility → VoiceOver → On
2. Practice gestures: swipe right (next), swipe left (previous),
   double-tap (activate), two-finger scroll
3. Use Rotor (twist two fingers): navigate by headings, links,
   form controls, landmarks

### Test Checklist
- [ ] Can I complete a purchase with VoiceOver only?
- [ ] Are all elements reachable by swiping?
- [ ] Do custom gestures work?
- [ ] Does the Rotor show appropriate navigation options?
- [ ] Is dynamic content announced?

## Android Accessibility Testing (TalkBack)

### Setup
1. Enable: Settings → Accessibility → TalkBack → On
2. Similar gestures to VoiceOver

### Test Checklist
- [ ] Can I navigate with swipe left/right?
- [ ] Are all form fields labeled?
- [ ] Is the reading order correct?
- [ ] Do touch targets have sufficient spacing?

# .github/ISSUE_TEMPLATE/a11y-bug.yml
name: Accessibility Issue
description: Report an accessibility violation
labels: [accessibility]
body:
  - type: dropdown
    id: severity
    attributes:
      label: Severity
      options:
        - Critical (Level A — blocks users)
        - Serious (Level AA — significant impact)
        - Moderate (Level AA — inconvenience)
        - Minor (Level AAA — enhancement)
    validations:
      required: true
  - type: input
    id: wcag
    attributes:
      label: WCAG Criterion
      description: e.g., SC 1.1.1 Non-text Content (Level A)
  - type: textarea
    id: description
    attributes:
      label: Description
      description: What is the issue and where does it occur?
  - type: textarea
    id: screen-reader-output
    attributes:
      label: Screen Reader Output
      description: What does the screen reader say?
  - type: textarea
    id: expected
    attributes:
      label: Expected Behavior
  - type: textarea
    id: remediation
    attributes:
      label: Proposed Fix

# .github/workflows/full-a11y.yml
name: Full Accessibility Pipeline
on:
  pull_request:
    paths:
      - 'src/**'
      - 'public/**'

jobs:
  # Layer 1: Unit-level accessibility checks
  unit-a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run test:a11y    # jest-axe tests

  # Layer 2: E2E accessibility checks
  e2e-a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      - run: npm run test:e2e:a11y  # cypress-axe tests

  # Layer 3: Full-page scans
  scan-a11y:
    runs-on: ubuntu-latest
    needs: [unit-a11y, e2e-a11y]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - run: npx serve out &
      - uses: dequelabs/axe-github-action@v3
        with:
          urls: |
            http://localhost:3000/
            http://localhost:3000/products
            http://localhost:3000/contact

  # Layer 4: Lighthouse score
  lighthouse:
    runs-on: ubuntu-latest
    needs: [scan-a11y]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - run: npx serve out &
      - run: |
          npm install -g @lhci/cli
          lhci autorun --config=./lighthouserc.js

// a11y-reporter.js — custom reporter combining multiple tools
const { axe } = require('axe-core');
const { JSDOM } = require('jsdom');

async function runFullAudit(urls) {
  const report = {
    timestamp: new Date().toISOString(),
    tool: 'DodaTech A11y Reporter v1.0',
    summary: { passed: 0, failed: 0, total: 0 },
    pages: [],
  };

  for (const url of urls) {
    console.log(`\nAuditing: ${url}`);
    const response = await fetch(url);
    const html = await response.text();
    const { window } = new JSDOM(html);
    const results = await axe.run(window.document, {
      runOnly: ['wcag2a', 'wcag2aa', 'wcag22aa'],
    });

    const pageReport = {
      url,
      violations: results.violations.map(v => ({
        id: v.id,
        impact: v.impact,
        help: v.help,
        wcag: v.tags.filter(t => t.startsWith('wcag')),
        nodes: v.nodes.length,
        elements: v.nodes.map(n => n.target.join(', ')),
      })),
      passes: results.passes.length,
      incomplete: results.incomplete.length,
    };

    pageReport.score = Math.round(
      (pageReport.passes / (pageReport.passes + pageReport.violations.length)) * 100
    );

    report.pages.push(pageReport);
    report.summary.total += pageReport.violations.length + pageReport.passes;
    report.summary.failed += pageReport.violations.length;
    report.summary.passed += pageReport.passes;

    console.log(`  Violations: ${pageReport.violations.length}`);
    console.log(`  Passes: ${pageReport.passes}`);
    console.log(`  Score: ${pageReport.score}%`);
  }

  return report;
}

// Usage
runFullAudit([
  'http://localhost:3000/',
  'http://localhost:3000/products',
  'http://localhost:3000/contact',
]).then(report => {
  console.log('\n=== FINAL REPORT ===');
  console.log(`Total pages: ${report.pages.length}`);
  console.log(`Passed checks: ${report.summary.passed}`);
  console.log(`Failed checks: ${report.summary.failed}`);
  console.log(`Overall: ${Math.round(report.summary.passed / report.summary.total * 100)}%`);
});