workforce-pay-bill-p/ACCESSIBILITY_TESTING.md

Accessibility Testing Guide for WorkForce Pro

Overview

This guide provides step-by-step instructions for testing accessibility features in WorkForce Pro to ensure WCAG 2.1 AA compliance.

Automated Testing

Setup

npm install --save-dev @axe-core/react
npm install --save-dev jest-axe

Running Tests

# Run all accessibility tests
npm run test:a11y

# Run with coverage
npm run test:a11y -- --coverage

Automated Checks

✅ Color contrast ratios ✅ ARIA attribute validity ✅ Keyboard navigation structure ✅ Semantic HTML validation ✅ Form label associations ✅ Heading hierarchy

Manual Testing Checklist

1. Keyboard Navigation Testing

Test Procedure

1. Disconnect or ignore your mouse
2. Use only keyboard to navigate
3. Test all interactive elements

Checklist

• Tab key moves focus forward through all interactive elements
• Shift+Tab moves focus backward
• Focus indicator is visible at all times
• Focus order is logical and follows visual layout
• Enter key activates buttons and links
• Space bar toggles checkboxes and activates buttons
• Escape key closes modals and dialogs
• Arrow keys work in custom widgets (tabs, menus, etc.)
• No keyboard traps (can always escape with Tab/Escape)
• Skip link appears when pressing Tab on page load

Views to Test

1. Dashboard

   • All metric cards are focusable
   • Chart elements provide keyboard access
   • Action buttons are accessible

2. Timesheets

   • Table navigation with arrow keys
   • Enter opens detail view
   • Can filter and search with keyboard

3. Billing

   • Invoice list is keyboard navigable
   • Can open invoice details
   • Actions menu accessible

4. Forms

   • Tab order follows visual flow
   • All fields focusable
   • Date pickers keyboard accessible
   • Dropdowns navigable with arrows

5. Dialogs/Modals

   • Focus moves to dialog on open
   • Focus trapped within dialog
   • Escape closes dialog
   • Focus returns to trigger on close

2. Screen Reader Testing

Required Tools

• Windows: NVDA (free) or JAWS
• macOS: VoiceOver (built-in)
• Linux: Orca
• Mobile: TalkBack (Android) or VoiceOver (iOS)

NVDA Quick Start (Windows)

Insert = NVDA modifier key

Insert+Q = Quit NVDA
Insert+N = NVDA menu
Insert+T = Read title
H/Shift+H = Next/Previous heading
B/Shift+B = Next/Previous button
F/Shift+F = Next/Previous form field
T/Shift+T = Next/Previous table
Insert+Down = Read all
Insert+Up = Current line

VoiceOver Quick Start (macOS)

Control+Option = VO (VoiceOver modifier)

VO+A = Start reading
VO+Left/Right Arrow = Navigate
VO+Space = Activate element
VO+Shift+Down = Into element
VO+Shift+Up = Out of element
VO+U = Rotor menu
VO+H = Next heading

Screen Reader Checklist

Navigation

• Skip link is announced and functional
• Main landmarks are announced (navigation, main, aside)
• Page title is descriptive and announced
• Headings form logical hierarchy (H1 → H2 → H3)
• Links have descriptive text (not "click here")

Forms

• Labels are associated with inputs
• Required fields are announced as required
• Error messages are announced
• Field instructions are read before input
• Group labels for radio/checkbox groups
• Placeholder text is not the only label

Interactive Elements

• Button purpose is clear from label
• Icon buttons have aria-label
• Current page/tab indicated with aria-current
• Disabled state is announced
• Loading state is announced

Dynamic Content

• Toast notifications are announced
• Live regions announce updates
• AJAX content changes are announced
• Loading spinners have status messages

Tables

• Table has caption or aria-label
• Column headers properly marked
• Row headers when applicable
• Table navigation works correctly

3. Visual Testing

Focus Indicators

• Visible on all interactive elements
• High contrast (3:1 minimum)
• Not obscured by other elements
• Consistent style throughout app
• Clearly distinguishable from hover state

Color Contrast

Use tools like:

• WebAIM Contrast Checker
• Chrome DevTools Color Picker
• Stark plugin for Figma/browsers

Requirements:

• Normal text: 4.5:1
• Large text (18pt+): 3:1
• UI components: 3:1
• Icons: 3:1

Test combinations:

• Text on background
• Text on colored backgrounds
• Links in paragraphs
• Button text
• Icon colors
• Border colors
• Focus indicators

Text Readability

• Text can be resized to 200% without loss of content
• No horizontal scrolling at 400% zoom
• Line height at least 1.5x font size
• Paragraph spacing at least 2x font size
• Letter spacing at least 0.12x font size
• Word spacing at least 0.16x font size

4. Reduced Motion Testing

Enable Reduced Motion

