rails_accessibility_testing 1.4.2 → 1.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a60633c05618ff8bc3fa720655c2a954675aa9a7ab5fdc3b515f18f937481ec
-  data.tar.gz: e15e7a3238221d4ae21ed60bf451818fbc94bca45ea6af4c0f9675309125ab63
+  metadata.gz: c4df6f6fa98287499a91edd38be1b081a97c3ec3ce09fade45192afe3aad7e27
+  data.tar.gz: 412a2a707455699628ab59d64c0ed3f7607c143fbdbfb7d0d70dae80bad84c8c
 SHA512:
-  metadata.gz: ff0b0cfc0c3f51b2bf022ffa97bfeab3c50da7cd0c3afb024d0ab8043f9cf599df8bb76f6cf8d3c97127a352e7050b5309819eac6b91030c5ea73a2e5d01c6ac
-  data.tar.gz: 9debe7aa2879d009108cbb801e158fc12e8c12e592f69c76e2a603c3fd8db4ad72b8e322d15e5d0987dbcb4e6b4f146e24edb5bd3cc1c4b241a5f0659e548cfb
+  metadata.gz: c6b0639e08a27ee874ff9fb98123f36cf429a6fcd98615beb6a17682da9a24adeb027305af4713a05cee02640d4f3d0b375245a4b55fdc03020a277a4c608f92
+  data.tar.gz: df40a9a2df569f6e49a41bc3d90812c897a827a981bc555c25dec824422aac25676b53689b323d29eaa7b6a3fa046e903cb2e510148cbaf0b4bc6797deed2c91

data/CHANGELOG.md

@@ -5,6 +5,22 @@ 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
@@ -168,6 +184,7 @@ 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

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,7 +43,68 @@ 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.
+
+### Step 4: Run Your Tests
 
 You can run accessibility checks in several ways:
 
@@ -250,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?
@@ -271,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.2
+**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

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,7 +48,68 @@ This creates:
 - `config/accessibility.yml` - Check settings
 - Updates `spec/rails_helper.rb` (if using RSpec)
 
-### Step 3: Create System Specs (Recommended)
+### 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.
+
+### Step 4: Create System Specs (Recommended)
 
 Create system specs for the pages you want to test. This is the **recommended and most reliable** approach:
 
@@ -63,7 +129,7 @@ RSpec.describe 'Home Page Accessibility', type: :system do
 end
 ```
 
-### Step 4: Run Your Tests
+### Step 5: Run Your Tests
 
 You can run accessibility checks in several ways:
 
@@ -98,6 +164,74 @@ This will:
 
 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

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.4.2
+**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.
 

data/lib/rails_accessibility_testing/version.rb

@@ -1,4 +1,4 @@
 module RailsAccessibilityTesting
-  VERSION = "1.4.2"
+  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.2
+# @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.2'
+    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.2
+  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