Rails Accessibility Testing

The RSpec + RuboCop of accessibility for Rails

Rails Accessibility Testing

The RSpec + RuboCop of accessibility for Rails. Catch WCAG violations before they reach production.

Version: 1.5.5

Rails Accessibility Testing is a comprehensive, opinionated but configurable gem that makes accessibility testing as natural as unit testing. It integrates seamlessly into your Rails workflow, catching accessibility issues as you code—not after deployment.

🎯 Positioning

Rails Accessibility Testing fills a critical gap in the Rails testing ecosystem. While RSpec ensures code works and RuboCop ensures code style, Rails Accessibility Testing ensures applications are accessible to everyone. Unlike manual accessibility audits that happen late in development, Rails Accessibility Testing integrates directly into your test suite, catching violations as you code. It’s opinionated enough to guide teams new to accessibility, yet configurable enough for experienced teams. By making accessibility testing as natural as unit testing, Rails Accessibility Testing helps teams build accessible applications from day one, not as an afterthought.

✨ Features

Core Capabilities

🆕 Version 1.5.0+ Highlights

🔍 Static File Scanner (NEW)

🎯 Live Accessibility Scanner

📝 Enhanced Error Reporting

🚀 Quick Start

Installation

Add to your Gemfile:

group :development, :test do
  gem 'rails_accessibility_testing'
  gem 'rspec-rails', '~> 8.0'  # Required for system specs
  gem 'axe-core-capybara', '~> 4.0'
  gem 'capybara', '~> 3.40'
  gem 'selenium-webdriver', '~> 4.0'
  gem 'webdrivers', '~> 5.0'  # Optional but recommended
  gem 'csv'  # Required for Ruby 3.3+ (CSV removed from standard library in Ruby 3.4)
end

Important: You must explicitly add selenium-webdriver and csv (for Ruby 3.3+) to your Gemfile. The gem has minimal dependencies - you control your own driver setup.

Then run:

bundle install

Setup (Option 1: Generator - Recommended)

rails generate rails_a11y:install

This creates:

📖 Usage

System specs are the recommended and most reliable way to run accessibility checks. They’re faster, more reliable, and integrate seamlessly with your test suite.

Create system specs for your pages:

# spec/system/home_page_accessibility_spec.rb
require 'rails_helper'

RSpec.describe 'Home Page Accessibility', type: :system do
  it 'loads successfully and passes comprehensive accessibility checks' do
    visit root_path
    expect(page).to have_content('Welcome')
    
    # Run comprehensive accessibility checks
    check_comprehensive_accessibility
    # ✅ Comprehensive accessibility checks (11 checks) also run automatically after this test!
  end
end

Accessibility checks run automatically after each visit in system specs!

Continuous Development Testing

The generator automatically adds a static accessibility scanner to your Procfile.dev:

web: bin/rails server
css: bin/rails dartsass:watch
a11y: bundle exec a11y_static_scanner

Then run:

bin/dev

This will:

🎯 What Gets Checked

The gem automatically runs 11 comprehensive accessibility checks:

  1. ✅ Form Labels - All form inputs have associated labels
  2. ✅ Image Alt Text - All images have descriptive alt attributes
  3. ✅ Interactive Elements - Buttons, links have accessible names (including links with images that have alt text)
  4. ✅ Heading Hierarchy - Proper h1-h6 structure (detects missing h1, multiple h1s, skipped levels, and h2+ without h1)
  5. ✅ Keyboard Accessibility - All interactive elements keyboard accessible
  6. ✅ ARIA Landmarks - Proper use of ARIA landmark roles
  7. ✅ Form Error Associations - Errors linked to form fields
  8. ✅ Table Structure - Tables have proper headers
  9. ✅ Duplicate IDs - No duplicate ID attributes
  10. ✅ Skip Links - Skip navigation links present (detects various patterns)
  11. ✅ Color Contrast - Text meets contrast requirements (optional)

📚 Documentation

Additional Guides

📞 Support

Made with ❤️ for accessible Rails applications

Rails Accessibility Testing helps teams build accessible applications from day one, not as an afterthought.