rails_accessibility_testing 1.1.0

data/lib/rails_accessibility_testing/checks/keyboard_accessibility_check.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Checks keyboard accessibility for modals
+    #
+    # WCAG 2.1 AA: 2.1.1 Keyboard (Level A)
+    #
+    # @api private
+    class KeyboardAccessibilityCheck < BaseCheck
+      def self.rule_name
+        :keyboard_accessibility
+      end
+      
+      def check
+        violations = []
+        
+        page.all('[role="dialog"], [role="alertdialog"]', visible: true).each do |modal|
+          focusable = modal.all('button, a, input, textarea, select, [tabindex]:not([tabindex="-1"])', visible: true)
+          if focusable.empty?
+            element_ctx = element_context(modal)
+            violations << violation(
+              message: "Modal dialog has no focusable elements",
+              element_context: element_ctx,
+              wcag_reference: "2.1.1",
+              remediation: "Add focusable elements to the modal (buttons, links, inputs)"
+            )
+          end
+        end
+        
+        violations
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/checks/skip_links_check.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Checks for skip links
+    #
+    # WCAG 2.1 AA: 2.4.1 Bypass Blocks (Level A)
+    #
+    # @api private
+    class SkipLinksCheck < BaseCheck
+      def self.rule_name
+        :skip_links
+      end
+      
+      def check
+        violations = []
+        # This is a warning-only check, so we return empty violations
+        # but could add a warning mechanism if needed
+        violations
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/checks/table_structure_check.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Checks for proper table structure
+    #
+    # WCAG 2.1 AA: 1.3.1 Info and Relationships (Level A)
+    #
+    # @api private
+    class TableStructureCheck < BaseCheck
+      def self.rule_name
+        :table_structure
+      end
+      
+      def check
+        violations = []
+        
+        page.all('table').each do |table|
+          has_headers = table.all('th').any?
+          unless has_headers
+            element_ctx = element_context(table)
+            violations << violation(
+              message: "Table missing headers",
+              element_context: element_ctx,
+              wcag_reference: "1.3.1",
+              remediation: "Add <th> headers to your table:\n\n<table>\n  <thead>\n    <tr><th>Column 1</th></tr>\n  </thead>\n</table>"
+            )
+          end
+        end
+        
+        violations
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/cli/command.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'json'
+
+module RailsAccessibilityTesting
+  module CLI
+    # Main CLI command for running accessibility checks
+    #
+    # Provides a command-line interface to run checks against
+    # URLs or Rails routes.
+    #
+    # @example
+    #   rails_a11y check /home /about
+    #   rails_a11y check --urls https://example.com
+    #   rails_a11y check --routes home_path about_path
+    #
+    class Command
+      def self.run(argv)
+        new.run(argv)
+      end
+      
+      def run(argv)
+        options = parse_options(argv)
+        
+        if options[:help]
+          print_help
+          return 0
+        end
+        
+        if options[:version]
+          print_version
+          return 0
+        end
+        
+        # Load configuration
+        config = load_config(options[:profile])
+        
+        # Run checks
+        results = run_checks(options, config)
+        
+        # Generate report
+        generate_report(results, options)
+        
+        results[:violations].any? ? 1 : 0
+      rescue StandardError => e
+        $stderr.puts "Error: #{e.message}"
+        $stderr.puts e.backtrace if options[:debug]
+        1
+      end
+      
+      private
+      
+      def parse_options(argv)
+        options = {
+          profile: :test,
+          format: :human,
+          output: nil,
+          debug: false
+        }
+        
+        OptionParser.new do |opts|
+          opts.banner = "Usage: rails_a11y [options] [paths...]"
+          
+          opts.on('-u', '--urls URL1,URL2', Array, 'Check specific URLs') do |urls|
+            options[:urls] = urls
+          end
+          
+          opts.on('-r', '--routes ROUTE1,ROUTE2', Array, 'Check Rails routes') do |routes|
+            options[:routes] = routes
+          end
+          
+          opts.on('-p', '--profile PROFILE', 'Configuration profile (development, test, ci)') do |profile|
+            options[:profile] = profile.to_sym
+          end
+          
+          opts.on('-f', '--format FORMAT', 'Output format (human, json)') do |format|
+            options[:format] = format.to_sym
+          end
+          
+          opts.on('-o', '--output FILE', 'Output file path') do |file|
+            options[:output] = file
+          end
+          
+          opts.on('--debug', 'Enable debug output') do
+            options[:debug] = true
+          end
+          
+          opts.on('-h', '--help', 'Show this help') do
+            options[:help] = true
+          end
+          
+          opts.on('-v', '--version', 'Show version') do
+            options[:version] = true
+          end
+        end.parse!(argv)
+        
+        # Remaining args are paths
+        options[:paths] = argv if argv.any?
+        
+        options
+      end
+      
+      def load_config(profile)
+        Config::YamlLoader.load(profile: profile)
+      end
+      
+      def run_checks(options, config)
+        require 'capybara'
+        require 'capybara/dsl'
+        require 'selenium-webdriver'
+        
+        # Setup Capybara
+        Capybara.default_driver = :selenium_chrome_headless
+        Capybara.app = Rails.application if defined?(Rails)
+        
+        engine = Engine::RuleEngine.new(config: config)
+        all_violations = []
+        checked_urls = []
+        
+        # Determine what to check
+        targets = determine_targets(options)
+        
+        targets.each do |target|
+          begin
+            Capybara.visit(target)
+            violations = engine.check(Capybara.current_session, context: { url: target })
+            all_violations.concat(violations)
+            checked_urls << { url: target, violations: violations.count }
+          rescue StandardError => e
+            $stderr.puts "Error checking #{target}: #{e.message}"
+          end
+        end
+        
+        {
+          violations: all_violations,
+          checked_urls: checked_urls,
+          summary: {
+            total_violations: all_violations.count,
+            urls_checked: checked_urls.count,
+            urls_with_violations: checked_urls.count { |u| u[:violations] > 0 }
+          }
+        }
+      end
+      
+      def determine_targets(options)
+        targets = []
+        
+        if options[:urls]
+          targets.concat(options[:urls])
+        end
+        
+        if options[:routes]
+          targets.concat(resolve_routes(options[:routes]))
+        end
+        
+        if options[:paths]
+          targets.concat(options[:paths])
+        end
+        
+        targets.uniq
+      end
+      
+      def resolve_routes(routes)
+        return [] unless defined?(Rails) && Rails.application
+        
+        routes.map do |route_name|
+          begin
+            Rails.application.routes.url_helpers.send(route_name)
+          rescue StandardError
+            nil
+          end
+        end.compact
+      end
+      
+      def generate_report(results, options)
+        output = case options[:format]
+                 when :json
+                   generate_json_report(results)
+                 else
+                   generate_human_report(results)
+                 end
+        
+        if options[:output]
+          File.write(options[:output], output)
+          puts "Report written to #{options[:output]}"
+        else
+          puts output
+        end
+      end
+      
+      def generate_human_report(results)
+        output = []
+        output << "=" * 70
+        output << "Rails A11y Accessibility Report"
+        output << "=" * 70
+        output << ""
+        output << "Summary:"
+        output << "  Total Violations: #{results[:summary][:total_violations]}"
+        output << "  URLs Checked: #{results[:summary][:urls_checked]}"
+        output << "  URLs with Issues: #{results[:summary][:urls_with_violations]}"
+        output << ""
+        
+        if results[:violations].any?
+          output << "Violations:"
+          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 << ""
+          end
+        else
+          output << "✅ No accessibility violations found!"
+        end
+        
+        output.join("\n")
+      end
+      
+      def generate_json_report(results)
+        {
+          summary: results[:summary],
+          violations: results[:violations].map(&:to_h),
+          checked_urls: results[:checked_urls]
+        }.to_json
+      end
+      
+      def print_help
+        puts <<~HELP
+          Rails A11y - Accessibility Testing for Rails
+          
+          Usage: rails_a11y [options] [paths...]
+          
+          Options:
+            -u, --urls URL1,URL2          Check specific URLs
+            -r, --routes ROUTE1,ROUTE2     Check Rails routes
+            -p, --profile PROFILE          Configuration profile (development, test, ci)
+            -f, --format FORMAT           Output format (human, json)
+            -o, --output FILE             Output file path
+            --debug                       Enable debug output
+            -h, --help                    Show this help
+            -v, --version                 Show version
+          
+          Examples:
+            rails_a11y check /home /about
+            rails_a11y --urls https://example.com
+            rails_a11y --routes home_path about_path --format json --output report.json
+        HELP
+      end
+      
+      def print_version
+        puts "Rails A11y #{RailsAccessibilityTesting::VERSION}"
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/config/yaml_loader.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module RailsAccessibilityTesting
+  module Config
+    # Loads and parses the accessibility.yml configuration file
+    #
+    # Supports profiles (development, test, ci) and rule overrides.
+    #
+    # @example Configuration file structure
+    #   # config/accessibility.yml
+    #   wcag_level: AA
+    #   
+    #   development:
+    #     checks:
+    #       color_contrast: false  # Skip in dev for speed
+    #   
+    #   ci:
+    #     checks:
+    #       color_contrast: true   # Full checks in CI
+    #
+    # @api private
+    class YamlLoader
+      DEFAULT_CONFIG_PATH = 'config/accessibility.yml'
+      
+      class << self
+        # Load configuration from YAML file
+        # @param path [String] Path to config file
+        # @param profile [Symbol] Profile to use (:development, :test, :ci)
+        # @return [Hash] Configuration hash
+        def load(path: DEFAULT_CONFIG_PATH, profile: :test)
+          config_path = resolve_config_path(path)
+          return default_config unless config_path && File.exist?(config_path)
+          
+          yaml_content = File.read(config_path)
+          parsed = YAML.safe_load(yaml_content, permitted_classes: [Symbol], aliases: true) || {}
+          
+          merge_profile_config(parsed, profile)
+        rescue StandardError => e
+          RailsAccessibilityTesting.config.logger&.warn("Failed to load config: #{e.message}") if defined?(RailsAccessibilityTesting)
+          default_config
+        end
+        
+        private
+        
+        # Resolve config path relative to Rails root
+        def resolve_config_path(path)
+          return path if Pathname.new(path).absolute?
+          
+          if defined?(Rails) && Rails.root
+            Rails.root.join(path).to_s
+          else
+            path
+          end
+        end
+        
+        # Merge profile-specific config with base config
+        def merge_profile_config(parsed, profile)
+          base_config = parsed.reject { |k, _| k.to_s.match?(/^(development|test|ci)$/) }
+          profile_config = parsed[profile.to_s] || parsed[profile] || {}
+          
+          # Deep merge checks configuration
+          checks = base_config['checks'] || {}
+          profile_checks = profile_config['checks'] || {}
+          
+          merged_checks = checks.merge(profile_checks)
+          
+          base_config.merge(
+            'checks' => merged_checks,
+            'profile' => profile.to_s,
+            'ignored_rules' => parse_ignored_rules(parsed, profile)
+          )
+        end
+        
+        # Parse ignored rules with comments
+        def parse_ignored_rules(parsed, profile)
+          ignored = []
+          
+          # Check base config
+          ignored.concat(parse_rule_overrides(parsed['ignored_rules'] || []))
+          
+          # Check profile-specific ignored rules
+          profile_config = parsed[profile.to_s] || parsed[profile] || {}
+          ignored.concat(parse_rule_overrides(profile_config['ignored_rules'] || []))
+          
+          ignored.uniq
+        end
+        
+        # Parse rule override entries
+        def parse_rule_overrides(overrides)
+          overrides.map do |override|
+            {
+              rule: override['rule'] || override[:rule],
+              reason: override['reason'] || override[:reason] || 'No reason provided',
+              comment: override['comment'] || override[:comment]
+            }
+          end.compact
+        end
+        
+        # Default configuration when no file exists
+        def default_config
+          {
+            'wcag_level' => 'AA',
+            'checks' => default_checks,
+            'ignored_rules' => [],
+            'profile' => 'test'
+          }
+        end
+        
+        # Default check configuration (all enabled)
+        def default_checks
+          {
+            'form_labels' => true,
+            'image_alt_text' => true,
+            'interactive_elements' => true,
+            'heading_hierarchy' => true,
+            'keyboard_accessibility' => true,
+            'aria_landmarks' => true,
+            'form_errors' => true,
+            'table_structure' => true,
+            'duplicate_ids' => true,
+            'skip_links' => true,
+            'color_contrast' => false  # Disabled by default (expensive)
+          }
+        end
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  # Configuration for the accessibility testing gem
+  #
+  # @example
+  #   RailsAccessibilityTesting.configure do |config|
+  #     config.auto_run_checks = true
+  #   end
+  #
+  # @attr [Boolean] auto_run_checks Whether to automatically run checks after system specs
+  class Configuration
+    attr_accessor :auto_run_checks
+
+    def initialize
+      @auto_run_checks = true
+    end
+  end
+
+  # Global configuration instance
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # Configure the gem
+  def self.configure
+    yield config if block_given?
+  end
+end
+

