rails_accessibility_testing 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7f693b05664c88f5b08e1917caa94ad360754d3113787d89c8d7b59331c1b55
-  data.tar.gz: 29bfe1bfa996b04d9f779c4d576c9a2b799a041ecc52d0d35c94b1cefb9b2f0a
+  metadata.gz: 5ed11e69796995b294eeaa17e2627e46b3122356d7383e2e1ad3b213c8f2ac78
+  data.tar.gz: 410f9e2c88b5e27e0a6319fb62bb854d832f8e74a25d7b3970aaf9b3f07a0fe5
 SHA512:
-  metadata.gz: b525904eca4df9bf87d32fed9b27587681a45cfb73ae4f630ba8700929fa763fef316940e0b246c84eb2d7216b3def1df82e99d6375c859760d72f34e05ac1fa
-  data.tar.gz: 750912a05ec0b37f24bdb2011052f140c827940ec1063f6beaf1d5974708e386d21399808ecc3133ed7899f4ba7202638292f20950de953dca9508f0a275af70
+  metadata.gz: b3c309bbcc50838e5a981cf997c74051e10a79ce0b03d67450ad3e0dac8486d6ed79cfad4cd201e2cd25abf432370d80799a67ca9f136e11e2c055724e5f9dee
+  data.tar.gz: d8f2aaaad2e708e83dc4c9f7fd283ec815904557549f33c2f4b491fdeeed6c196b55c759b79effe7074bfda21cb4e3d07ccdefedcf07e065cdf4302f4395b74d

data/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.0] - 2025-11-18
+
+### Changed
+- Updated documentation examples to use clearer language ("runs accessibility checks" instead of "passes accessibility checks")
+- Improved test descriptions to accurately reflect that tests will fail if accessibility issues are found
+- Enhanced comments in examples to clarify when success messages appear
+
+### Improved
+- Better clarity in documentation about when accessibility checks pass vs fail
+- More accurate test descriptions that don't imply tests will pass when they may fail
+- Improved user understanding of accessibility check behavior
+
+## [1.3.0] - 2025-11-18
+
+### Added
+- CLI reports now use ErrorMessageBuilder for detailed, formatted error messages
+- CLI reports include comprehensive remediation steps, element details, and WCAG references
+- Better empty alt text detection (checks both Capybara attributes and JavaScript getAttribute)
+- Improved server port detection with better error handling and timeout management
+
+### Changed
+- CLI default profile changed to `:development` for faster checks (color contrast disabled by default)
+- Improved server wait logic with longer retry times (up to 20 seconds) and better port re-detection
+- Report generation now skips when no URLs are checked (cleaner output when server isn't ready)
+- Port detection now prioritizes common Rails ports (3000, 3001, 4000, 5000) and excludes problematic ports
+
+### Fixed
+- Fixed logger accessor compatibility issue - logger access is now optional to work with older gem versions
+- Fixed CLI connection issues by improving port detection and server readiness checks
+- Fixed CLI showing empty reports when server isn't ready - now shows informative message instead
+- Improved error handling for connection timeouts and connection refused errors
+- Better handling of interrupt signals during server wait operations
+
+### Improved
+- CLI error messages are now more detailed and actionable with specific remediation steps
+- Server detection is more reliable with improved timeout handling and error recovery
+- Better user experience when running in Procfile.dev with automatic retries
+
 ## [1.2.0] - 2024-12-XX
 
 ### Changed
@@ -111,6 +149,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.3.0]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.3.0
 [1.2.0]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.2.0
 [1.1.6]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.1.6
 [1.1.5]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.1.5

data/GUIDES/getting_started.md

@@ -54,7 +54,7 @@ Let's see it in action. Create a simple system spec:
 
 ```ruby
 # spec/system/home_spec.rb
-RSpec.describe "Home Page" do
+RSpec.describe "Home Page", type: :system do
   it "displays the welcome message" do
     visit root_path
     expect(page).to have_content("Welcome")
@@ -63,6 +63,41 @@ RSpec.describe "Home Page" do
 end
 ```
 
