rails_accessibility_testing 1.1.4 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d58abecc3e5e128753499732dea24b016875593af005f776a9e94002f5d779e9
-  data.tar.gz: 51f98255eb1ae6042b55310532c59adfb9ebaeedb5a9415d4e1be652986df1c7
+  metadata.gz: 916b677bef5f630731d65df12bdd430949d70876ec0c5a9c047e15353084ae7b
+  data.tar.gz: 4960a239874be87bc96a74ba7804cfc3213ae0ea62a4b9a367d437fed337e0d0
 SHA512:
-  metadata.gz: 4d554890949ccc6009accdcac4f6740e43237192f075fee2345b8468edab548a32da307577967409922fe2275361bbf19ef89de51f3fc0bd89dbf3f09c9747d3
-  data.tar.gz: 6be04fb755999ece4ab602dbfe014257f61243542f3c36ffea3dd0984fd58f5d425a8f94d7d4fdc97664b275502c6a0c6220aae032db07c3e683e4888c49c79d
+  metadata.gz: f0d0e645d4d2929da2b0d2461459510759dab172192e7564be8dd2e57f2771ff86144f4fb8ece7fcbd04351ba2cc0ee08964ea7a0e07d65485171718e7608a5c
+  data.tar.gz: d8678b98bd3978104dd2158ff04f3494ff291d690b75ecee4bc29121eb76d283fd378a1cb6f763f14904060a1e8cc9e39288dcc4ca7f8ab8420253fcbc1273e1

data/CHANGELOG.md

@@ -5,6 +5,55 @@ 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.3.0] - 2024-12-XX
+
+### 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
+- **BREAKING**: Removed unnecessary dependencies (selenium-webdriver, capybara from gemspec)
+- Gem now has minimal dependencies - only requires `axe-core-capybara`
+- Users provide their own capybara, selenium-webdriver, webdrivers in their Gemfile
+- This allows users to control their own driver configuration for RSpec system specs
+- CLI tool still works but requires users to have selenium-webdriver in their Gemfile if they want to use it
+
+## [1.1.6] - 2024-12-XX
+
+### Fixed
+- Added server readiness check with retry mechanism to prevent connection refused errors
+- CLI tool now waits up to 20 seconds for Rails server to be ready before attempting accessibility checks
+- Prevents race conditions when running in Procfile.dev where a11y process starts before web server
+
+## [1.1.5] - 2024-12-XX
+
+### Fixed
+- Fixed CLI tool "invalid argument" error when visiting paths by automatically converting paths to full URLs
+- CLI tool now properly constructs `http://localhost:PORT/path` URLs when using Selenium with Rails apps
+- Respects PORT, RAILS_PORT, and RAILS_URL environment variables for server URL configuration
+
 ## [1.1.4] - 2024-12-XX
 
 ### Fixed
@@ -88,6 +137,10 @@ 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
 [1.1.4]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.1.4
 [1.1.3]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.1.3
 [1.1.0]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.1.0

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.2.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
 ```
 
@@ -301,9 +303,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
@@ -119,7 +119,8 @@ module RailsAccessibilityTesting
         
         # Setup Capybara
         Capybara.default_driver = :selenium_chrome_headless
-        Capybara.app = Rails.application if defined?(Rails)
+        # Don't set Capybara.app when using Selenium - it needs a real HTTP server
+        # The Rails server should be running separately (e.g., via Procfile.dev)
         
         engine = Engine::RuleEngine.new(config: config)
         all_violations = []
@@ -130,10 +131,48 @@ module RailsAccessibilityTesting
         
         targets.each do |target|
           begin
-            Capybara.visit(target)
-            violations = engine.check(Capybara.current_session, context: { url: target })
+            # Convert path to full URL if needed (when using Selenium with Rails)
+            url = normalize_url(target)
+            
+            # Wait for server to be ready (with retries)
+            # 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
+                  $stderr.puts "Waiting for server to start... (will retry automatically)"
+                  next
+                end
+              end
+            end
+            
+            Capybara.visit(url)
+            violations = engine.check(Capybara.current_session, context: { url: url })
             all_violations.concat(violations)
-            checked_urls << { url: target, violations: violations.count }
+            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
@@ -168,6 +207,92 @@ module RailsAccessibilityTesting
         targets.uniq
       end
       
+      def normalize_url(target)
+        # If it's already a full URL, return as-is
+        return target if target.match?(/\Ahttps?:\/\//)
+        
+        # If it's a path and we're using Selenium, construct a full URL
+        # 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 /
+        path = target.start_with?('/') ? target : "/#{target}"
+        "#{base_url}#{path}"
+      end
+      
+      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'
+        
+        uri = URI.parse(url)
+        base_url = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+        
+        max_retries.times do |attempt|
+          begin
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.open_timeout = 2
+            http.read_timeout = 2
+            response = http.head('/')
+            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
+              begin
+                sleep(retry_delay)
+              rescue Interrupt
+                # Handle interrupt gracefully - return false to indicate failure
+                return false
+              end
+              next
+            else
+              # Last attempt failed
+              return false
+            end
+          rescue Interrupt
+            # Handle interrupt gracefully
+            return false
+          end
+        end
+        
+        false
+      end
+      
       def resolve_routes(routes)
         return [] unless defined?(Rails) && Rails.application
         
@@ -181,6 +306,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)
@@ -213,11 +343,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!"
@@ -251,7 +384,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,6 +48,12 @@ module RailsAccessibilityTesting
           # Run comprehensive accessibility checks
           instance = example.example_group_instance
           instance.check_comprehensive_accessibility
+          
+          # Show success message if checks passed (no exception was raised)
+          unless example.exception
+            $stdout.puts "\n✅ All comprehensive accessibility checks passed! (11 checks)"
+            $stdout.flush
+          end
         rescue StandardError => e
           example.set_exception(e)
         end

data/lib/rails_accessibility_testing/version.rb

@@ -1,4 +1,4 @@
 module RailsAccessibilityTesting
-  VERSION = "1.1.4"
+  VERSION = "1.3.0"
 end
 

data/lib/rails_accessibility_testing.rb

@@ -38,7 +38,7 @@ begin
   require_relative 'rails_accessibility_testing/version'
 rescue LoadError
   module RailsAccessibilityTesting
-    VERSION = '1.1.0'
+    VERSION = '1.3.0'
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_accessibility_testing
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.3.0
 platform: ruby
 authors:
 - Regan Maharjan
@@ -24,20 +24,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.0'
-- !ruby/object:Gem::Dependency
-  name: capybara
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -66,20 +52,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -94,34 +66,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
-- !ruby/object:Gem::Dependency
-  name: capybara
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: selenium-webdriver
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.0'
 description: Comprehensive, opinionated but configurable accessibility testing gem
   for Rails. Integrates seamlessly into your test suite with RSpec and Minitest support.
   Includes CLI tool, Rails generator, YAML configuration, and 11+ WCAG 2.1 AA aligned