rails_accessibility_testing 1.4.1 → 1.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdfb13e559e3d6d786ac41d4027b1b89272b5595d2bc6b9324db3ee6082a8d90
-  data.tar.gz: b8b3420d7ba19cb20bb2a6b3601196e996e5e372aab780ec3de0a6ae7b44f22d
+  metadata.gz: c4df6f6fa98287499a91edd38be1b081a97c3ec3ce09fade45192afe3aad7e27
+  data.tar.gz: 412a2a707455699628ab59d64c0ed3f7607c143fbdbfb7d0d70dae80bad84c8c
 SHA512:
-  metadata.gz: c2abe639249eca589eb405aeb0432b7fa57c45214c8de1b044c4fc1a5118c229ae16d90d04b7368ed3430830400ae77ef7a3848623edb587ec222a28b50f9376
-  data.tar.gz: ddc8a6f229e2038c080d923f0c9d25a21949543e581c8131b23c7e3536ffb633a9ee0ad855dce7d2bd2e9482a959a07f7171e021e08a7c5f5d831f0fb0994d1d
+  metadata.gz: c6b0639e08a27ee874ff9fb98123f36cf429a6fcd98615beb6a17682da9a24adeb027305af4713a05cee02640d4f3d0b375245a4b55fdc03020a277a4c608f92
+  data.tar.gz: df40a9a2df569f6e49a41bc3d90812c897a827a981bc555c25dec824422aac25676b53689b323d29eaa7b6a3fa046e903cb2e510148cbaf0b4bc6797deed2c91

data/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.3] - 2025-11-19
+
+### Added
+- Comprehensive driver setup documentation for Capybara and Selenium WebDriver
+- Explicit `selenium-webdriver` gem requirement in all Gemfile examples
+- Chrome/Chromium installation instructions for macOS, Linux, and Windows
+- Troubleshooting section covering common errors including `DriverFinder` issues
+- Version compatibility table with recommended and minimum versions
+- Rails 8 specific setup notes and requirements
+
+### Improved
+- Enhanced getting started guides with complete driver configuration examples
+- Better documentation for Rails 8 compatibility and `driven_by` method usage
+- Clearer instructions for resolving `uninitialized constant Selenium::WebDriver::DriverFinder` errors
+- More comprehensive setup instructions covering all required dependencies
+
+## [1.4.2] - 2025-11-18
+
+### Added
+- Procfile.dev documentation for continuous accessibility checking during development
+- Instructions for running accessibility checks automatically every 30 seconds via `bin/dev`
+- Updated getting started guides with Procfile setup examples
+- Enhanced README with continuous testing workflow documentation
+
+### Improved
+- Better developer experience with continuous accessibility feedback during development
+- Clearer documentation on multiple ways to run accessibility checks (manual vs continuous)
+- Improved onboarding with step-by-step Procfile setup instructions
+
 ## [1.4.1] - 2025-11-18
 
 ### Changed
@@ -155,6 +184,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Compatible with RSpec Rails 6.0+
 - Modular architecture with rule engine and check definitions
 
+[1.4.3]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.4.3
+[1.4.2]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.4.2
 [1.4.1]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.4.1
 [1.4.0]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.4.0
 [1.3.0]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.3.0

data/GUIDES/getting_started.md

@@ -16,9 +16,14 @@ Add to your `Gemfile`:
 group :development, :test do
   gem 'rails_accessibility_testing'
   gem 'axe-core-capybara', '~> 4.0'
+  gem 'capybara', '~> 3.40'
+  gem 'selenium-webdriver', '~> 4.0'
+  gem 'webdrivers', '~> 5.0'  # Optional but recommended for automatic driver management
 end
 ```
 
+**Important:** You must explicitly add `selenium-webdriver` to your Gemfile. It's not automatically included as a dependency.
+
 Then run:
 
 ```bash
@@ -38,9 +43,72 @@ This creates:
 - `config/accessibility.yml` - Check settings
 - Updates `spec/rails_helper.rb` (if using RSpec)
 