+## Running Comprehensive Checks Explicitly
+
+While checks run automatically after each `visit`, you can also run comprehensive checks explicitly at any point in your test:
+
+```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
+    expect(page).to have_content('Welcome')
+    
+    # Run comprehensive accessibility checks explicitly
+    # This will fail the test if any accessibility issues are found
+    check_comprehensive_accessibility
+    # ✅ This runs all 11 comprehensive checks:
+    #    - Form labels, Image alt text, Interactive elements
+    #    - Heading hierarchy, Keyboard accessibility, ARIA landmarks
+    #    - Form errors, Table structure, Duplicate IDs
+    #    - Skip links, Color contrast (if enabled)
+    # If all checks pass, you'll see: "All comprehensive accessibility checks passed! (11 checks)"
+  end
+end
+```
+
+**When to use explicit checks:**
+- When you want to run checks at a specific point in your test (e.g., after filling a form)
+- When you want to ensure checks run even if the test might fail before the automatic check
+- When you want to test multiple pages in one spec and check each one explicitly
+
+**Note:** Even if you call `check_comprehensive_accessibility` explicitly, the automatic checks will still run after the test completes (unless the test fails before reaching the explicit check).
+
+### Example: Comprehensive Check Output
+
 If there are accessibility issues, you'll see detailed error messages like:
 
 ```
@@ -96,19 +131,33 @@ If there are accessibility issues, you'll see detailed error messages like:
 
 ## Understanding the Checks
 
-Rails A11y runs 11 comprehensive checks:
+Rails A11y runs **11 comprehensive checks** automatically. These checks are WCAG 2.1 AA aligned:
 
-1. **Form Labels** - All inputs have associated labels
-2. **Image Alt Text** - All images have alt attributes
-3. **Interactive Elements** - Buttons and links have accessible names
-4. **Heading Hierarchy** - Proper h1-h6 structure
+1. **Form Labels** - All form inputs have associated labels
+2. **Image Alt Text** - All images have descriptive alt attributes (including empty alt="" detection)
+3. **Interactive Elements** - Buttons, links, and other interactive elements have accessible names
+4. **Heading Hierarchy** - Proper h1-h6 structure without skipping levels
 5. **Keyboard Accessibility** - All interactive elements are 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
-11. **Color Contrast** - Text meets contrast requirements (optional)
+6. **ARIA Landmarks** - Proper use of ARIA landmark roles for page structure
+7. **Form Error Associations** - Form errors are properly linked to their form fields
+8. **Table Structure** - Tables have proper headers and structure
+9. **Duplicate IDs** - No duplicate ID attributes on the page
+10. **Skip Links** - Skip navigation links are present for keyboard users
+11. **Color Contrast** - Text meets WCAG contrast requirements (optional, disabled by default for performance)
+
+### What `check_comprehensive_accessibility` Does
+
+When you call `check_comprehensive_accessibility`, it runs all 11 checks above and provides detailed error messages for any violations found. Each error includes:
+
+- **File location hints** - Know exactly which view file to fix
+- **Element details** - Tag, ID, classes, and visible text
+- **Actionable fix instructions** - Code examples showing how to fix the issue
+- **WCAG references** - Links to relevant WCAG guidelines
+
+If all checks pass, you'll see:
+```
+✅ All comprehensive accessibility checks passed! (11 checks)
+```
 
 ## Configuration
 
@@ -171,6 +220,7 @@ end
 
 ## Next Steps
 
+- **⭐ Read the [System Specs Guide](system_specs_for_accessibility.md)** - Recommended approach for reliable accessibility testing
 - **Read the [CI Integration Guide](continuous_integration.md)** to set up automated checks
 - **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

data/GUIDES/system_specs_for_accessibility.md

@@ -0,0 +1,248 @@
+# Using System Specs for Accessibility Testing
+
+System specs are the **recommended and most reliable** way to run accessibility checks in your Rails application. This guide shows you how to set up continuous accessibility testing using RSpec system specs.
+
+## Why System Specs?
+
+✅ **More Reliable** - Runs in the same test environment as your other specs  
+✅ **Faster** - No need to wait for external server processes  
+✅ **Better Integration** - Works seamlessly with your existing test suite  
+✅ **Automatic** - Checks run automatically after each `visit` in system specs  
+✅ **Clear Feedback** - Detailed error messages with file locations and fix instructions  
+
+## Quick Setup
+
+### 1. Create System Specs
+
+Create system specs for the pages you want to test. Name them with `_accessibility_spec.rb` suffix for clarity:
+
+```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
+    expect(page).to have_content('Biorepository').or have_content('Welcome')
+    
+    # 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
+```
+
+### 2. Automatic Checks
+
+The gem automatically runs comprehensive accessibility checks after each `visit` in system specs. You don't need to call `check_comprehensive_accessibility` manually unless you want to run checks at a specific point in your test.
+
+### 3. Add to Procfile.dev (Optional)
+
+For continuous testing during development, add to your `Procfile.dev`:
+
+```ruby
+web: $(bundle show rails_accessibility_testing)/exe/rails_server_safe
+css: bin/rails dartsass:watch
+a11y: while true; do bundle exec rspec spec/system/*_accessibility_spec.rb; sleep 30; done
+```
+
+This will run your accessibility specs every 30 seconds while you develop.
+
+## Example Specs
+
+### Basic Page Check
+
+```ruby
+# spec/system/home_page_accessibility_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Home Page Accessibility', type: :system do
+  it 'runs accessibility checks on the home page' do
+    visit root_path
+    # ✅ Comprehensive accessibility checks run automatically after this test!
+    # The test will fail if any accessibility issues are found
+  end
+end
+```
+
+### Multiple Pages
+
+```ruby
+# spec/system/pages_accessibility_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Pages Accessibility', type: :system do
+  it 'runs accessibility checks on home page' do
+    visit root_path
+    # Checks run automatically - test fails if issues found
+  end
+
+  it 'runs accessibility checks on about page' do
+    visit about_path
+    # Checks run automatically - test fails if issues found
+  end
+
+  it 'runs accessibility checks on contact page' do
+    visit contact_path
+    # Checks run automatically - test fails if issues found
+  end
+end
+```
+
+### With User Authentication
+
+```ruby
+# spec/system/dashboard_accessibility_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Dashboard Accessibility', type: :system do
+  before do
+    user = FactoryBot.create(:user)
+    sign_in user
+  end
+
+  it 'runs accessibility checks on dashboard' do
+    visit dashboard_path
+    # ✅ Comprehensive accessibility checks run automatically after authentication!
+    # The test will fail if any accessibility issues are found
+  end
+end
+```
+
+### Skip Checks for Specific Tests
+
+```ruby
+it 'does something without accessibility checks', skip_a11y: true do
+  visit some_path
+  # Accessibility checks won't run for this test
+end
+```
+
+## 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
+4. ✅ **Heading Hierarchy** - Proper h1-h6 structure
+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
+11. ✅ **Color Contrast** - Text meets contrast requirements (optional, disabled by default)
+
+## Success Messages
+
+When all checks pass, you'll see:
+
+```
+✅ All comprehensive accessibility checks passed! (11 checks)
+```
+
+## Error Messages
+
+When issues are found, you get detailed, actionable errors:
+
+```
+======================================================================
+❌ ACCESSIBILITY ERROR: Page missing H1 heading
+======================================================================
+
+📄 Page Being Tested:
+   URL: http://127.0.0.1:54384/
+   Path: /
+   📝 Likely View File: app/views/home/about.html.erb
+
+📍 Element Details:
+   Tag: <page>
+   ID: (none)
+   Classes: (none)
+   Visible text: Page has no H1 heading
+
+🔧 HOW TO FIX:
+   Add an <h1> heading to your page:
+
+   <h1>Main Page Title</h1>
+
+   Or in Rails ERB:
+   <h1><%= @page_title || 'Default Title' %></h1>
+
+   💡 Best Practice: Every page should have exactly one <h1>.
+      It should describe the main purpose of the page.
+
+📖 WCAG Reference: https://www.w3.org/WAI/WCAG21/Understanding/
+======================================================================
+```
+
+## Running Specs
+
+### Run All Accessibility Specs
+
+```bash
+bundle exec rspec spec/system/*_accessibility_spec.rb
+```
+
+### Run Specific Spec
+
+```bash
+bundle exec rspec spec/system/home_page_accessibility_spec.rb
+```
+
+### Run with Documentation Format
+
+```bash
+bundle exec rspec spec/system/*_accessibility_spec.rb --format documentation
+```
+
+## Continuous Integration
+
+Add to your CI configuration:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Run Accessibility Tests
+  run: bundle exec rspec spec/system/*_accessibility_spec.rb
+```
+
+## Best Practices
+
+1. **Name your specs clearly** - Use `_accessibility_spec.rb` suffix
+2. **Test critical paths** - Focus on user-facing pages
+3. **Keep specs simple** - One page per spec is often enough
+4. **Use Procfile.dev** - For continuous testing during development
+5. **Run in CI** - Catch issues before they reach production
+
+## Troubleshooting
+
+### Checks Not Running
+
+Make sure:
+- Your spec has `type: :system`
+- You call `visit` in your test
+- The gem is properly configured in `spec/rails_helper.rb`
+
+### Success Message Not Showing
+
+The success message appears when all checks pass. If you don't see it, there may be silent failures. Check your RSpec output for any exceptions.
+
+### Slow Tests
+
+Disable color contrast checking in development:
+
+```yaml
+# config/accessibility.yml
+development:
+  checks:
+    color_contrast: false
+```
+
+## Next Steps
+
+- See [Getting Started Guide](getting_started.md) for initial setup
+- See [Continuous Integration Guide](continuous_integration.md) for CI/CD setup
+- See [Writing Accessible Views](writing_accessible_views_in_rails.md) for best practices
+

data/README.md

@@ -7,7 +7,7 @@
 
 **The RSpec + RuboCop of accessibility for Rails. Catch WCAG violations before they reach production.**
 
-**Current Version:** 1.1.0
+**Current Version:** 1.4.0
 
 📖 **[📚 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,6 +40,8 @@ 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
 end
 ```
 
@@ -82,13 +84,45 @@ RailsAccessibilityTesting::Integration::MinitestIntegration.setup!
 
 ## 📖 Usage
 
+### System Specs (Recommended)
+
+**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:
+
+```ruby
+# 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('Biorepository').or 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!**
+
+For continuous testing during development, add to your `Procfile.dev`:
+
+```ruby
+a11y: while true; do bundle exec rspec spec/system/*_accessibility_spec.rb; sleep 30; done
+```
+
+📖 **[See the full System Specs Guide](GUIDES/system_specs_for_accessibility.md)** for detailed examples and best practices.
+
 ### Automatic Checks
 
 Just write your specs normally - checks run automatically:
 
 ```ruby
 # spec/system/home_page_spec.rb
-RSpec.describe "Home Page" do
+RSpec.describe "Home Page", type: :system do
   it "displays welcome message" do
     visit root_path
     expect(page).to have_content("Welcome")
@@ -268,6 +302,7 @@ Complete documentation site with all guides, examples, and API reference. The do
 
 ### Guides
 
+- **[System Specs for Accessibility](GUIDES/system_specs_for_accessibility.md)** - ⭐ **Recommended approach** - Using system specs for reliable accessibility testing
 - **[Getting Started](GUIDES/getting_started.md)** - Quick start guide
 - **[Continuous Integration](GUIDES/continuous_integration.md)** - CI/CD setup
 - **[Writing Accessible Views](GUIDES/writing_accessible_views_in_rails.md)** - Best practices
@@ -301,9 +336,13 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architecture documentation.
 - Ruby 3.0+ (3.1+ recommended)
 - Rails 6.0+ (7.1+ recommended)
 - RSpec Rails 6.0+ (for RSpec) or Minitest (for Minitest)
-- Capybara 3.0+
+- Capybara 3.0+ (provided by your project)
+- selenium-webdriver 4.0+ (provided by your project, for system specs)
+- webdrivers (optional, provided by your project, for automatic driver management)
 - Chrome/Chromium browser
 
+**Note:** As of version 1.2.0, the gem has minimal dependencies. You provide and configure Capybara, selenium-webdriver, and webdrivers in your own Gemfile, giving you full control over your test driver setup.
+
 ## 🤝 Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

data/lib/rails_accessibility_testing/accessibility_helper.rb

@@ -83,6 +83,9 @@ module AccessibilityHelper
     # If we collected any errors and this was called directly (not from comprehensive), raise them
     if @accessibility_errors.any? && !@in_comprehensive_check
       raise format_all_errors(@accessibility_errors)
+    elsif @accessibility_errors.empty? && !@in_comprehensive_check
+      # Show success message when all checks pass
+      puts "\n✅ All basic accessibility checks passed! (5 checks: form labels, images, interactive elements, headings, keyboard)"
     end
   end
 
@@ -103,6 +106,9 @@ module AccessibilityHelper
     # If we collected any errors, raise them all together
     if @accessibility_errors.any?
       raise format_all_errors(@accessibility_errors)
+    else
+      # Show success message when all checks pass
+      puts "\n✅ All comprehensive accessibility checks passed! (11 checks: form labels, images, interactive elements, headings, keyboard, ARIA landmarks, form errors, table structure, duplicate IDs, skip links, color contrast)"
     end
   end
 

data/lib/rails_accessibility_testing/checks/image_alt_text_check.rb

@@ -17,6 +17,10 @@ module RailsAccessibilityTesting
         
         page.all('img', visible: :all).each do |img|
           has_alt_attribute = page.evaluate_script("arguments[0].hasAttribute('alt')", img.native)
+          # Get alt value - might be nil, empty string, or actual text
+          alt_value = img[:alt] || ""
+          # Also check via JavaScript to be sure
+          alt_value_js = page.evaluate_script("arguments[0].getAttribute('alt')", img.native) || ""
           
           if has_alt_attribute == false
             element_ctx = element_context(img)
@@ -27,6 +31,17 @@ module RailsAccessibilityTesting
               wcag_reference: "1.1.1",
               remediation: generate_remediation(element_ctx)
             )
+          elsif (alt_value.blank? || alt_value_js.blank?) && has_alt_attribute
+            # Image has alt attribute but it's empty - warn about this
+            # Empty alt is valid for decorative images, but we should check if it's actually decorative
+            element_ctx = element_context(img)
+            
+            violations << violation(
+              message: "Image has empty alt attribute - ensure this image is purely decorative. If it conveys information, add descriptive alt text.",
+              element_context: element_ctx,
+              wcag_reference: "1.1.1",
+              remediation: generate_remediation(element_ctx)
+            )
           end
         end
         

data/lib/rails_accessibility_testing/cli/command.rb

@@ -53,7 +53,7 @@ module RailsAccessibilityTesting
       
       def parse_options(argv)
         options = {
-          profile: :test,
+          profile: :development,  # Use development profile by default (faster, no color contrast)
           format: :human,
           output: nil,
           debug: false
@@ -106,6 +106,9 @@ module RailsAccessibilityTesting
       end
       
       def run_checks(options, config)
+        # Reset wait attempts counter for each run
+        @wait_attempts = 0
+        
         require 'capybara'
         require 'capybara/dsl'
         require 'selenium-webdriver'
@@ -135,12 +138,49 @@ module RailsAccessibilityTesting
             url = normalize_url(target)
             
             # Wait for server to be ready (with retries)
-            wait_for_server(url) if url.match?(/\Ahttps?:\/\//)
+            # If wait fails, try to re-detect port and update URL
+            if url.match?(/\Ahttps?:\/\//)
+              # First, try to detect the port (might not be ready yet)
+              uri = URI.parse(url)
+              detected_port = detect_server_port
+              
+              # If we detected a different port, update the URL
+              if detected_port != uri.port.to_s
+                url = "#{uri.scheme}://#{uri.host}:#{detected_port}#{uri.path}"
+              end
+              
+              # Now wait for server to be ready
+              server_ready = wait_for_server(url, max_retries: 20, retry_delay: 1)
+              
+              # If still not ready, try re-detecting port one more time
+              unless server_ready
+                new_port = detect_server_port
+                if new_port != uri.port.to_s
+                  url = "#{uri.scheme}://#{uri.host}:#{new_port}#{uri.path}"
+                  server_ready = wait_for_server(url, max_retries: 20, retry_delay: 1)
+                end
+                
+                # If still not ready, skip this check and try next time
+                unless server_ready
+                  # Server still starting - this is normal, will retry automatically
+                  # Only show message occasionally to avoid spam (every 3rd attempt)
+                  @wait_attempts ||= 0
+                  @wait_attempts += 1
+                  if @wait_attempts % 3 == 1
+                    $stderr.puts "Waiting for server to start... (will retry automatically)"
+                  end
+                  next
+                end
+              end
+            end
             
             Capybara.visit(url)
             violations = engine.check(Capybara.current_session, context: { url: url })
             all_violations.concat(violations)
             checked_urls << { url: url, violations: violations.count }
+          rescue Interrupt
+            # Handle interrupt gracefully - exit the loop
+            break
           rescue StandardError => e
             $stderr.puts "Error checking #{target}: #{e.message}"
           end
@@ -180,8 +220,8 @@ module RailsAccessibilityTesting
         return target if target.match?(/\Ahttps?:\/\//)
         
         # If it's a path and we're using Selenium, construct a full URL
-        # Default to localhost:3000 (standard Rails port)
-        port = ENV['PORT'] || ENV['RAILS_PORT'] || '3000'
+        # Try to detect the actual port, or use environment variables, or default to 3000
+        port = detect_server_port
         base_url = ENV['RAILS_URL'] || "http://localhost:#{port}"
         
         # Ensure path starts with /
@@ -189,7 +229,42 @@ module RailsAccessibilityTesting
         "#{base_url}#{path}"
       end
       
-      def wait_for_server(url, max_retries: 10, retry_delay: 2)
+      def detect_server_port
+        # Check environment variables first
+        return ENV['PORT'] if ENV['PORT']
+        return ENV['RAILS_PORT'] if ENV['RAILS_PORT']
+        
+        # Try to detect port from Rails server - check common Rails ports
+        # Check in order: 3000 (most common), then others
+        # Prioritize 3000 first as it's the Rails default
+        common_ports = [3000, 3001, 4000, 5000]
+        
+        common_ports.each do |port|
+          begin
+            require 'net/http'
+            http = Net::HTTP.new('localhost', port)
+            http.open_timeout = 1
+            http.read_timeout = 1
+            # Try to get a response - check if it looks like a Rails server
+            response = http.head('/')
+            # Accept 2xx, 3xx, or 4xx responses (server is responding)
+            # Reject 5xx as it might be a proxy or error
+            if response.code.to_i < 500
+              # Additional check: Rails servers usually have certain headers
+              # But for now, any HTTP response on these common ports is likely Rails
+              return port.to_s
+            end
+          rescue Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout, SocketError, Interrupt, Errno::EHOSTUNREACH, Errno::ETIMEDOUT
+            # Port not available or interrupted, try next
+            next
+          end
+        end
+        
+        # Default to 3000 if nothing found
+        '3000'
+      end
+      
+      def wait_for_server(url, max_retries: 15, retry_delay: 1)
         require 'net/http'
         require 'uri'
         
@@ -199,22 +274,31 @@ module RailsAccessibilityTesting
         max_retries.times do |attempt|
           begin
             http = Net::HTTP.new(uri.host, uri.port)
-            http.open_timeout = 1
-            http.read_timeout = 1
+            http.open_timeout = 2
+            http.read_timeout = 2
             response = http.head('/')
-            return if response.code.to_i < 500 # Server is responding
-          rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout, SocketError
+            return true if response.code.to_i < 500 # Server is responding
+          rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout, SocketError, Errno::EHOSTUNREACH
             # Server not ready yet
             if attempt < max_retries - 1
-              sleep(retry_delay)
+              begin
+                sleep(retry_delay)
+              rescue Interrupt
+                # Handle interrupt gracefully - return false to indicate failure
+                return false
+              end
               next
             else
-              # Last attempt failed, but we'll still try to visit (might be a different error)
-              $stderr.puts "Warning: Server at #{base_url} not responding after #{max_retries} attempts, attempting anyway..."
-              return
+              # Last attempt failed
+              return false
             end
+          rescue Interrupt
+            # Handle interrupt gracefully
+            return false
           end
         end
+        
+        false
       end
       
       def resolve_routes(routes)
@@ -230,6 +314,11 @@ module RailsAccessibilityTesting
       end
       
       def generate_report(results, options)
+        # Don't generate report if no URLs were checked (server not ready)
+        if results[:summary][:urls_checked] == 0
+          return
+        end
+        
         output = case options[:format]
                  when :json
                    generate_json_report(results)
@@ -262,11 +351,14 @@ module RailsAccessibilityTesting
           output << ""
           
           results[:violations].each_with_index do |violation, index|
-            output << "#{index + 1}. #{violation.message}"
-            output << "   Rule: #{violation.rule_name}"
-            output << "   URL: #{violation.page_context[:url]}"
-            output << "   View: #{violation.page_context[:view_file]}" if violation.page_context[:view_file]
-            output << ""
+            # Use ErrorMessageBuilder for detailed formatted messages
+            detailed_message = ErrorMessageBuilder.build(
+              error_type: violation.message,
+              element_context: violation.element_context || {},
+              page_context: violation.page_context || {}
+            )
+            output << detailed_message
+            output << "" if index < results[:violations].count - 1  # Add spacing between violations
           end
         else
           output << "✅ No accessibility violations found!"
@@ -300,7 +392,8 @@ module RailsAccessibilityTesting
             -v, --version                 Show version
           
           Examples:
-            rails_a11y check /home /about
+            rails_a11y /home /about
+            rails_a11y /
             rails_a11y --urls https://example.com
             rails_a11y --routes home_path about_path --format json --output report.json
         HELP

data/lib/rails_accessibility_testing/config/yaml_loader.rb

@@ -38,7 +38,9 @@ module RailsAccessibilityTesting
           
           merge_profile_config(parsed, profile)
         rescue StandardError => e
-          RailsAccessibilityTesting.config.logger&.warn("Failed to load config: #{e.message}") if defined?(RailsAccessibilityTesting)
+          if defined?(RailsAccessibilityTesting) && RailsAccessibilityTesting.config.respond_to?(:logger) && RailsAccessibilityTesting.config.logger
+            RailsAccessibilityTesting.config.logger.warn("Failed to load config: #{e.message}")
+          end
           default_config
         end
         

data/lib/rails_accessibility_testing/configuration.rb

@@ -9,11 +9,13 @@ module RailsAccessibilityTesting
   #   end
   #
   # @attr [Boolean] auto_run_checks Whether to automatically run checks after system specs
+  # @attr [Logger, nil] logger Optional logger for accessibility check output
   class Configuration
-    attr_accessor :auto_run_checks
+    attr_accessor :auto_run_checks, :logger
 
     def initialize
       @auto_run_checks = true
+      @logger = nil
     end
   end
 

data/lib/rails_accessibility_testing/engine/rule_engine.rb

@@ -38,7 +38,9 @@ module RailsAccessibilityTesting
             @violation_collector.add(violations) if violations.any?
           rescue StandardError => e
             # Log but don't fail - one check error shouldn't stop others
-            RailsAccessibilityTesting.config.logger&.error("Check #{check_class.rule_name} failed: #{e.message}") if defined?(RailsAccessibilityTesting)
+            if defined?(RailsAccessibilityTesting) && RailsAccessibilityTesting.config.respond_to?(:logger) && RailsAccessibilityTesting.config.logger
+              RailsAccessibilityTesting.config.logger.error("Check #{check_class.rule_name} failed: #{e.message}")
+            end
           end
         end
         

data/lib/rails_accessibility_testing/rspec_integration.rb

@@ -48,7 +48,14 @@ module RailsAccessibilityTesting
           # Run comprehensive accessibility checks
           instance = example.example_group_instance
           instance.check_comprehensive_accessibility
+          
+          # If we get here without an exception, all checks passed
+          # Note: check_comprehensive_accessibility will raise if there are errors,
+          # so if we reach this point, checks passed successfully
+          $stdout.puts "\n✅ All comprehensive accessibility checks passed! (11 checks)"
+          $stdout.flush
         rescue StandardError => e
+          # Accessibility check failed - set the exception so test fails
           example.set_exception(e)
         end
       end

data/lib/rails_accessibility_testing/version.rb

@@ -1,4 +1,4 @@
 module RailsAccessibilityTesting
-  VERSION = "1.2.0"
+  VERSION = "1.4.0"
 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.1.0
+# @version 1.4.0
 # @author Regan Maharjan
 #
 # @example Basic usage
@@ -38,7 +38,7 @@ begin
   require_relative 'rails_accessibility_testing/version'
 rescue LoadError
   module RailsAccessibilityTesting
-    VERSION = '1.1.0'
+    VERSION = '1.4.0'
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_accessibility_testing
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Regan Maharjan
@@ -84,6 +84,7 @@ files:
 - CONTRIBUTING.md
 - GUIDES/continuous_integration.md
 - GUIDES/getting_started.md
+- GUIDES/system_specs_for_accessibility.md
 - GUIDES/working_with_designers_and_content_authors.md
 - GUIDES/writing_accessible_views_in_rails.md
 - LICENSE