rails_accessibility_testing 1.4.3 → 1.5.0

data/docs_site/getting_started.md

@@ -20,6 +20,7 @@ Add to your `Gemfile`:
 ```ruby
 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'
@@ -27,7 +28,9 @@ group :development, :test do
 end
 ```
 
-**Important:** You must explicitly add `selenium-webdriver` to your Gemfile. It's not automatically included as a dependency.
+**Important:** 
+- You must explicitly add `selenium-webdriver` to your Gemfile. It's not automatically included as a dependency.
+- **RSpec Rails is required** - The generator creates system specs that require `rspec-rails`. If you're using Minitest, you'll need to manually create your accessibility tests.
 
 Then run:
 
@@ -46,11 +49,55 @@ rails generate rails_a11y:install
 This creates:
 - `config/initializers/rails_a11y.rb` - Configuration
 - `config/accessibility.yml` - Check settings
+- `spec/system/all_pages_accessibility_spec.rb` - Comprehensive spec that tests all GET routes
 - Updates `spec/rails_helper.rb` (if using RSpec)
 
-### Step 2.5: Configure Capybara Driver (Required for System Tests)
+**Note:** If you already have system tests set up in your Rails application, you can skip to Step 3. If you need help configuring Capybara or installing Chrome, see the [Troubleshooting section](#troubleshooting) below.
 
-For system tests to work, you need to configure Capybara with a Selenium driver. Create `spec/support/driver.rb`:
+### Step 3: Run Your Tests
+
+The generator creates `spec/system/all_pages_accessibility_spec.rb` which automatically tests all GET routes in your application.
+
+You can also create custom system specs for specific pages:
+
+```ruby
+# spec/system/my_page_accessibility_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'My 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
+# Run all accessibility specs
+bundle exec rspec spec/system/*_accessibility_spec.rb
+
+# Or run all system specs
+bundle exec rspec spec/system/
+```
+
+Accessibility checks run automatically on every system test that visits a page.
+
+
+## Troubleshooting
+
+### How do I configure Capybara for system tests?
+
+If you don't already have system tests configured, you need to set up Capybara with a Selenium driver. Create `spec/support/driver.rb`:
 
 ```ruby
 # spec/support/driver.rb
@@ -85,7 +132,7 @@ 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)
+### How do I install Chrome/Chromium?
 
 System tests require Chrome or Chromium to be installed on your system:
 
@@ -109,63 +156,6 @@ Download and install Chrome from [google.com/chrome](https://www.google.com/chro
 
 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/
-```
-
-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!
-
-## Troubleshooting
-
 ### Error: `uninitialized constant Selenium::WebDriver::DriverFinder`
 
 This error typically occurs when:
@@ -218,14 +208,14 @@ development:
 
 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+ |
+| Component | Recommended Version | Minimum Version | Required |
+|-----------|-------------------|-----------------|----------|
+| Ruby | 3.1+ | 3.0+ | Yes |
+| Rails | 7.1+ / 8.0+ | 6.0+ | Yes |
+| **RSpec Rails** | **8.0+** | **6.0+** | **Yes (for system specs)** |
+| Capybara | ~> 3.40 | 3.0+ | Yes |
+| selenium-webdriver | ~> 4.10 | 4.0+ | Yes |
+| webdrivers | ~> 5.3 | 5.0+ | Optional |
 
 **Rails 8 Notes:**
 - Rails 8 requires `selenium-webdriver` 4.6.0+ for `DriverFinder` support

data/exe/a11y_live_scanner

@@ -0,0 +1,361 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Live accessibility scanner for development
+# Monitors page visits and runs accessibility checks automatically
+# Usage: Add to Procfile.dev as: a11y: bundle exec a11y_live_scanner
+
+require 'bundler/setup'
+require 'json'
+require 'fileutils'
+require 'timeout'
+
+# Load Rails environment
+# Find Rails root by looking for config/environment.rb
+rails_root = Dir.pwd
+while rails_root != '/' && !File.exist?(File.join(rails_root, 'config', 'environment.rb'))
+  rails_root = File.dirname(rails_root)
+end
+
+if File.exist?(File.join(rails_root, 'config', 'environment.rb'))
+  Dir.chdir(rails_root)
+  require File.join(rails_root, 'config', 'environment')
+end
+
+# Require the gem and ensure all components are loaded
+begin
+  require 'rails_accessibility_testing'
+  # Verify AccessibilityHelper is available
+  unless defined?(RailsAccessibilityTesting::AccessibilityHelper)
+    raise LoadError, "RailsAccessibilityTesting::AccessibilityHelper not found after requiring gem"
+  end
+rescue LoadError => e
+  $stderr.puts "❌ Error loading rails_accessibility_testing gem: #{e.message}"
+  $stderr.puts "   Make sure the gem is installed: bundle install"
+  exit 1
+end
+
+require 'capybara'
+require 'capybara/dsl'
+require 'selenium-webdriver'
+
+# Try to require webdrivers
+begin
+  require 'webdrivers'
+rescue LoadError
+  # webdrivers not available
+end
+
+# Setup Capybara for live scanning
+Capybara.default_driver = :selenium_chrome_headless
+Capybara.app_host = ENV.fetch('RAILS_URL', 'http://localhost:3000')
+Capybara.default_max_wait_time = 5
+
+# Configure Chrome options
+browser_options = Selenium::WebDriver::Chrome::Options.new
+browser_options.add_argument('--headless')
+browser_options.add_argument('--window-size=1920,1080')
+browser_options.add_argument('--disable-gpu')
+browser_options.add_argument('--no-sandbox')
+
+Capybara.register_driver :selenium_chrome_headless do |app|
+  Capybara::Selenium::Driver.new(
+    app,
+    browser: :chrome,
+    options: browser_options
+  )
+end
+
+include Capybara::DSL
+
+# Page visit log file
+def log_file
+  defined?(Rails) ? File.join(Rails.root, 'tmp', 'a11y_page_visits.log') : File.join(Dir.pwd, 'tmp', 'a11y_page_visits.log')
+end
+
+def scanned_pages_file
+  defined?(Rails) ? File.join(Rails.root, 'tmp', 'a11y_scanned_pages.json') : File.join(Dir.pwd, 'tmp', 'a11y_scanned_pages.json')
+end
+
+# Track which pages we've already scanned (to avoid duplicates)
+def load_scanned_pages
+  return {} unless File.exist?(scanned_pages_file)
+  JSON.parse(File.read(scanned_pages_file))
+rescue StandardError
+  {}
+end
+
+def save_scanned_page(path, timestamp)
+  scanned = load_scanned_pages
+  scanned[path] = timestamp
+  # Use atomic write to avoid triggering file watchers unnecessarily
+  temp_file = "#{scanned_pages_file}.tmp"
+  File.write(temp_file, scanned.to_json)
+  FileUtils.mv(temp_file, scanned_pages_file)
+rescue StandardError => e
+  # Silently fail - don't break scanning if file write fails
+end
+
+def page_already_scanned?(path, visit_timestamp)
+  scanned = load_scanned_pages
+  return false unless scanned[path]
+  # Don't rescan if scanned within last 30 seconds (debounce)
+  last_scan_time = scanned[path].to_f
+  (Time.now.to_f - last_scan_time) < 30
+end
+
+# Run accessibility check on a page
+def check_page(path, url = nil)
+  begin
+    # Check if scan was cancelled before starting
+    if $scan_cancelled
+      puts "⏭️  Scan cancelled - user navigated to different page"
+      return nil
+    end
+    
+    # Show what we're about to scan
+    puts "\n" + "="*70
+    puts "🔍 Starting accessibility scan..."
+    puts "="*70
+    puts "📍 Path: #{path}"
+    puts "🔗 URL: #{url || path}"
+    puts "⏰ Time: #{Time.now.strftime('%H:%M:%S')}"
+    puts "="*70
+    puts ""
+    
+    # Visit the page
+    puts "  🌐 Loading page..."
+    visit path
+    
+    # Check for cancellation after page load
+    if $scan_cancelled || $current_scan_target != path
+      puts "⏭️  Scan cancelled - user navigated to different page"
+      return nil
+    end
+    
+    # Capybara already waits for page load, no need for explicit sleep
+    # Only wait if page hasn't loaded (Capybara handles this automatically)
+    
+    # Get page details
+    current_url = page.current_url rescue path
+    page_title = page.title rescue 'Unknown'
+    
+    # Skip if redirected to sign in
+    if current_url.include?('sign_in') || current_url.include?('login')
+      puts "⏭️  Skipping #{path}: requires authentication"
+      puts "   Redirected to: #{current_url}"
+      return nil
+    end
+    
+    # Check for cancellation before running checks
+    if $scan_cancelled || $current_scan_target != path
+      puts "⏭️  Scan cancelled - user navigated to different page"
+      return nil
+    end
+    
+    # Show page details
+    puts "  ✓ Page loaded successfully"
+    puts "  📄 Title: #{page_title}"
+    puts "  🔗 Final URL: #{current_url}"
+    puts ""
+    puts "  🔍 Running accessibility checks..."
+    puts ""
+    
+    # Run accessibility checks using Capybara page directly
+    # Verify AccessibilityHelper is available
+    unless defined?(RailsAccessibilityTesting::AccessibilityHelper)
+      raise "RailsAccessibilityTesting::AccessibilityHelper is not available. Make sure the gem is properly installed."
+    end
+    
+    # Create a minimal helper instance
+    helper_class = Class.new do
+      include RailsAccessibilityTesting::AccessibilityHelper
+      
+      def initialize(page)
+        @page = page
+      end
+      
+      def page
+        @page
+      end
+    end
+    
+    helper = helper_class.new(page)
+    
+    # Run checks with periodic cancellation checks
+    # Note: The checks themselves don't support cancellation yet, but we check before/after
+    result = helper.check_comprehensive_accessibility
+    
+    # Check for cancellation after checks complete
+    if $scan_cancelled || $current_scan_target != path
+      puts "⏭️  Scan cancelled - user navigated to different page"
+      return nil
+    end
+    
+    # Show scan completion
+    puts ""
+    puts "="*70
+    puts "✅ Scan completed for: #{path}"
+    if result && result.is_a?(Hash)
+      puts "   Errors: #{result[:errors] || 0}, Warnings: #{result[:warnings] || 0}"
+    end
+    puts "="*70
+    puts ""
+    
+    # Return result
+    result
+  rescue StandardError => e
+    # Don't show error if scan was cancelled
+    if $scan_cancelled || $current_scan_target != path
+      return nil
+    end
+    
+    puts ""
+    puts "="*70
+    puts "⚠️  Error checking #{path}"
+    puts "   Error: #{e.message}"
+    puts "   URL: #{url || path}"
+    puts "="*70
+    puts ""
+    nil
+  end
+end
+
+# Global variable to track current scan target (for cancellation)
+$current_scan_target = nil
+$scan_cancelled = false
+
+# Main scanner loop
+def run_scanner
+  puts "\n" + "="*70
+  puts "🔍 Live Accessibility Scanner Started"
+  puts "="*70
+  puts "📍 Monitoring: #{Capybara.app_host}"
+  puts "📝 Watching: #{log_file}"
+  puts "💡 Navigate to pages in your browser to see accessibility reports"
+  puts "⏱️  Checking for new page visits every 2 seconds..."
+  puts "💡 Tip: If you navigate to a new page, current scan will be cancelled"
+  puts "="*70
+  puts ""
+  puts "⏳ Waiting for page visits... (scanning will start automatically)"
+  puts ""
+  
+  # Create log file if it doesn't exist
+  FileUtils.mkdir_p(File.dirname(log_file))
+  FileUtils.touch(log_file) unless File.exist?(log_file)
+  
+  # Start reading from end of file
+  last_position = File.exist?(log_file) ? File.size(log_file) : 0
+  last_scan_time = {} # In-memory debounce cache
+  
+  loop do
+    begin
+      # Check if log file has new content
+      current_size = File.exist?(log_file) ? File.size(log_file) : 0
+      
+      if current_size > last_position
+        # Read all new lines to get the latest page visit
+        new_visits = []
+        File.open(log_file, 'r') do |f|
+          f.seek(last_position)
+          f.each_line do |line|
+            next if line.strip.empty?
+            
+            begin
+              visit_data = JSON.parse(line.strip)
+              new_visits << visit_data
+            rescue JSON::ParserError => e
+              # Skip invalid JSON
+              next
+            end
+          end
+        end
+        
+        # Process only the most recent visit (user's current page)
+        if new_visits.any?
+          begin
+            # Get the latest visit (last in the array)
+            latest_visit = new_visits.last
+            path = latest_visit['path']
+            url = latest_visit['url']
+            timestamp = latest_visit['timestamp'].to_f
+            
+            # Debounce: Skip if we scanned this page in the last 30 seconds (in-memory check)
+            if last_scan_time[path] && (Time.now.to_f - last_scan_time[path]) < 30
+              last_position = current_size
+              next
+            end
+            
+            # Skip if we've already scanned this page (from persistent storage)
+            if page_already_scanned?(path, timestamp)
+              last_position = current_size
+              next
+            end
+            
+            # Cancel current scan if scanning a different page
+            if $current_scan_target && $current_scan_target != path
+              puts "\n⚠️  User navigated to new page - cancelling current scan"
+              puts "   Previous: #{$current_scan_target}"
+              puts "   New: #{path}"
+              $scan_cancelled = true
+              # Give a moment for cancellation to be processed
+              sleep 0.5
+            end
+            
+            # Reset cancellation flag and set new target
+            $scan_cancelled = false
+            $current_scan_target = path
+            
+            # Mark as scanned (both in memory and on disk)
+            last_scan_time[path] = Time.now.to_f
+            save_scanned_page(path, timestamp)
+            
+            # Show that we detected a new page visit
+            visit_time = Time.at(timestamp)
+            puts "\n" + "🎯" + "="*69
+            puts "📥 NEW PAGE VISIT DETECTED"
+            puts "="*70
+            puts "   Path: #{path}"
+            puts "   URL: #{url}"
+            puts "   Visited at: #{visit_time.strftime('%H:%M:%S')}"
+            puts "   Starting scan..."
+            puts "="*70
+            
+            # Run check with URL info
+            check_page(path, url)
+            
+            # Clear scan target after completion
+            $current_scan_target = nil if $current_scan_target == path
+          rescue StandardError => e
+            puts "⚠️  Error processing visit: #{e.message}"
+          end
+        end
+        
+        last_position = current_size
+      end
+      
+      # Sleep longer to reduce file system activity and avoid triggering Rails reloads
+      # Check every 2 seconds - fast enough for live scanning, slow enough to not overload
+      # Show a subtle indicator that we're still monitoring (every 10 seconds)
+      if Time.now.to_i % 10 == 0
+        print "💚 Monitoring... (#{Time.now.strftime('%H:%M:%S')})\r"
+        $stdout.flush
+      end
+      sleep 2
+      
+    rescue StandardError => e
+      puts "\n⚠️  Scanner error: #{e.message}"
+      puts "   Continuing to monitor..."
+      sleep 2
+    end
+  end
+end
+
+# Run the scanner
+begin
+  run_scanner
+rescue Interrupt
+  puts "\n\n👋 Live scanner stopped"
+  exit 0
+end
+

data/exe/rails_server_safe

@@ -15,7 +15,17 @@ if [ -f "$PIDFILE" ]; then
     # Check if it's listening on the expected port
     if lsof -ti:$PORT -sTCP:LISTEN | grep -q "^$PID$" 2>/dev/null; then
       echo "Server is already running (pid: $PID, port: $PORT)"
+      echo "Keeping process alive for Foreman..."
+      # Keep the process alive by waiting indefinitely
+      # This prevents Foreman from shutting down all processes
+      while true; do
+        # Check if the server process is still running
+        if ! kill -0 "$PID" 2>/dev/null; then
+          echo "Server process ended. Exiting."
       exit 0
+        fi
+        sleep 5
+      done
     else
       # PID exists but not listening on port - stale PID file
       echo "Removing stale PID file (pid: $PID not listening on port $PORT)"
@@ -32,8 +42,15 @@ fi
 if lsof -ti:$PORT -sTCP:LISTEN >/dev/null 2>&1; then
   EXISTING_PID=$(lsof -ti:$PORT -sTCP:LISTEN | head -1)
   echo "Port $PORT is already in use by process $EXISTING_PID"
-  echo "Server may already be running. Exiting gracefully."
+  echo "Server may already be running. Keeping process alive for Foreman..."
+  # Keep the process alive by monitoring the existing server
+  while true; do
+    if ! lsof -ti:$PORT -sTCP:LISTEN >/dev/null 2>&1; then
+      echo "Port $PORT is now free. Exiting so Foreman can restart."
   exit 0
+    fi
+    sleep 5
+  done
 fi
 
 # Start the server normally

data/lib/generators/rails_a11y/install/install_generator.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+require 'fileutils'
+
+module RailsA11y
+  # Generator to install Rails Accessibility Testing
+  #
+  # Creates initializer and configuration file.
+  #
+  # @example
+  #   rails generate rails_a11y:install
+  #
+  class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+      
+      desc "Install Rails A11y: creates initializer and configuration file"
+      
+      def create_initializer
+        template 'initializer.rb.erb', 'config/initializers/rails_a11y.rb'
+      end
+      
+      def create_config_file
+        template 'accessibility.yml.erb', 'config/accessibility.yml'
+      end
+      
+      def add_to_rails_helper
+        rails_helper_path = 'spec/rails_helper.rb'
+        
+        if File.exist?(rails_helper_path)
+          rails_helper_content = File.read(rails_helper_path)
+          
+          # Add rails_accessibility_testing require
+          unless rails_helper_content.include?("require 'rails_accessibility_testing'")
+            inject_into_file rails_helper_path,
+              after: "require 'rspec/rails'\n" do
+              "require 'rails_accessibility_testing'\n"
+            end
+          end
+        else
+          say "⚠️  spec/rails_helper.rb not found. Please add: require 'rails_accessibility_testing'", :yellow
+        end
+      end
+      
+      def create_all_pages_spec
+        spec_path = 'spec/system/all_pages_accessibility_spec.rb'
+        
+        if File.exist?(spec_path)
+          say "⚠️  #{spec_path} already exists. Skipping creation.", :yellow
+        else
+          template 'all_pages_accessibility_spec.rb.erb', spec_path
+          say "✅ Created #{spec_path}", :green
+        end
+      end
+      
+      def update_procfile_dev
+        procfile_path = 'Procfile.dev'
+        
+        if File.exist?(procfile_path)
+          procfile_content = File.read(procfile_path)
+          
+          # Check if a11y line already exists
+          unless procfile_content.include?('a11y:')
+            # Add live scanner to Procfile.dev
+            a11y_line = "a11y: bundle exec a11y_live_scanner\n"
+            procfile_content += a11y_line
+            File.write(procfile_path, procfile_content)
+            say "✅ Added live accessibility scanner to #{procfile_path}", :green
+            say "   💡 Run 'bin/dev' to start live scanning as you browse pages", :cyan
+          else
+            say "⚠️  Procfile.dev already contains an a11y entry. Skipping.", :yellow
+          end
+        else
+          # Create Procfile.dev if it doesn't exist
+          procfile_content = <<~PROCFILE
+            web: bin/rails server
+            a11y: bundle exec a11y_live_scanner
+          PROCFILE
+          
+          File.write(procfile_path, procfile_content)
+          say "✅ Created #{procfile_path} with live accessibility scanner", :green
+        end
+      end
+      
+      def update_gitignore
+        gitignore_path = '.gitignore'
+        
+        if File.exist?(gitignore_path)
+          gitignore_content = File.read(gitignore_path)
+          
+          # Add tmp files for live scanner if not already present
+          a11y_entries = [
+            'tmp/a11y_page_visits.log',
+            'tmp/a11y_scanned_pages.json'
+          ]
+          
+          a11y_entries.each do |entry|
+            unless gitignore_content.include?(entry)
+              gitignore_content += "\n#{entry}\n"
+            end
+          end
+          
+          File.write(gitignore_path, gitignore_content) if gitignore_content != File.read(gitignore_path)
+        end
+      end
+      
+      def show_instructions
+        say "\n✅ Rails Accessibility Testing installed successfully!", :green
+        say "\n📋 Next Steps:", :yellow
+        say ""
+        say "  1. Run the accessibility tests:", :cyan
+        say "     bundle exec rspec spec/system/all_pages_accessibility_spec.rb"
+        say ""
+        say "  2. For live scanning during development:", :cyan
+        say "     bin/dev  # Starts web server + live accessibility scanner"
+        say "     # Navigate to pages in your browser to see real-time reports!"
+        say ""
+        say "  3. Create custom specs for specific pages:", :cyan
+        say "     # spec/system/my_page_accessibility_spec.rb"
+        say "     RSpec.describe 'My Page', type: :system do"
+        say "       it 'is accessible' do"
+        say "         visit my_page_path"
+        say "         check_comprehensive_accessibility"
+        say "       end"
+        say "     end"
+        say ""
+        say "  4. Configure which checks run in config/accessibility.yml", :cyan
+        say ""
+        say "  5. Accessibility checks run automatically after each 'visit' in system specs!", :cyan
+        say ""
+        say "📚 Documentation:", :yellow
+        say "   • README: https://github.com/rayraycodes/rails-accessibility-testing"
+        say ""
+      end
+  end
+end
+