-### Step 3: Run Your Tests
+### Step 2.5: Configure Capybara Driver (Required for System Tests)
+
+For system tests to work, you need to configure Capybara with a Selenium driver. Create `spec/support/driver.rb`:
+
+```ruby
+# spec/support/driver.rb
+require 'selenium-webdriver'
+require 'capybara/rails'
+require 'capybara/rspec'
+
+# Configure Chrome options
+browser_options = Selenium::WebDriver::Chrome::Options.new
+browser_options.add_argument('--window-size=1920,1080')
+browser_options.add_argument('--headless') unless ENV['SHOW_TEST_BROWSER']
+
+# Register the driver
+Capybara.register_driver :selenium_chrome_headless do |app|
+  Capybara::Selenium::Driver.new(
+    app,
+    browser: :chrome,
+    options: browser_options
+  )
+end
+
+# Set as default JavaScript driver
+Capybara.javascript_driver = :selenium_chrome_headless
+
+# Configure RSpec to use the driver for system tests
+RSpec.configure do |config|
+  config.before(:each, type: :system) do
+    driven_by :selenium_chrome_headless
+  end
+end
+```
+
+**Note for Rails 8:** Rails 8 uses `driven_by` to configure system tests. Make sure your `spec/support/driver.rb` is loaded by `rails_helper.rb` (it should be automatically loaded if it's in the `spec/support/` directory).
+
+### Step 3: Install Chrome/Chromium (Required)
+
+System tests require Chrome or Chromium to be installed on your system:
+
+**macOS:**
+```bash
+brew install --cask google-chrome
+# or for Chromium:
+brew install --cask chromium
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt-get update
+sudo apt-get install -y google-chrome-stable
+# or for Chromium:
+sudo apt-get install -y chromium-browser
+```
+
+**Windows:**
+Download and install Chrome from [google.com/chrome](https://www.google.com/chrome/)
+
+The `webdrivers` gem will automatically download and manage the ChromeDriver binary for you.
 
-That's it! Just run your system specs:
+### Step 4: Run Your Tests
+
+You can run accessibility checks in several ways:
+
+#### Option A: Run Tests Manually
 
 ```bash
 bundle exec rspec spec/system/
@@ -48,6 +116,29 @@ bundle exec rspec spec/system/
 
 Accessibility checks run automatically on every system test that visits a page.
 
+#### Option B: Run Continuously with Procfile (Recommended for Development)
+
+For continuous accessibility checking during development, add to your `Procfile.dev`:
+
+```procfile
+web: bin/rails server
+css: bin/rails dartsass:watch
+a11y: while true; do bundle exec rspec spec/system/*_accessibility_spec.rb; sleep 30; done
+```
+
+Then run:
+
+```bash
+bin/dev
+```
+
+This will:
+- Start your Rails server
+- Watch for CSS changes
+- **Automatically run accessibility checks every 30 seconds** on all `*_accessibility_spec.rb` files
+
+The accessibility checker will continuously monitor your pages and alert you to any issues as you develop!
+
 ## Your First Accessibility Check
 
 Let's see it in action. Create a simple system spec:
@@ -225,6 +316,74 @@ end
 - **Check out [Writing Accessible Views](writing_accessible_views_in_rails.md)** for best practices
 - **See [Working with Designers](working_with_designers_and_content_authors.md)** for team collaboration
 
+## Troubleshooting
+
+### Error: `uninitialized constant Selenium::WebDriver::DriverFinder`
+
+This error typically occurs when:
+1. **Missing selenium-webdriver gem** - Make sure you've added `gem 'selenium-webdriver', '~> 4.0'` to your Gemfile
+2. **Version incompatibility** - Ensure you're using compatible versions:
+   - `selenium-webdriver` ~> 4.0 (4.6.0+ recommended for Rails 8)
+   - `webdrivers` ~> 5.0 (if using webdrivers)
+   - `capybara` ~> 3.40
+
+**Solution:**
+```bash
+# Update your Gemfile
+gem 'selenium-webdriver', '~> 4.10'
+gem 'webdrivers', '~> 5.3'
+gem 'capybara', '~> 3.40'
+
+# Then run
+bundle update selenium-webdriver webdrivers capybara
+```
+
+### Error: Chrome/ChromeDriver not found
+
+**Solution:**
+1. Make sure Chrome is installed (see Step 3 above)
+2. If using `webdrivers` gem, it should auto-download ChromeDriver. If not:
+   ```bash
+   bundle exec webdrivers chrome
+   ```
+3. For manual installation, download from [ChromeDriver downloads](https://chromedriver.chromium.org/downloads)
+
+### System tests not running
+
+**Check:**
+1. Your spec has `type: :system` metadata
+2. `spec/support/driver.rb` exists and is properly configured
+3. `spec/rails_helper.rb` loads support files (should be automatic)
+4. Chrome is installed and accessible
+
+### Tests are slow
+
+Disable expensive checks in development:
+```yaml
+# config/accessibility.yml
+development:
+  checks:
+    color_contrast: false  # Disable expensive color contrast checks
+```
+
+## Version Compatibility
+
+For best results, use these compatible versions:
+
+| Component | Recommended Version | Minimum Version |
+|-----------|-------------------|-----------------|
+| Ruby | 3.1+ | 3.0+ |
+| Rails | 7.1+ / 8.0+ | 6.0+ |
+| RSpec Rails | 6.0+ | 5.0+ |
+| Capybara | ~> 3.40 | 3.0+ |
+| selenium-webdriver | ~> 4.10 | 4.0+ |
+| webdrivers | ~> 5.3 | 5.0+ |
+
+**Rails 8 Notes:**
+- Rails 8 requires `selenium-webdriver` 4.6.0+ for `DriverFinder` support
+- Make sure your `driven_by` configuration is in `spec/support/driver.rb`
+- Rails 8 system tests use `driven_by` instead of direct Capybara configuration
+
 ## Common Questions
 
 ### Q: Do I need to change my existing tests?
@@ -246,8 +405,8 @@ end
 ## Getting Help
 
 - **Documentation:** See the main [README](../README.md)
-- **Issues:** [GitHub Issues](https://github.com/your-org/rails-a11y/issues)
-- **Email:** support@example.com
+- **Issues:** [GitHub Issues](https://github.com/rayraycodes/rails-accessibility-testing/issues)
+- **Email:** imregan@umich.edu
 
 ---
 

data/README.md

@@ -7,7 +7,7 @@
 
 **The RSpec + RuboCop of accessibility for Rails. Catch WCAG violations before they reach production.**
 
-**Current Version:** 1.4.1
+**Current Version:** 1.4.3
 
 📖 **[📚 Full Documentation](https://rayraycodes.github.io/rails-accessibility-testing/)** | [💻 GitHub](https://github.com/rayraycodes/rails-accessibility-testing) | [💎 RubyGems](https://rubygems.org/gems/rails_accessibility_testing)
 
@@ -40,11 +40,14 @@ Add to your `Gemfile`:
 group :development, :test do
   gem 'rails_accessibility_testing'
   gem 'axe-core-capybara', '~> 4.0'
-  # Your existing Capybara, selenium-webdriver, webdrivers gems
-  # The gem has minimal dependencies - you control your own driver setup
+  gem 'capybara', '~> 3.40'
+  gem 'selenium-webdriver', '~> 4.0'
+  gem 'webdrivers', '~> 5.0'  # Optional but recommended for automatic driver management
 end
 ```
 
+**Important:** You must explicitly add `selenium-webdriver` to your Gemfile. It's not automatically included as a dependency. The gem has minimal dependencies - you control your own driver setup.
+
 Then run:
 
 ```bash
@@ -108,12 +111,24 @@ end
 
 **Accessibility checks run automatically after each `visit` in system specs!**
 
-For continuous testing during development, add to your `Procfile.dev`:
+#### Continuous Testing with Procfile (Recommended for Development)
 
-```ruby
+For continuous accessibility checking during development, add to your `Procfile.dev`:
+
+```procfile
+web: bin/rails server
+css: bin/rails dartsass:watch
 a11y: while true; do bundle exec rspec spec/system/*_accessibility_spec.rb; sleep 30; done
 ```
 
+Then run:
+
+```bash
+bin/dev
+```
+
+This will automatically run accessibility checks every 30 seconds on all `*_accessibility_spec.rb` files, giving you continuous feedback as you develop!
+
 📖 **[See the full System Specs Guide](GUIDES/system_specs_for_accessibility.md)** for detailed examples and best practices.
 
 ### Automatic Checks

data/docs_site/getting_started.md

@@ -21,9 +21,14 @@ Add to your `Gemfile`:
 group :development, :test do
   gem 'rails_accessibility_testing'
   gem 'axe-core-capybara', '~> 4.0'
+  gem 'capybara', '~> 3.40'
+  gem 'selenium-webdriver', '~> 4.0'
+  gem 'webdrivers', '~> 5.0'  # Optional but recommended for automatic driver management
 end
 ```
 
+**Important:** You must explicitly add `selenium-webdriver` to your Gemfile. It's not automatically included as a dependency.
+
 Then run:
 
 ```bash
@@ -43,9 +48,92 @@ This creates:
 - `config/accessibility.yml` - Check settings
 - Updates `spec/rails_helper.rb` (if using RSpec)
 
-### Step 3: Run Your Tests
+### Step 2.5: Configure Capybara Driver (Required for System Tests)
+
+For system tests to work, you need to configure Capybara with a Selenium driver. Create `spec/support/driver.rb`:
+
+```ruby
+# spec/support/driver.rb
+require 'selenium-webdriver'
+require 'capybara/rails'
+require 'capybara/rspec'
+
+# Configure Chrome options
+browser_options = Selenium::WebDriver::Chrome::Options.new
+browser_options.add_argument('--window-size=1920,1080')
+browser_options.add_argument('--headless') unless ENV['SHOW_TEST_BROWSER']
+
+# Register the driver
+Capybara.register_driver :selenium_chrome_headless do |app|
+  Capybara::Selenium::Driver.new(
+    app,
+    browser: :chrome,
+    options: browser_options
+  )
+end
+
+# Set as default JavaScript driver
+Capybara.javascript_driver = :selenium_chrome_headless
 
-That's it! Just run your system specs:
+# Configure RSpec to use the driver for system tests
+RSpec.configure do |config|
+  config.before(:each, type: :system) do
+    driven_by :selenium_chrome_headless
+  end
+end
+```
+
+**Note for Rails 8:** Rails 8 uses `driven_by` to configure system tests. Make sure your `spec/support/driver.rb` is loaded by `rails_helper.rb` (it should be automatically loaded if it's in the `spec/support/` directory).
+
+### Step 3: Install Chrome/Chromium (Required)
+
+System tests require Chrome or Chromium to be installed on your system:
+
+**macOS:**
+```bash
+brew install --cask google-chrome
+# or for Chromium:
+brew install --cask chromium
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt-get update
+sudo apt-get install -y google-chrome-stable
+# or for Chromium:
+sudo apt-get install -y chromium-browser
+```
+
+**Windows:**
+Download and install Chrome from [google.com/chrome](https://www.google.com/chrome/)
+
+The `webdrivers` gem will automatically download and manage the ChromeDriver binary for you.
+
+### Step 4: Create System Specs (Recommended)
+
+Create system specs for the pages you want to test. This is the **recommended and most reliable** approach:
+
+```ruby
+# spec/system/home_page_accessibility_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Home Page Accessibility', type: :system do
+  it 'loads the page and runs comprehensive accessibility checks' do
+    visit root_path
+    
+    # Run comprehensive accessibility checks
+    # This will fail the test if any accessibility issues are found
+    check_comprehensive_accessibility
+    # ✅ If all checks pass, you'll see: "All comprehensive accessibility checks passed! (11 checks)"
+  end
+end
+```
+
+### Step 5: Run Your Tests
+
+You can run accessibility checks in several ways:
+
+#### Option A: Run Tests Manually
 
 ```bash
 bundle exec rspec spec/system/
@@ -53,5 +141,99 @@ bundle exec rspec spec/system/
 
 Accessibility checks run automatically on every system test that visits a page.
 
-For complete documentation, see the [Getting Started guide](https://github.com/rayraycodes/rails-accessibility-testing/blob/main/GUIDES/getting_started.md) in the main repository.
+#### Option B: Run Continuously with Procfile (Recommended for Development)
+
+For continuous accessibility checking during development, add to your `Procfile.dev`:
+
+```procfile
+web: bin/rails server
+css: bin/rails dartsass:watch
+a11y: while true; do bundle exec rspec spec/system/*_accessibility_spec.rb; sleep 30; done
+```
+
+Then run:
+
+```bash
+bin/dev
+```
+
+This will:
+- Start your Rails server
+- Watch for CSS changes
+- **Automatically run accessibility checks every 30 seconds** on all `*_accessibility_spec.rb` files
+
+The accessibility checker will continuously monitor your pages and alert you to any issues as you develop!
+
+## Troubleshooting
+
+### Error: `uninitialized constant Selenium::WebDriver::DriverFinder`
+
+This error typically occurs when:
+1. **Missing selenium-webdriver gem** - Make sure you've added `gem 'selenium-webdriver', '~> 4.0'` to your Gemfile
+2. **Version incompatibility** - Ensure you're using compatible versions:
+   - `selenium-webdriver` ~> 4.0 (4.6.0+ recommended for Rails 8)
+   - `webdrivers` ~> 5.0 (if using webdrivers)
+   - `capybara` ~> 3.40
+
+**Solution:**
+```bash
+# Update your Gemfile
+gem 'selenium-webdriver', '~> 4.10'
+gem 'webdrivers', '~> 5.3'
+gem 'capybara', '~> 3.40'
+
+# Then run
+bundle update selenium-webdriver webdrivers capybara
+```
+
+### Error: Chrome/ChromeDriver not found
+
+**Solution:**
+1. Make sure Chrome is installed (see Step 2.5 above)
+2. If using `webdrivers` gem, it should auto-download ChromeDriver. If not:
+   ```bash
+   bundle exec webdrivers chrome
+   ```
+3. For manual installation, download from [ChromeDriver downloads](https://chromedriver.chromium.org/downloads)
+
+### System tests not running
+
+**Check:**
+1. Your spec has `type: :system` metadata
+2. `spec/support/driver.rb` exists and is properly configured
+3. `spec/rails_helper.rb` loads support files (should be automatic)
+4. Chrome is installed and accessible
+
+### Tests are slow
+
+Disable expensive checks in development:
+```yaml
+# config/accessibility.yml
+development:
+  checks:
+    color_contrast: false  # Disable expensive color contrast checks
+```
+
+## Version Compatibility
+
+For best results, use these compatible versions:
+
+| Component | Recommended Version | Minimum Version |
+|-----------|-------------------|-----------------|
+| Ruby | 3.1+ | 3.0+ |
+| Rails | 7.1+ / 8.0+ | 6.0+ |
+| RSpec Rails | 6.0+ | 5.0+ |
+| Capybara | ~> 3.40 | 3.0+ |
+| selenium-webdriver | ~> 4.10 | 4.0+ |
+| webdrivers | ~> 5.3 | 5.0+ |
+
+**Rails 8 Notes:**
+- Rails 8 requires `selenium-webdriver` 4.6.0+ for `DriverFinder` support
+- Make sure your `driven_by` configuration is in `spec/support/driver.rb`
+- Rails 8 system tests use `driven_by` instead of direct Capybara configuration
+
+## Learn More
+
+- **[System Specs Guide](https://github.com/rayraycodes/rails-accessibility-testing/blob/main/GUIDES/system_specs_for_accessibility.md)** - ⭐ Recommended approach for reliable accessibility testing
+- **[Complete Getting Started Guide](https://github.com/rayraycodes/rails-accessibility-testing/blob/main/GUIDES/getting_started.md)** - Detailed setup instructions
 

data/docs_site/index.md

@@ -7,7 +7,7 @@ title: Home
 
 **The RSpec + RuboCop of accessibility for Rails. Catch WCAG violations before they reach production.**
 
-**Version:** 1.1.0
+**Version:** 1.4.3
 
 Rails Accessibility Testing is a comprehensive accessibility testing gem that makes accessibility testing as natural as unit testing. It integrates seamlessly into your Rails workflow, catching WCAG 2.1 AA violations as you code—not after deployment.
 
@@ -48,6 +48,12 @@ bundle exec rspec spec/system/
 - [CI Integration]({{ '/ci_integration.html' | relative_url }}) - CI/CD setup
 - [Contributing]({{ '/contributing.html' | relative_url }}) - How to contribute
 
+## Additional Guides
+
+- [System Specs for Accessibility](https://github.com/rayraycodes/rails-accessibility-testing/blob/main/GUIDES/system_specs_for_accessibility.md) - ⭐ Recommended approach
+- [Writing Accessible Views](https://github.com/rayraycodes/rails-accessibility-testing/blob/main/GUIDES/writing_accessible_views_in_rails.md) - Best practices
+- [Working with Designers](https://github.com/rayraycodes/rails-accessibility-testing/blob/main/GUIDES/working_with_designers_and_content_authors.md) - Team collaboration
+
 ## Links
 
 - [GitHub Repository](https://github.com/rayraycodes/rails-accessibility-testing)

data/lib/rails_accessibility_testing/version.rb

@@ -1,4 +1,4 @@
 module RailsAccessibilityTesting
-  VERSION = "1.4.1"
+  VERSION = "1.4.3"
 end
 

data/lib/rails_accessibility_testing.rb

@@ -5,7 +5,7 @@
 # Automatically configures accessibility testing for Rails system specs with
 # comprehensive checks and detailed error messages.
 #
-# @version 1.4.1
+# @version 1.4.3
 # @author Regan Maharjan
 #
 # @example Basic usage
@@ -38,7 +38,7 @@ begin
   require_relative 'rails_accessibility_testing/version'
 rescue LoadError
   module RailsAccessibilityTesting
-    VERSION = '1.4.1'
+    VERSION = '1.4.3'
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_accessibility_testing
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.4.3
 platform: ruby
 authors:
 - Regan Maharjan
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-11-18 00:00:00.000000000 Z
+date: 2025-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: axe-core-capybara