Windows 10/11: Settings → Ease of Access → Display → Show animations

macOS: System Preferences → Accessibility → Display → Reduce motion

Test:

• Animations are disabled or simplified
• Transitions are instant or very brief
• Auto-playing content is paused
• Page remains functional without motion

5. Browser Testing

Test in multiple browsers to ensure compatibility:

• Chrome/Edge (Chromium)
• Firefox
• Safari
• Mobile Safari (iOS)
• Chrome Mobile (Android)

Test Scenarios by Feature

Login Flow

1. Navigate to login with keyboard
2. Use screen reader to fill form
3. Verify error messages are announced
4. Test with high contrast mode
5. Test at 200% zoom

Checklist:

• All fields have visible labels
• Errors announced on submission
• Password visibility toggle accessible
• Remember me checkbox accessible
• Login button clearly labeled

Creating a Timesheet

1. Navigate to Timesheets view
2. Use keyboard to open creation dialog
3. Fill form using only keyboard
4. Submit and verify success announcement

Checklist:

• Dialog receives focus on open
• All form fields accessible
• Date picker keyboard friendly
• Time input accessible
• Validation errors announced
• Success message announced

Searching and Filtering

1. Use keyboard shortcut (Ctrl+K) to open search
2. Navigate results with arrows
3. Apply filters with keyboard
4. Verify results announced

Checklist:

• Search shortcut works
• Results announced to screen reader
• No results state communicated
• Filter controls keyboard accessible
• Clear filters button accessible

Viewing Reports

1. Navigate to Reports view
2. Interact with charts via keyboard
3. Export data using keyboard
4. Verify high contrast mode displays correctly

Checklist:

• Chart data accessible
• Legend items selectable
• Export button accessible
• Date range picker accessible
• Data table sortable via keyboard

Common Issues and Solutions

Issue: Focus Not Visible

Solution: Ensure :focus-visible styles are applied and have sufficient contrast

Issue: Screen Reader Not Announcing Updates

Solution: Add aria-live regions or use useAnnounce hook

Issue: Keyboard Trap in Modal

Solution: Use useFocusTrap hook and ensure Escape key closes modal

Issue: Poor Color Contrast

Solution: Update CSS variables to meet WCAG AA standards (4.5:1)

Issue: Icon Button No Label

Solution: Add aria-label or aria-labelledby attribute

Issue: Form Errors Not Announced

Solution: Link errors with aria-describedby and use role="alert"

Reporting Accessibility Issues

When filing an accessibility bug, include:

1. WCAG Criterion: Which guideline is violated
2. Severity: Critical, High, Medium, Low
3. User Impact: Who is affected and how
4. Steps to Reproduce: Detailed steps
5. Expected Behavior: What should happen
6. Actual Behavior: What actually happens
7. Environment: Browser, OS, assistive technology used
8. Screenshots/Video: Visual evidence if applicable

Example Bug Report

Title: Invoice table not keyboard navigable

WCAG: 2.1.1 Keyboard (Level A)
Severity: High
Impact: Keyboard-only users cannot navigate invoice table

Steps:
1. Navigate to Billing view
2. Press Tab to focus on invoice table
3. Try to navigate rows with arrow keys

Expected: Arrow keys should navigate between table cells
Actual: Arrow keys do nothing, Tab skips entire table

Environment: Chrome 120, Windows 11, NVDA 2023.3

Accessibility Champions Program

Every development team should have an accessibility champion who:

• Reviews PRs for accessibility issues
• Runs automated tests on new features
• Conducts keyboard navigation testing
• Performs screen reader testing
• Maintains this documentation
• Educates team on best practices

Resources

Tools

• axe DevTools Browser Extension
• WAVE Browser Extension
• Lighthouse in Chrome DevTools
• NVDA Screen Reader

Documentation

• WCAG 2.1 Guidelines
• WAI-ARIA Authoring Practices
• MDN Accessibility Docs
• WebAIM Resources

Training

• Web Accessibility Course (Udacity)
• Digital Accessibility Foundations (W3C)
• Deque University

Continuous Monitoring

Pre-commit Hooks

Ensure accessibility linting runs before commits:

{
  "husky": {
    "hooks": {
      "pre-commit": "npm run lint:a11y"
    }
  }
}

CI/CD Integration

Add accessibility tests to your pipeline:

- name: Accessibility Tests
  run: npm run test:a11y

Monthly Audits

Schedule monthly comprehensive audits:

• Full manual keyboard testing
• Screen reader testing of new features
• Automated scan of all pages
• User testing with people with disabilities

Success Metrics

Track these metrics to measure accessibility:

• Automated test pass rate (target: 100%)
• Manual test completion rate (target: 100% per release)
• Accessibility bugs in backlog (target: <5)
• Average time to fix a11y bugs (target: <2 sprints)
• Team training completion (target: 100%)