data/lib/rails_accessibility_testing/engine/rule_engine.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Engine
+    # Core rule engine that evaluates accessibility checks
+    #
+    # Coordinates check execution, applies configuration, and collects violations.
+    #
+    # @example
+    #   engine = RuleEngine.new(config: config)
+    #   violations = engine.check(page)
+    #
+    # @api private
+    class RuleEngine
+      attr_reader :config, :violation_collector
+      
+      # Initialize the rule engine
+      # @param config [Hash] Configuration hash from YamlLoader
+      def initialize(config:)
+        @config = config
+        @violation_collector = ViolationCollector.new
+        @checks = load_checks
+      end
+      
+      # Run all enabled checks against a page
+      # @param page [Capybara::Session] The page to check
+      # @param context [Hash] Additional context (url, path, etc.)
+      # @return [Array<Violation>] Array of violations found
+      def check(page, context: {})
+        @violation_collector.reset
+        
+        enabled_checks.each do |check_class|
+          next if rule_ignored?(check_class.rule_name)
+          
+          begin
+            check_instance = check_class.new(page: page, context: context)
+            violations = check_instance.run
+            @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)
+          end
+        end
+        
+        @violation_collector.violations
+      end
+      
+      private
+      
+      # Load all check classes
+      def load_checks
+        [
+          Checks::FormLabelsCheck,
+          Checks::ImageAltTextCheck,
+          Checks::InteractiveElementsCheck,
+          Checks::HeadingHierarchyCheck,
+          Checks::KeyboardAccessibilityCheck,
+          Checks::AriaLandmarksCheck,
+          Checks::FormErrorsCheck,
+          Checks::TableStructureCheck,
+          Checks::DuplicateIdsCheck,
+          Checks::SkipLinksCheck,
+          Checks::ColorContrastCheck
+        ]
+      end
+      
+      # Get enabled checks based on configuration
+      def enabled_checks
+        @checks.select do |check_class|
+          check_enabled?(check_class.rule_name)
+        end
+      end
+      
+      # Check if a specific check is enabled
+      def check_enabled?(rule_name)
+        checks_config = @config['checks'] || {}
+        check_key = rule_name_to_config_key(rule_name)
+        checks_config.fetch(check_key, true) # Default to enabled
+      end
+      
+      # Check if a rule is in the ignored list
+      def rule_ignored?(rule_name)
+        ignored_rules = @config['ignored_rules'] || []
+        ignored_rules.any? { |override| override[:rule] == rule_name || override['rule'] == rule_name }
+      end
+      
+      # Convert rule name to config key
+      def rule_name_to_config_key(rule_name)
+        rule_name.to_s
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/engine/violation.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Engine
+    # Represents a single accessibility violation
+    #
+    # Contains all information needed to understand and fix the issue.
+    #
+    # @example
+    #   violation = Violation.new(
+    #     rule_name: 'form_labels',
+    #     message: 'Form input missing label',
+    #     element: element,
+    #     page_context: { url: '/', path: '/' }
+    #   )
+    #
+    # @api private
+    class Violation
+      attr_reader :rule_name, :message, :element_context, :page_context, :wcag_reference, :remediation
+      
+      # Initialize a violation
+      # @param rule_name [String, Symbol] Name of the rule that was violated
+      # @param message [String] Human-readable error message
+      # @param element_context [Hash] Context about the element with the issue
+      # @param page_context [Hash] Context about the page being tested
+      # @param wcag_reference [String] WCAG reference (e.g., "1.1.1")
+      # @param remediation [String] Suggested fix
+      def initialize(rule_name:, message:, element_context: {}, page_context: {}, wcag_reference: nil, remediation: nil)
+        @rule_name = rule_name.to_s
+        @message = message
+        @element_context = element_context
+        @page_context = page_context
+        @wcag_reference = wcag_reference
+        @remediation = remediation
+      end
+      
+      # Convert to hash for JSON serialization
+      # @return [Hash]
+      def to_h
+        {
+          rule_name: @rule_name,
+          message: @message,
+          element_context: @element_context,
+          page_context: @page_context,
+          wcag_reference: @wcag_reference,
+          remediation: @remediation
+        }
+      end
+      
+      # Convert to JSON string
+      # @return [String]
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+  end
+end
+