mirror of https://github.com/docusealco/docuseal
This commit establishes the foundation for WCAG 2.2 Level AA compliance: Infrastructure: - Add axe-core-rspec gem for automated accessibility testing - Create spec/accessibility/ directory structure - Add accessibility_helpers.rb with custom WCAG test helpers - Add comprehensive testing documentation (README.md, SETUP_NOTES.md) Semantic Landmarks (WCAG 2.4.1): - Add <main> landmark with id="main-content" to application layout - Add <nav> landmark with aria-label to navbar - Add skip navigation link for keyboard users - Skip link uses focus:translate-y-0 to appear only on keyboard focus These changes address critical barriers for screen reader and keyboard users. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>pull/599/head
Marcelo Paiva
1 month ago
parent
bb7a233863
commit
aa9cb026a9
@ -0,0 +1,201 @@
|
|||||||
|
# Accessibility Testing Framework
|
||||||
|
|
||||||
|
This directory contains accessibility (a11y) tests for DocuSeal, targeting **WCAG 2.2 Level AA compliance**.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The accessibility testing framework uses:
|
||||||
|
- **RSpec** for test structure
|
||||||
|
- **Capybara** with **Cuprite** (headless Chrome) for browser automation
|
||||||
|
- **axe-core-rspec** for automated WCAG validation
|
||||||
|
- **Custom accessibility helpers** in `spec/support/accessibility_helpers.rb`
|
||||||
|
|
||||||
|
## Running Tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run all accessibility tests
|
||||||
|
bundle exec rspec spec/accessibility/
|
||||||
|
|
||||||
|
# Run specific accessibility test file
|
||||||
|
bundle exec rspec spec/accessibility/layouts_spec.rb
|
||||||
|
|
||||||
|
# Run with visible browser for debugging
|
||||||
|
HEADLESS=false bundle exec rspec spec/accessibility/
|
||||||
|
|
||||||
|
# Run with coverage report
|
||||||
|
COVERAGE=true bundle exec rspec spec/accessibility/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Test Categories
|
||||||
|
|
||||||
|
### Phase 1: Critical Barriers
|
||||||
|
- **layouts_spec.rb** - Semantic landmarks, skip navigation
|
||||||
|
- **images_spec.rb** - Alt text for images
|
||||||
|
- **buttons_spec.rb** - ARIA labels for icon buttons
|
||||||
|
- **keyboard_spec.rb** - Keyboard support for custom elements
|
||||||
|
|
||||||
|
### Phase 2: Forms & Input Accessibility
|
||||||
|
- **forms_spec.rb** - Form error associations, labels
|
||||||
|
- **modals_spec.rb** - Modal accessibility, focus traps
|
||||||
|
- **live_regions_spec.rb** - ARIA live announcements
|
||||||
|
|
||||||
|
### Phase 3: Complex Interactions
|
||||||
|
- **components_spec.rb** - Vue component accessibility
|
||||||
|
- **tables_spec.rb** - Table headers, captions, scope
|
||||||
|
|
||||||
|
### Phase 4: Comprehensive Coverage
|
||||||
|
- **wcag_compliance_spec.rb** - Full WCAG 2.2 AA validation with axe-core
|
||||||
|
|
||||||
|
## Custom Helpers
|
||||||
|
|
||||||
|
### Available Test Helpers
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
# Check accessible names
|
||||||
|
expect_accessible_name('button.save', 'Save Document')
|
||||||
|
|
||||||
|
# Check all images have alt text
|
||||||
|
expect_images_have_alt_text
|
||||||
|
|
||||||
|
# Check form inputs are labeled
|
||||||
|
expect_form_inputs_labeled
|
||||||
|
|
||||||
|
# Check keyboard accessibility
|
||||||
|
expect_keyboard_accessible('button.custom')
|
||||||
|
|
||||||
|
# Check semantic landmarks
|
||||||
|
expect_semantic_landmarks
|
||||||
|
|
||||||
|
# Check buttons have names
|
||||||
|
expect_buttons_have_names
|
||||||
|
|
||||||
|
# Check error associations
|
||||||
|
expect_errors_associated_with_inputs('email_field', 'email_error')
|
||||||
|
|
||||||
|
# Check modal accessibility
|
||||||
|
expect_accessible_modal('#my-modal')
|
||||||
|
|
||||||
|
# Check focus trap
|
||||||
|
expect_focus_trap('#my-modal')
|
||||||
|
|
||||||
|
# Check skip navigation
|
||||||
|
expect_skip_navigation_link
|
||||||
|
```
|
||||||
|
|
||||||
|
## WCAG 2.2 Level AA Criteria
|
||||||
|
|
||||||
|
Our testing targets these success criteria:
|
||||||
|
|
||||||
|
### Level A
|
||||||
|
- **1.1.1** Non-text Content
|
||||||
|
- **1.3.1** Info and Relationships
|
||||||
|
- **2.1.1** Keyboard
|
||||||
|
- **2.1.2** No Keyboard Trap
|
||||||
|
- **2.4.1** Bypass Blocks
|
||||||
|
- **2.4.3** Focus Order
|
||||||
|
- **3.3.1** Error Identification
|
||||||
|
- **3.3.2** Labels or Instructions
|
||||||
|
- **4.1.2** Name, Role, Value
|
||||||
|
|
||||||
|
### Level AA
|
||||||
|
- **1.4.3** Contrast (Minimum)
|
||||||
|
- **2.4.6** Headings and Labels
|
||||||
|
- **2.4.7** Focus Visible
|
||||||
|
- **3.2.4** Consistent Identification
|
||||||
|
- **4.1.3** Status Messages
|
||||||
|
|
||||||
|
## Manual Testing
|
||||||
|
|
||||||
|
Automated tests catch most issues, but manual testing is required for:
|
||||||
|
|
||||||
|
### Screen Reader Testing
|
||||||
|
- **NVDA** (Windows) - Free, open-source
|
||||||
|
- **JAWS** (Windows) - Industry standard, paid
|
||||||
|
- **VoiceOver** (Mac/iOS) - Built-in
|
||||||
|
|
||||||
|
Test these flows:
|
||||||
|
1. Navigate the app with Tab/Shift+Tab only
|
||||||
|
2. Fill out and submit forms
|
||||||
|
3. Open and close modals
|
||||||
|
4. Upload files via file dropzone
|
||||||
|
5. Complete document signing flow
|
||||||
|
|
||||||
|
### Keyboard Navigation
|
||||||
|
Test all interactions with:
|
||||||
|
- **Tab** / **Shift+Tab** - Move focus
|
||||||
|
- **Enter** / **Space** - Activate buttons/links
|
||||||
|
- **Escape** - Close modals
|
||||||
|
- **Arrow keys** - Navigate lists/dropdowns
|
||||||
|
|
||||||
|
### Browser Zoom
|
||||||
|
- Test at 200% zoom level
|
||||||
|
- Verify no content is cut off
|
||||||
|
- Check mobile responsiveness
|
||||||
|
|
||||||
|
### Color Contrast
|
||||||
|
- Use browser DevTools color picker
|
||||||
|
- Verify 4.5:1 ratio for normal text
|
||||||
|
- Verify 3:1 ratio for large text (18pt+)
|
||||||
|
|
||||||
|
## Validation Tools
|
||||||
|
|
||||||
|
### Browser Extensions
|
||||||
|
- **axe DevTools** - Comprehensive WCAG auditing
|
||||||
|
- **WAVE** - Visual accessibility checker
|
||||||
|
- **Lighthouse** - Chrome DevTools built-in
|
||||||
|
|
||||||
|
### Command-Line Tools
|
||||||
|
```bash
|
||||||
|
# Run Lighthouse accessibility audit
|
||||||
|
lighthouse http://localhost:3000 --only-categories=accessibility
|
||||||
|
|
||||||
|
# Run axe-core via CLI
|
||||||
|
npx @axe-core/cli http://localhost:3000
|
||||||
|
```
|
||||||
|
|
||||||
|
## CI/CD Integration
|
||||||
|
|
||||||
|
Add to your CI pipeline:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# .github/workflows/accessibility.yml
|
||||||
|
name: Accessibility Tests
|
||||||
|
|
||||||
|
on: [push, pull_request]
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
a11y:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v3
|
||||||
|
- name: Run accessibility tests
|
||||||
|
run: |
|
||||||
|
bundle install
|
||||||
|
bundle exec rspec spec/accessibility/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Reporting Issues
|
||||||
|
|
||||||
|
When accessibility issues are found:
|
||||||
|
|
||||||
|
1. **Severity**: Critical, High, Medium, Low
|
||||||
|
2. **WCAG Criterion**: Which success criterion is violated
|
||||||
|
3. **User Impact**: Which disability groups are affected
|
||||||
|
4. **Location**: File path and line number
|
||||||
|
5. **Recommendation**: Specific fix with code example
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
- [WCAG 2.2 Guidelines](https://www.w3.org/WAI/WCAG22/quickref/)
|
||||||
|
- [axe-core Rules](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md)
|
||||||
|
- [A11Y Project Checklist](https://www.a11yproject.com/checklist/)
|
||||||
|
- [WebAIM Screen Reader Testing](https://webaim.org/articles/screenreader_testing/)
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
When adding new features:
|
||||||
|
1. Write accessibility tests alongside feature tests
|
||||||
|
2. Run axe-core audit on new pages/components
|
||||||
|
3. Test keyboard navigation manually
|
||||||
|
4. Verify with screen reader if possible
|
||||||
|
5. Document any accessibility considerations
|
||||||
@ -0,0 +1,86 @@
|
|||||||
|
# Accessibility Testing Setup Notes
|
||||||
|
|
||||||
|
## Gem Installation Required
|
||||||
|
|
||||||
|
The `axe-core-rspec` gem has been added to the Gemfile but requires installation.
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
This project requires **Ruby 4.0.1** (as specified in Gemfile).
|
||||||
|
|
||||||
|
Currently, the system Ruby is 2.6.10, which is incompatible. You'll need to:
|
||||||
|
|
||||||
|
1. **Install a Ruby version manager** (recommended: rbenv or asdf)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Using rbenv
|
||||||
|
brew install rbenv ruby-build
|
||||||
|
rbenv install 4.0.1
|
||||||
|
rbenv local 4.0.1
|
||||||
|
|
||||||
|
# Or using asdf
|
||||||
|
brew install asdf
|
||||||
|
asdf plugin add ruby
|
||||||
|
asdf install ruby 4.0.1
|
||||||
|
asdf local ruby 4.0.1
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Install dependencies**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bundle install
|
||||||
|
yarn install
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Run accessibility tests**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bundle exec rspec spec/accessibility/
|
||||||
|
```
|
||||||
|
|
||||||
|
## What's Been Set Up
|
||||||
|
|
||||||
|
✅ **Added to Gemfile (test group):**
|
||||||
|
- `axe-core-rspec` - Automated WCAG 2.2 validation
|
||||||
|
|
||||||
|
✅ **Created directory structure:**
|
||||||
|
- `spec/accessibility/` - Test files for a11y specs
|
||||||
|
- `spec/support/` - Helper modules
|
||||||
|
|
||||||
|
✅ **Created accessibility helpers:**
|
||||||
|
- `spec/support/accessibility_helpers.rb` - Custom test helpers for WCAG validation
|
||||||
|
- Methods for checking landmarks, labels, keyboard access, modals, etc.
|
||||||
|
|
||||||
|
✅ **Created documentation:**
|
||||||
|
- `spec/accessibility/README.md` - Comprehensive testing guide
|
||||||
|
- Covers running tests, manual testing, WCAG criteria, and resources
|
||||||
|
|
||||||
|
## Using axe-core-rspec
|
||||||
|
|
||||||
|
Once the gem is installed, you can use it in your tests:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
# spec/accessibility/wcag_compliance_spec.rb
|
||||||
|
RSpec.describe 'WCAG Compliance', type: :system do
|
||||||
|
it 'passes axe audit on home page' do
|
||||||
|
visit root_path
|
||||||
|
expect(page).to be_axe_clean
|
||||||
|
end
|
||||||
|
|
||||||
|
it 'passes WCAG 2.2 AA on submissions page' do
|
||||||
|
visit submissions_path
|
||||||
|
expect(page).to be_axe_clean.according_to(:wcag2aa, :wcag22aa)
|
||||||
|
end
|
||||||
|
|
||||||
|
it 'passes specific tag checks' do
|
||||||
|
visit template_path
|
||||||
|
expect(page).to be_axe_clean
|
||||||
|
.excluding('.legacy-component')
|
||||||
|
.according_to(:wcag2aa)
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
After bundle install completes, the testing infrastructure will be fully operational and ready for Phase 1 fixes.
|
||||||
@ -0,0 +1,142 @@
|
|||||||
|
# frozen_string_literal: true
|
||||||
|
|
||||||
|
# Accessibility testing helpers for WCAG 2.2 Level AA compliance
|
||||||
|
module AccessibilityHelpers
|
||||||
|
# Check if an element has proper ARIA label or text content
|
||||||
|
def expect_accessible_name(selector, expected_name = nil)
|
||||||
|
element = page.find(selector)
|
||||||
|
|
||||||
|
# Check for accessible name via aria-label, aria-labelledby, or text content
|
||||||
|
accessible_name = element['aria-label'] ||
|
||||||
|
find_aria_labelledby_text(element) ||
|
||||||
|
element.text.strip
|
||||||
|
|
||||||
|
if expected_name
|
||||||
|
expect(accessible_name).to eq(expected_name)
|
||||||
|
else
|
||||||
|
expect(accessible_name).not_to be_empty
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
# Check if images have alt text
|
||||||
|
def expect_images_have_alt_text
|
||||||
|
images_without_alt = page.all('img:not([alt])')
|
||||||
|
expect(images_without_alt).to be_empty,
|
||||||
|
"Found #{images_without_alt.count} images without alt attributes"
|
||||||
|
end
|
||||||
|
|
||||||
|
# Check if form inputs have associated labels or aria-label
|
||||||
|
def expect_form_inputs_labeled
|
||||||
|
unlabeled_inputs = page.all('input, select, textarea').select do |input|
|
||||||
|
next if input['type'] == 'hidden'
|
||||||
|
next if input['type'] == 'submit'
|
||||||
|
next if input['type'] == 'button'
|
||||||
|
|
||||||
|
# Check for label association, aria-label, or aria-labelledby
|
||||||
|
has_label = input['id'] && page.has_css?("label[for='#{input['id']}']")
|
||||||
|
has_aria = input['aria-label'] || input['aria-labelledby']
|
||||||
|
|
||||||
|
!has_label && !has_aria
|
||||||
|
end
|
||||||
|
|
||||||
|
expect(unlabeled_inputs).to be_empty,
|
||||||
|
"Found #{unlabeled_inputs.count} unlabeled form inputs"
|
||||||
|
end
|
||||||
|
|
||||||
|
# Check if interactive elements are keyboard accessible
|
||||||
|
def expect_keyboard_accessible(selector)
|
||||||
|
element = page.find(selector)
|
||||||
|
|
||||||
|
# Interactive elements should be focusable
|
||||||
|
expect(element['tabindex'].to_i).to be >= 0
|
||||||
|
end
|
||||||
|
|
||||||
|
# Check for proper semantic landmarks
|
||||||
|
def expect_semantic_landmarks
|
||||||
|
expect(page).to have_css('main, [role="main"]'),
|
||||||
|
'Page should have a main landmark'
|
||||||
|
expect(page).to have_css('nav, [role="navigation"]'),
|
||||||
|
'Page should have a navigation landmark'
|
||||||
|
end
|
||||||
|
|
||||||
|
# Check if buttons have accessible names
|
||||||
|
def expect_buttons_have_names
|
||||||
|
unnamed_buttons = page.all('button').select do |button|
|
||||||
|
text = button.text.strip
|
||||||
|
aria_label = button['aria-label']
|
||||||
|
aria_labelledby = button['aria-labelledby']
|
||||||
|
|
||||||
|
text.empty? && !aria_label && !aria_labelledby
|
||||||
|
end
|
||||||
|
|
||||||
|
expect(unnamed_buttons).to be_empty,
|
||||||
|
"Found #{unnamed_buttons.count} buttons without accessible names"
|
||||||
|
end
|
||||||
|
|
||||||
|
# Check color contrast ratio (simplified check for common patterns)
|
||||||
|
def expect_sufficient_contrast(selector)
|
||||||
|
element = page.find(selector)
|
||||||
|
computed_style = page.evaluate_script(
|
||||||
|
"window.getComputedStyle(document.querySelector('#{selector}'))"
|
||||||
|
)
|
||||||
|
|
||||||
|
# This is a basic check - proper contrast testing requires color parsing
|
||||||
|
color = computed_style['color']
|
||||||
|
background = computed_style['background-color']
|
||||||
|
|
||||||
|
expect(color).not_to eq('rgb(209, 213, 219)'), # text-gray-300
|
||||||
|
'Text color has insufficient contrast'
|
||||||
|
end
|
||||||
|
|
||||||
|
# Check if error messages are associated with form fields
|
||||||
|
def expect_errors_associated_with_inputs(input_id, error_id)
|
||||||
|
input = page.find("##{input_id}")
|
||||||
|
expect(input['aria-describedby']).to include(error_id),
|
||||||
|
"Input ##{input_id} should reference error ##{error_id} via aria-describedby"
|
||||||
|
|
||||||
|
# Error should be announced to screen readers
|
||||||
|
error_element = page.find("##{error_id}")
|
||||||
|
expect(error_element['role']).to eq('alert').or eq(nil)
|
||||||
|
end
|
||||||
|
|
||||||
|
# Check if modal dialogs are properly configured
|
||||||
|
def expect_accessible_modal(selector)
|
||||||
|
modal = page.find(selector)
|
||||||
|
|
||||||
|
expect(modal['role']).to eq('dialog'),
|
||||||
|
'Modal should have role="dialog"'
|
||||||
|
expect(modal['aria-modal']).to eq('true'),
|
||||||
|
'Modal should have aria-modal="true"'
|
||||||
|
expect(modal['aria-labelledby']).not_to be_nil,
|
||||||
|
'Modal should have aria-labelledby referencing its title'
|
||||||
|
end
|
||||||
|
|
||||||
|
# Check if focus is trapped within modal
|
||||||
|
def expect_focus_trap(modal_selector)
|
||||||
|
within(modal_selector) do
|
||||||
|
focusable = page.all('a[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])')
|
||||||
|
expect(focusable.count).to be > 0, 'Modal should contain focusable elements'
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
# Check for skip navigation link
|
||||||
|
def expect_skip_navigation_link
|
||||||
|
expect(page).to have_css('a[href="#main-content"], a[href="#main"]'),
|
||||||
|
'Page should have a skip navigation link'
|
||||||
|
end
|
||||||
|
|
||||||
|
private
|
||||||
|
|
||||||
|
def find_aria_labelledby_text(element)
|
||||||
|
labelledby_id = element['aria-labelledby']
|
||||||
|
return nil unless labelledby_id
|
||||||
|
|
||||||
|
label_element = page.find("##{labelledby_id}", visible: false)
|
||||||
|
label_element&.text&.strip
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
# Include helpers in system specs
|
||||||
|
RSpec.configure do |config|
|
||||||
|
config.include AccessibilityHelpers, type: :system
|
||||||
|
end
|
||||||
Loading…
Reference in new issue