Accessibility Testing (Chinese Version)

accessibility-testing-en

prompts/accessibility-testing.md

When to Use

• When users mention "accessibility testing", "a11y", or "WCAG"
• When you need to design accessibility testing strategies, test cases, and plans based on WCAG standards
• Trigger Examples: "Design accessibility test cases based on the following requirements" "Create a WCAG 2.1 compliance testing plan"

Output Format Options

How to Use the Prompts in This Skill

1. Open

   prompts/accessibility-testing.md

   in this directory, copy the content below the dashed line into your AI conversation.
2. Attach your functional requirements or system specifications.
3. If you need Excel/CSV/JSON, add the request phrase from output-formats.md at the end.

Reference Files

• prompts/accessibility-testing.md — Standard-version prompts for accessibility testing
• output-formats.md — Instructions for requesting Markdown / Excel / CSV / JSON formats

Code Examples | Code Examples

1. axe-core + Playwright Automation Testing - Complete accessibility automation testing suite
   • 12 test cases
   • Covers WCAG 2.1 Level A/AA
   • Includes automation and manual testing guidelines
   • Detailed violation reports
2. WCAG 2.1 Manual Testing Checklist (Coming soon)
3. Screen Reader Testing Guidelines (Coming soon)

Common Pitfalls | Common Pitfalls

• ❌ Relying solely on automation tools → ✅ Combine automation tools (30% coverage) with manual testing (70% coverage)
• ❌ Ignoring keyboard navigation → ✅ Ensure all functions are accessible via keyboard
• ❌ Insufficient color contrast → ✅ Use tools to check contrast, ensure at least 4.5:1 (normal text)
• ❌ Missing alternative text → ✅ Provide meaningful alt text for all images and icons
• ❌ Missing form labels → ✅ Ensure all form controls have associated labels
• ❌ Testing only after development is complete → ✅ Consider accessibility during design and development phases

Best Practices | Best Practices

1. WCAG Compliance
   • Follow WCAG 2.1 Level AA standards (minimum requirement)
   • Use automation tools to detect common issues
   • Conduct manual testing to verify complex interactions
   • Test with real assistive technologies
2. Testing Strategy
   • Integrate automated accessibility testing into CI/CD
   • Conduct regular manual testing and user testing
   • Cross-verify with multiple tools
   • Document and track accessibility issues
3. Key Testing Points
   • Keyboard navigation (Tab, Enter, Esc, arrow keys)
   • Screen reader compatibility (NVDA, JAWS, VoiceOver)
   • Color contrast and visual design
   • Form accessibility
   • Semantic HTML
   • Correct use of ARIA attributes
4. Tool Selection
   • axe-core: Automation testing (most comprehensive)
   • Lighthouse: Quick audits
   • WAVE: Visual issue detection
   • Screen readers: Real user experience testing
5. Documentation and Reporting
   • Clearly document violations and their severity
   • Provide repair suggestions and code examples
   • Track repair progress
   • Generate regular compliance reports

Troubleshooting | Troubleshooting

Issue 1: axe-core reports too many false positives

1. Configure rules to exclude known false positives:
   typescript

   await new AxeBuilder({ page })
     .disableRules(['color-contrast']) // Exclude specific rules
     .analyze();

2. Filter using tags:
   typescript

   await new AxeBuilder({ page })
     .withTags(['wcag2a', 'wcag2aa']) // Only check WCAG 2.1 A/AA
     .analyze();

3. Manually verify suspicious issues
4. Update to the latest version of axe-core

Issue 2: Unable to detect accessibility issues in dynamic content

1. Run tests after triggering dynamic content:
   typescript

   await page.click('[data-testid="open-modal"]');
   await page.waitForSelector('[role="dialog"]');
   const results = await new AxeBuilder({ page }).analyze();

2. Test specific regions:
   typescript

   await new AxeBuilder({ page })
     .include('[role="dialog"]')
     .analyze();

3. Test accessibility in different states

Issue 3: Keyboard navigation tests fail

1. Check tabindex attributes:
   html

   <!-- ✅ Recommended: Use tabindex="0" to make elements focusable -->
   <div role="button" tabindex="0">Click me</div>
   
   <!-- ❌ Avoid: tabindex > 0 breaks natural Tab order -->
   <div tabindex="5">Bad practice</div>

2. Use semantic HTML:
   html

   <!-- ✅ Recommended: Native buttons are automatically focusable -->
   <button>Click me</button>
   
   <!-- ❌ Not recommended: Requires additional accessibility attributes -->
   <div onclick="...">Click me</div>

3. Add keyboard event handlers:
   typescript

   element.addEventListener('keydown', (e) => {
     if (e.key === 'Enter' || e.key === ' ') {
       // Handle activation
     }
   });

Issue 4: Insufficient color contrast

1. Use contrast checking tools:
   • Chrome DevTools Lighthouse
   • WebAIM Contrast Checker
   • Colour Contrast Analyser
2. Ensure contrast ratios of at least:
   • Normal text: 4.5:1
   • Large text (18pt+): 3:1
   • UI components: 3:1
3. Adjust color schemes:
   css

   /* ❌ Insufficient contrast */
   color: #999; /* Gray text */
   background: #fff; /* White background */
   
   /* ✅ Sufficient contrast */
   color: #595959; /* Dark gray text */
   background: #fff; /* White background */

Issue 5: Screen readers cannot read content correctly

1. Use semantic HTML:
   html

   <!-- ✅ Recommended -->
   <nav>
     <ul>
       <li><a href="/">Home</a></li>
     </ul>
   </nav>
   
   <!-- ❌ Not recommended -->
   <div class="nav">
     <div class="item">Home</div>
   </div>

2. Use ARIA attributes correctly:
   html

   <!-- ✅ Recommended: Provide meaningful labels -->
   <button aria-label="Close dialog">×</button>
   
   <!-- ❌ Not recommended: Screen readers will only read "multiplication sign" -->
   <button>×</button>

3. Use aria-live to notify dynamic changes:
   html

   <div aria-live="polite" aria-atomic="true">
     <!-- Dynamic content -->
   </div>

Issue 6: Form accessibility issues

1. Associate labels with inputs:
   html

   <!-- ✅ Recommended: Explicit association -->
   <label for="email">Email</label>
   <input id="email" type="email" />
   
   <!-- ✅ Recommended: Implicit association -->
   <label>
     Email
     <input type="email" />
   </label>

2. Provide clear error messages:
   html

   <input
     id="email"
     type="email"
     aria-invalid="true"
     aria-describedby="email-error"
   />
   <span id="email-error" role="alert">
     Please enter a valid email address
   </span>

3. Use fieldset and legend for grouping:
   html

   <fieldset>
     <legend>Contact Information</legend>
     <!-- Form controls -->
   </fieldset>

Issue 7: Tests fail in CI environment

1. Ensure browsers are installed in CI environment:
   yaml

   - name: Install Playwright
     run: npx playwright install --with-deps

2. Check environment differences (fonts, rendering)
3. Save screenshots and reports when tests fail:
   typescript

   if (violations.length > 0) {
     await page.screenshot({ path: 'a11y-violations.png' });
     fs.writeFileSync('a11y-report.json', JSON.stringify(violations));
   }

4. Use Docker containers to ensure environment consistency

Get More Help

1. Check FAQ.md
2. Check the README.md files in the examples
3. Refer to the official WCAG 2.1 documentation
4. Use WebAIM resources
5. Submit a new Issue with detailed information