Testing and Validation Tools

// Install dependencies
// npm install --save-dev jest-axe @testing-library/react @testing-library/jest-dom

// Jest setup (setupTests.js)
import { toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

// Component test with jest-axe
import { render } from '@testing-library/react';
import { axe } from 'jest-axe';
import Button from './Button';

describe('Button accessibility', () => {
  it('should not have accessibility violations', async () => {
    const { container } = render(
      <Button onClick={() => {}}>Click me</Button>
    );
    
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
  
  it('should have accessible name', () => {
    const { getByRole } = render(<Button>Submit</Button>);
    expect(getByRole('button', { name: 'Submit' })).toBeInTheDocument();
  });
});

// Playwright with axe-core
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('homepage should not have accessibility violations', async ({ page }) => {
  await page.goto('http://localhost:3000');
  
  const accessibilityScanResults = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
    .analyze();
  
  expect(accessibilityScanResults.violations).toEqual([]);
});

// Cypress with cypress-axe
import 'cypress-axe';

describe('Accessibility tests', () => {
  beforeEach(() => {
    cy.visit('/');
    cy.injectAxe();
  });
  
  it('should have no accessibility violations', () => {
    cy.checkA11y();
  });
  
  it('should check specific component', () => {
    cy.checkA11y('.modal-dialog');
  });
  
  it('should exclude specific elements', () => {
    cy.checkA11y(null, {
      exclude: ['.third-party-widget']
    });
  });
});

// ESLint configuration (.eslintrc.js)
module.exports = {
  extends: [
    'plugin:jsx-a11y/recommended'
  ],
  plugins: ['jsx-a11y'],
  rules: {
    'jsx-a11y/anchor-is-valid': 'error',
    'jsx-a11y/img-redundant-alt': 'error',
    'jsx-a11y/no-autofocus': 'warn',
    'jsx-a11y/label-has-associated-control': 'error'
  }
};

// Screen Reader Test Script

1. Page Structure Test
   □ Navigate by headings (H key) - logical hierarchy?
   □ Navigate by landmarks (D/R key) - proper regions?
   □ Page title announced correctly?
   □ Main content easily accessible?

2. Interactive Elements Test
   □ Navigate by buttons (B key) - all announced?
   □ Button states announced (pressed, expanded)?
   □ Links (K key) - descriptive text, not "click here"?
   □ Form fields (F key) - labels associated?

3. Dynamic Content Test
   □ Form validation errors announced?
   □ Live region updates announced?
   □ Loading states announced?
   □ Route changes announced (SPA)?

4. Complex Widgets Test
   □ Modal dialog focus trapped?
   □ Accordion expand/collapse announced?
   □ Tab panels keyboard navigable?
   □ Combobox autocomplete working?

5. Table Test
   □ Table headers announced with cells?
   □ Navigate by cell (Ctrl+Alt+Arrow)?
   □ Row/column headers associated?

// Screen Reader Testing Script Example
describe('Screen reader announcements', () => {
  it('should announce form errors', () => {
    // Simulate screen reader
    const form = document.querySelector('form');
    const errorMessage = document.querySelector('[role="alert"]');
    
    // Verify error in accessibility tree
    expect(errorMessage).toHaveAttribute('role', 'alert');
    expect(errorMessage).toHaveTextContent('Email is required');
  });
  
  it('should announce dynamic updates', () => {
    const liveRegion = document.querySelector('[aria-live="polite"]');
    expect(liveRegion).toBeInTheDocument();
    
    // Update content
    liveRegion.textContent = '3 items added to cart';
    
    // Verify content updated
    expect(liveRegion).toHaveTextContent('3 items added to cart');
  });
});

// Keyboard navigation test utilities
class KeyboardTester {
  // Simulate Tab key
  static tab(element, shift = false) {
    const event = new KeyboardEvent('keydown', {
      key: 'Tab',
      code: 'Tab',
      keyCode: 9,
      shiftKey: shift,
      bubbles: true
    });
    element.dispatchEvent(event);
  }
  
  // Get all focusable elements
  static getFocusableElements(container = document) {
    const selector = [
      'a[href]',
      'button:not([disabled])',
      'textarea:not([disabled])',
      'input:not([disabled]):not([type="hidden"])',
      'select:not([disabled])',
      '[tabindex]:not([tabindex="-1"])'
    ].join(', ');
    
    return Array.from(container.querySelectorAll(selector));
  }
  
  // Test tab order
  static testTabOrder(expectedOrder) {
    const focusable = this.getFocusableElements();
    const actualOrder = focusable.map(el => 
      el.getAttribute('data-testid') || el.textContent.trim()
    );
    
    console.log('Expected:', expectedOrder);
    console.log('Actual:', actualOrder);
    
    return JSON.stringify(expectedOrder) === JSON.stringify(actualOrder);
  }
}

// Playwright keyboard testing
test('keyboard navigation works correctly', async ({ page }) => {
  await page.goto('/');
  
  // Tab through all interactive elements
  await page.keyboard.press('Tab');
  await expect(page.locator('button').first()).toBeFocused();
  
  await page.keyboard.press('Tab');
  await expect(page.locator('a').first()).toBeFocused();
  
  // Test Shift+Tab (reverse)
  await page.keyboard.press('Shift+Tab');
  await expect(page.locator('button').first()).toBeFocused();
  
  // Test Enter activation
  await page.keyboard.press('Enter');
  // Verify button action occurred
});

// Testing-Library keyboard test
import { render } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('modal closes with Escape key', async () => {
  const user = userEvent.setup();
  const onClose = jest.fn();
  
  const { getByRole } = render(
    <Modal isOpen onClose={onClose}>
      <h2>Modal Title</h2>
    </Modal>
  );
  
  // Modal is open
  expect(getByRole('dialog')).toBeInTheDocument();
  
  // Press Escape
  await user.keyboard('{Escape}');
  
  // Modal should close
  expect(onClose).toHaveBeenCalled();
});

// Manual test checklist
/*
Keyboard Navigation Test Checklist:

□ Tab reaches all interactive elements
□ Tab order follows visual/logical order
□ Shift+Tab works in reverse
□ No keyboard traps (can always Tab out)
□ Enter activates buttons and links
□ Space activates buttons and checkboxes
□ Escape closes modals and cancels actions
□ Focus indicators clearly visible (3:1 contrast)
□ Arrow keys work in composite widgets
□ Home/End jump to first/last items
□ No auto-focus unless necessary
□ Focus restored after modal/dropdown closes
*/

// WCAG Contrast Requirements
/*
Text Size              | WCAG AA  | WCAG AAA
--------------------- | -------- | --------
Normal text (<18px)   | 4.5:1    | 7:1
Large text (≥18px)    | 3:1      | 4.5:1
Large bold (≥14px)    | 3:1      | 4.5:1
UI components         | 3:1      | N/A
Graphics/icons        | 3:1      | N/A
Focus indicators      | 3:1      | N/A (WCAG 2.4.13)
*/

// Contrast ratio calculation (relative luminance)
function getLuminance(r, g, b) {
  const [R, G, B] = [r, g, b].map(val => {
    val = val / 255;
    return val <= 0.03928 
      ? val / 12.92 
      : Math.pow((val + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * R + 0.7152 * G + 0.0722 * B;
}

function getContrastRatio(rgb1, rgb2) {
  const lum1 = getLuminance(...rgb1);
  const lum2 = getLuminance(...rgb2);
  const lighter = Math.max(lum1, lum2);
  const darker = Math.min(lum1, lum2);
  return (lighter + 0.05) / (darker + 0.05);
}

// Usage
const textColor = [0, 0, 0];      // Black
const bgColor = [255, 255, 255];  // White
const ratio = getContrastRatio(textColor, bgColor);
console.log(`Contrast ratio: ${ratio.toFixed(2)}:1`); // 21:1

// Validation function
function meetsWCAG(ratio, level = 'AA', isLargeText = false) {
  if (level === 'AAA') {
    return isLargeText ? ratio >= 4.5 : ratio >= 7;
  }
  // AA
  return isLargeText ? ratio >= 3 : ratio >= 4.5;
}

// Automated contrast checking in tests
import { toHaveNoViolations } from 'jest-axe';
import { render } from '@testing-library/react';
import { axe } from 'jest-axe';

test('button has sufficient contrast', async () => {
  const { container } = render(
    <button style={{ background: '#0066cc', color: '#ffffff' }}>
      Click me
    </button>
  );
  
  const results = await axe(container, {
    rules: {
      'color-contrast': { enabled: true }
    }
  });
  
  expect(results).toHaveNoViolations();
});

// CSS color contrast validation
/*
Good contrast examples:
- #000000 on #FFFFFF = 21:1 (AAA)
- #0066CC on #FFFFFF = 8.59:1 (AAA)
- #666666 on #FFFFFF = 5.74:1 (AA)
- #FFFFFF on #0066CC = 8.59:1 (AAA)

Poor contrast examples (avoid):
- #777777 on #FFFFFF = 4.47:1 (fails AA for normal text)
- #0066CC on #000000 = 2.44:1 (fails AA)
- #CCCCCC on #FFFFFF = 1.61:1 (fails all)
*/

// Accessibility Testing Checklist Template

=== KEYBOARD NAVIGATION ===
□ Tab through entire page (top to bottom)
□ Verify all interactive elements reachable
□ Check tab order matches visual order
□ Shift+Tab works in reverse
□ Focus visible on all elements (3:1 contrast)
□ No keyboard traps detected
□ Enter activates buttons/links
□ Space activates buttons/checkboxes
□ Escape closes modals/dropdowns
□ Arrow keys work in custom widgets

=== SCREEN READER ===
□ Use heading navigation (H key) - logical structure
□ Navigate by landmarks (D/R key) - proper regions
□ Check all images have alt text
□ Verify form labels read correctly
□ Test form validation announcements
□ Check ARIA states announced (expanded, pressed, etc.)
□ Verify live region updates announced
□ Test table navigation (headers announced)
□ Check custom widget announcements

=== VISUAL & CONTRAST ===
□ Text contrast meets 4.5:1 (normal) or 3:1 (large)
□ UI component contrast meets 3:1
□ Focus indicators visible (3:1 against adjacent)
□ Information not conveyed by color alone
□ Test with color blindness simulator
□ Check in high contrast mode (Windows)

=== ZOOM & REFLOW ===
□ Zoom to 200% - no horizontal scroll
□ Zoom to 400% for text - content visible
□ Resize to 320px width - content reflows
□ No loss of content at any zoom level
□ Touch targets remain 24×24px minimum
□ Test responsive design breakpoints

=== FORMS ===
□ All inputs have visible labels
□ Labels programmatically associated
□ Required fields clearly indicated
□ Error messages clear and specific
□ Errors announced by screen reader
□ Success confirmation provided
□ Can submit with keyboard

=== MEDIA ===
□ Videos have captions
□ Audio has transcripts
□ Auto-play videos can be paused
□ Media controls keyboard accessible
□ Transcripts provided for audio-only

=== MOBILE ===
□ Test with VoiceOver (iOS)
□ Test with TalkBack (Android)
□ Touch targets 44×44px minimum
□ Works in both orientations
□ Zoom not disabled (no user-scalable=no)
□ Gestures have button alternatives

=== DYNAMICS ===
□ Route changes announced (SPA)
□ Loading states announced
□ Form submission feedback
□ Modal opens - focus trapped
□ Modal closes - focus restored
□ Live regions working (cart updates, etc.)

=== DOCUMENTATION ===
□ Document any known issues
□ Note browser/AT combinations tested
□ Include WCAG conformance level
□ List exemptions (if any)
□ Provide remediation timeline

// package.json scripts
{
  "scripts": {
    "lint:a11y": "eslint --ext .js,.jsx,.ts,.tsx src/",
    "test:a11y": "jest --testMatch '**/*.a11y.test.js'",
    "audit:a11y": "pa11y-ci --config .pa11yci.json",
    "lighthouse": "lighthouse-ci --config=.lighthouserc.json"
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "jest --findRelatedTests --passWithNoTests"
    ]
  }
}

// .eslintrc.js
module.exports = {
  extends: [
    'plugin:jsx-a11y/recommended'
  ],
  plugins: ['jsx-a11y'],
  rules: {
    'jsx-a11y/alt-text': 'error',
    'jsx-a11y/anchor-has-content': 'error',
    'jsx-a11y/anchor-is-valid': 'error',
    'jsx-a11y/aria-props': 'error',
    'jsx-a11y/aria-role': 'error',
    'jsx-a11y/aria-unsupported-elements': 'error',
    'jsx-a11y/label-has-associated-control': 'error',
    'jsx-a11y/no-autofocus': 'warn'
  }
};

// .pa11yci.json (Pa11y CI configuration)
{
  "defaults": {
    "standard": "WCAG2AA",
    "runners": ["axe", "htmlcs"],
    "timeout": 10000,
    "wait": 1000,
    "chromeLaunchConfig": {
      "args": ["--no-sandbox"]
    }
  },
  "urls": [
    "http://localhost:3000",
    "http://localhost:3000/about",
    "http://localhost:3000/products"
  ]
}

// .lighthouserc.json (Lighthouse CI)
{
  "ci": {
    "collect": {
      "url": ["http://localhost:3000"],
      "numberOfRuns": 3
    },
    "assert": {
      "assertions": {
        "categories:accessibility": ["error", {"minScore": 0.9}],
        "aria-allowed-attr": "error",
        "aria-required-attr": "error",
        "button-name": "error",
        "color-contrast": "error",
        "duplicate-id-aria": "error",
        "html-has-lang": "error",
        "image-alt": "error",
        "label": "error",
        "link-name": "error",
        "list": "error"
      }
    }
  }
}

// GitHub Actions workflow (.github/workflows/a11y.yml)
name: Accessibility Tests

on: [push, pull_request]

jobs:
  accessibility:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Lint accessibility
        run: npm run lint:a11y
      
      - name: Build app
        run: npm run build
      
      - name: Start server
        run: npm start &
        
      - name: Wait for server
        run: npx wait-on http://localhost:3000
      
      - name: Run Pa11y CI
        run: npm run audit:a11y
      
      - name: Run Lighthouse CI
        run: |
          npm install -g @lhci/cli
          lhci autorun
      
      - name: Upload results
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: accessibility-reports
          path: |
            pa11y-results/
            .lighthouseci/

// Storybook a11y addon (.storybook/preview.js)
import { withA11y } from '@storybook/addon-a11y';

export const decorators = [withA11y];

export const parameters = {
  a11y: {
    config: {
      rules: [
        {
          id: 'color-contrast',
          enabled: true
        }
      ]
    }
  }
};