rails_accessibility_testing 1.1.0

data/lib/rails_accessibility_testing/change_detector.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  # Detects if relevant files have changed to determine if accessibility checks should run
+  class ChangeDetector
+    # Time window for considering files as "recently changed" (in seconds)
+    CHANGE_WINDOW = 300 # 5 minutes
+
+    # Directories to monitor for changes
+    MONITORED_DIRECTORIES = %w[app/views app/controllers app/helpers].freeze
+
+    # View file extensions to check
+    VIEW_EXTENSIONS = %w[erb haml slim].freeze
+
+    class << self
+      # Check if relevant files have changed
+      # @param current_path [String] The current Rails path being tested
+      # @return [Boolean] true if files have changed, false otherwise
+      def files_changed?(current_path)
+        return false unless current_path
+
+        view_file = determine_view_file_from_path(current_path)
+        return true if view_file_recently_modified?(view_file)
+        return true if git_has_uncommitted_changes?
+        return true if any_monitored_files_recently_modified?
+
+        false
+      end
+
+      private
+
+      # Check if a specific view file was recently modified
+      def view_file_recently_modified?(view_file)
+        return false unless view_file && File.exist?(view_file)
+
+        File.mtime(view_file) > Time.now - CHANGE_WINDOW
+      end
+
+      # Check if git has uncommitted changes in monitored directories
+      def git_has_uncommitted_changes?
+        git_status = `git status --porcelain #{MONITORED_DIRECTORIES.join(' ')} 2>/dev/null`
+        git_status.strip.length.positive?
+      rescue StandardError
+        false # Git not available or not a git repo
+      end
+
+      # Check if any monitored files were recently modified
+      def any_monitored_files_recently_modified?
+        monitored_files.any? do |file|
+          File.exist?(file) && File.mtime(file) > Time.now - CHANGE_WINDOW
+        end
+      end
+
+      # Get all monitored files
+      def monitored_files
+        view_files + controller_files + helper_files
+      end
+
+      # Get all view files
+      def view_files
+        VIEW_EXTENSIONS.flat_map do |ext|
+          Dir.glob("app/views/**/*.#{ext}")
+        end
+      end
+
+      # Get all controller files
+      def controller_files
+        Dir.glob('app/controllers/**/*.rb')
+      end
+
+      # Get all helper files
+      def helper_files
+        Dir.glob('app/helpers/**/*.rb')
+      end
+
+      # Determine view file from Rails path
+      def determine_view_file_from_path(path)
+        return nil unless path
+
+        clean_path = path.split('?').first.split('#').first
+        return nil unless clean_path.start_with?('/')
+
+        parts = clean_path.sub(/\A\//, '').split('/')
+        return nil if parts.empty?
+
+        find_view_file(parts)
+      end
+
+      # Find view file based on path parts
+      def find_view_file(parts)
+        if parts.length >= 2
+          controller = parts[0..-2].join('/')
+          action = parts.last
+          find_view_for_action(controller, action)
+        elsif parts.length == 1
+          find_view_for_action(parts[0], 'index')
+        end
+      end
+
+      # Find view file for a specific controller and action
+      def find_view_for_action(controller, action)
+        view_paths = VIEW_EXTENSIONS.flat_map do |ext|
+          [
+            "app/views/#{controller}/#{action}.html.#{ext}",
+            "app/views/#{controller}/_#{action}.html.#{ext}"
+          ]
+        end
+
+        view_paths.find { |vp| File.exist?(vp) }
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/checks/aria_landmarks_check.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Checks for proper ARIA landmarks
+    #
+    # WCAG 2.1 AA: 1.3.1 Info and Relationships (Level A)
+    #
+    # @api private
+    class AriaLandmarksCheck < BaseCheck
+      def self.rule_name
+        :aria_landmarks
+      end
+      
+      def check
+        violations = []
+        
+        main_landmarks = page.all('main, [role="main"]', visible: true)
+        if main_landmarks.empty?
+          violations << violation(
+            message: "Page missing MAIN landmark",
+            element_context: { tag: 'page', text: 'Page has no MAIN landmark' },
+            wcag_reference: "1.3.1",
+            remediation: "Wrap main content in <main> tag:\n\n<main>\n  <%= yield %>\n</main>"
+          )
+        end
+        
+        violations
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/checks/base_check.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Base class for all accessibility checks
+    #
+    # Provides common functionality and defines the interface
+    # that all checks must implement.
+    #
+    # @abstract Subclass and implement {#check} to create a new check
+    #
+    # @example Creating a custom check
+    #   class MyCustomCheck < BaseCheck
+    #     def self.rule_name
+    #       :my_custom_check
+    #     end
+    #
+    #     def check
+    #       violations = []
+    #       # Check logic here
+    #       violations
+    #     end
+    #   end
+    #
+    # @api private
+    class BaseCheck
+      attr_reader :page, :context
+      
+      # Initialize the check
+      # @param page [Capybara::Session] The page to check
+      # @param context [Hash] Additional context (url, path, etc.)
+      def initialize(page:, context: {})
+        @page = page
+        @context = context
+      end
+      
+      # Run the check and return violations
+      # @return [Array<Engine::Violation>]
+      def run
+        check
+      end
+      
+      # The check implementation (must be overridden)
+      # @return [Array<Engine::Violation>]
+      def check
+        raise NotImplementedError, "Subclass must implement #check"
+      end
+      
+      # Rule name for this check (must be overridden)
+      # @return [Symbol]
+      def self.rule_name
+        raise NotImplementedError, "Subclass must implement .rule_name"
+      end
+      
+      protected
+      
+      # Create a violation
+      # @param message [String] Error message
+      # @param element_context [Hash] Element context
+      # @param wcag_reference [String] WCAG reference
+      # @param remediation [String] Suggested fix
+      # @return [Engine::Violation]
+      def violation(message:, element_context: {}, wcag_reference: nil, remediation: nil)
+        Engine::Violation.new(
+          rule_name: self.class.rule_name,
+          message: message,
+          element_context: element_context,
+          page_context: page_context,
+          wcag_reference: wcag_reference,
+          remediation: remediation
+        )
+      end
+      
+      # Get page context
+      # @return [Hash]
+      def page_context
+        {
+          url: safe_page_url,
+          path: safe_page_path,
+          view_file: determine_view_file
+        }
+      end
+      
+      # Get element context from Capybara element
+      # @param element [Capybara::Node::Element] The element
+      # @return [Hash]
+      def element_context(element)
+        {
+          tag: element.tag_name,
+          id: element[:id],
+          classes: element[:class],
+          href: element[:href],
+          src: element[:src],
+          text: element.text.strip,
+          parent: safe_parent_info(element)
+        }
+      end
+      
+      # Safely get page URL
+      def safe_page_url
+        page.current_url
+      rescue StandardError
+        nil
+      end
+      
+      # Safely get page path
+      def safe_page_path
+        page.current_path
+      rescue StandardError
+        nil
+      end
+      
+      # Safely get parent element info
+      def safe_parent_info(element)
+        parent = element.find(:xpath, '..')
+        {
+          tag: parent.tag_name,
+          id: parent[:id],
+          classes: parent[:class]
+        }
+      rescue StandardError
+        nil
+      end
+      
+      # Determine likely view file (simplified version)
+      def determine_view_file
+        return nil unless safe_page_path
+        
+        path = safe_page_path.split('?').first.split('#').first
+        
+        if defined?(Rails) && Rails.application
+          begin
+            route = Rails.application.routes.recognize_path(path)
+            controller = route[:controller]
+            action = route[:action]
+            
+            find_view_file_for_controller_action(controller, action)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+      
+      # Find view file for controller and action
+      def find_view_file_for_controller_action(controller, action)
+        extensions = %w[erb haml slim]
+        extensions.each do |ext|
+          view_path = "app/views/#{controller}/#{action}.html.#{ext}"
+          return view_path if File.exist?(view_path)
+        end
+        nil
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/checks/color_contrast_check.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Checks color contrast ratios for text elements
+    #
+    # Validates that text meets WCAG 2.1 AA contrast requirements:
+    # - Normal text: 4.5:1
+    # - Large text (18pt+ or 14pt+ bold): 3:1
+    #
+    # Note: This is a simplified check. Full contrast checking requires
+    # JavaScript evaluation of computed styles.
+    #
+    # @api private
+    class ColorContrastCheck < BaseCheck
+      def self.rule_name
+        :color_contrast
+      end
+      
+      def check
+        violations = []
+        
+        # This is a placeholder implementation
+        # Full contrast checking requires JavaScript to compute
+        # actual foreground/background colors from CSS
+        
+        # For now, we'll check for common contrast issues:
+        # - Text with low contrast classes
+        # - Inline styles with poor contrast
+        # - Elements that might have contrast issues
+        
+        page.all('*[style*="color"], *[class*="text-"], p, span, div, h1, h2, h3, h4, h5, h6', visible: true).each do |element|
+          # Check for inline styles that might indicate contrast issues
+          style = element[:style]
+          if style && style.match?(/color:\s*(?:#(?:fff|ffffff|000|000000)|rgb\(255,\s*255,\s*255\)|rgb\(0,\s*0,\s*0\))/i)
+            # This is a simplified check - real contrast checking needs computed styles
+            # For now, we'll just warn about potential issues
+            next # Skip for now - requires JS evaluation
+          end
+        end
+        
+        violations
+      end
+      
+      private
+      
+      # Calculate contrast ratio (simplified - would need actual color values)
+      def contrast_ratio(foreground, background)
+        # Placeholder - would need to convert colors to relative luminance
+        # and calculate: (L1 + 0.05) / (L2 + 0.05)
+        4.5 # Default to passing
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/checks/duplicate_ids_check.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Checks for duplicate IDs
+    #
+    # WCAG 2.1 AA: 4.1.1 Parsing (Level A)
+    #
+    # @api private
+    class DuplicateIdsCheck < BaseCheck
+      def self.rule_name
+        :duplicate_ids
+      end
+      
+      def check
+        violations = []
+        all_ids = page.all('[id]').map { |el| el[:id] }.compact
+        duplicates = all_ids.group_by(&:itself).select { |_k, v| v.length > 1 }.keys
+        
+        if duplicates.any?
+          first_duplicate_id = duplicates.first
+          first_element = page.first("[id='#{first_duplicate_id}']", wait: false)
+          
+          element_ctx = if first_element
+            ctx = element_context(first_element)
+            ctx[:duplicate_ids] = duplicates
+            ctx
+          else
+            {
+              tag: 'multiple',
+              id: first_duplicate_id,
+              duplicate_ids: duplicates
+            }
+          end
+          
+          violations << violation(
+            message: "Duplicate IDs found: #{duplicates.join(', ')}",
+            element_context: element_ctx,
+            wcag_reference: "4.1.1",
+            remediation: "Ensure each ID is unique on the page"
+          )
+        end
+        
+        violations
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/checks/form_errors_check.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Checks that form errors are associated with inputs
+    #
+    # WCAG 2.1 AA: 3.3.1 Error Identification (Level A)
+    #
+    # @api private
+    class FormErrorsCheck < BaseCheck
+      def self.rule_name
+        :form_errors
+      end
+      
+      def check
+        violations = []
+        
+        page.all('.field_with_errors input, .field_with_errors textarea, .field_with_errors select, .is-invalid, [aria-invalid="true"]').each do |input|
+          id = input[:id]
+          next if id.blank?
+          
+          has_error_message = page.has_css?("[aria-describedby*='#{id}'], .field_with_errors label[for='#{id}'] + .error, .field_with_errors label[for='#{id}'] + .invalid-feedback", wait: false)
+          
+          unless has_error_message
+            element_ctx = element_context(input)
+            violations << violation(
+              message: "Form input error message not associated",
+              element_context: element_ctx,
+              wcag_reference: "3.3.1",
+              remediation: "Associate error message with input using aria-describedby"
+            )
+          end
+        end
+        
+        violations
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/checks/form_labels_check.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Checks that form inputs have associated labels
+    #
+    # WCAG 2.1 AA: 1.3.1 Info and Relationships (Level A)
+    #
+    # @api private
+    class FormLabelsCheck < BaseCheck
+      def self.rule_name
+        :form_labels
+      end
+      
+      def check
+        violations = []
+        page_context = self.page_context
+        
+        page.all('input[type="text"], input[type="email"], input[type="password"], input[type="number"], input[type="tel"], input[type="url"], input[type="search"], input[type="date"], input[type="time"], input[type="datetime-local"], textarea, select').each do |input|
+          id = input[:id]
+          next if id.blank?
+          
+          has_label = page.has_css?("label[for='#{id}']", wait: false)
+          aria_label = input[:"aria-label"].present?
+          aria_labelledby = input[:"aria-labelledby"].present?
+          
+          unless has_label || aria_label || aria_labelledby
+            element_ctx = element_context(input)
+            element_ctx[:input_type] = input[:type] || input.tag_name
+            
+            violations << violation(
+              message: "Form input missing label",
+              element_context: element_ctx,
+              wcag_reference: "1.3.1",
+              remediation: generate_remediation(element_ctx)
+            )
+          end
+        end
+        
+        violations
+      end
+      
+      private
+      
+      def generate_remediation(element_context)
+        id = element_context[:id]
+        input_type = element_context[:input_type] || 'text'
+        
+        "Choose ONE of these solutions:\n\n" \
+        "1. Add a <label> element:\n" \
+        "   <label for=\"#{id}\">Field Label</label>\n" \
+        "   <input type=\"#{input_type}\" id=\"#{id}\" name=\"field_name\">\n\n" \
+        "2. Add aria-label attribute:\n" \
+        "   <input type=\"#{input_type}\" id=\"#{id}\" aria-label=\"Field Label\">\n\n" \
+        "3. Use Rails helper:\n" \
+        "   <%= form.label :field_name, 'Field Label' %>\n" \
+        "   <%= form.text_field :field_name, id: '#{id}' %>"
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/checks/heading_hierarchy_check.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Checks for proper heading hierarchy
+    #
+    # WCAG 2.1 AA: 1.3.1 Info and Relationships (Level A)
+    #
+    # @api private
+    class HeadingHierarchyCheck < BaseCheck
+      def self.rule_name
+        :heading_hierarchy
+      end
+      
+      def check
+        violations = []
+        headings = page.all('h1, h2, h3, h4, h5, h6', visible: true)
+        
+        if headings.empty?
+          return violations  # Warning only, not error
+        end
+        
+        h1_count = headings.count { |h| h.tag_name == 'h1' }
+        if h1_count == 0
+          violations << violation(
+            message: "Page missing H1 heading",
+            element_context: { tag: 'page', text: 'Page has no H1 heading' },
+            wcag_reference: "1.3.1",
+            remediation: "Add an <h1> heading to your page:\n\n<h1>Main Page Title</h1>"
+          )
+        end
+        
+        previous_level = 0
+        headings.each do |heading|
+          current_level = heading.tag_name[1].to_i
+          if current_level > previous_level + 1
+            element_ctx = element_context(heading)
+            violations << violation(
+              message: "Heading hierarchy skipped (h#{previous_level} to h#{current_level})",
+              element_context: element_ctx,
+              wcag_reference: "1.3.1",
+              remediation: "Fix the heading hierarchy. Don't skip levels."
+            )
+          end
+          previous_level = current_level
+        end
+        
+        violations
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/checks/image_alt_text_check.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Checks that images have alt attributes
+    #
+    # WCAG 2.1 AA: 1.1.1 Non-text Content (Level A)
+    #
+    # @api private
+    class ImageAltTextCheck < BaseCheck
+      def self.rule_name
+        :image_alt_text
+      end
+      
+      def check
+        violations = []
+        
+        page.all('img', visible: :all).each do |img|
+          has_alt_attribute = page.evaluate_script("arguments[0].hasAttribute('alt')", img.native)
+          
+          if has_alt_attribute == false
+            element_ctx = element_context(img)
+            
+            violations << violation(
+              message: "Image missing alt attribute",
+              element_context: element_ctx,
+              wcag_reference: "1.1.1",
+              remediation: generate_remediation(element_ctx)
+            )
+          end
+        end
+        
+        violations
+      end
+      
+      private
+      
+      def generate_remediation(element_context)
+        src = element_context[:src] || 'image.png'
+        
+        "Choose ONE of these solutions:\n\n" \
+        "1. Add alt text for informative images:\n" \
+        "   <img src=\"#{src}\" alt=\"Description of image\">\n\n" \
+        "2. Add empty alt for decorative images:\n" \
+        "   <img src=\"#{src}\" alt=\"\">\n\n" \
+        "3. Use Rails image_tag helper:\n" \
+        "   <%= image_tag 'image.png', alt: 'Description' %>"
+      end
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/checks/interactive_elements_check.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RailsAccessibilityTesting
+  module Checks
+    # Checks that interactive elements have accessible names
+    #
+    # WCAG 2.1 AA: 2.4.4 Link Purpose (Level A), 4.1.2 Name, Role, Value (Level A)
+    #
+    # @api private
+    class InteractiveElementsCheck < BaseCheck
+      def self.rule_name
+        :interactive_elements
+      end
+      
+      def check
+        violations = []
+        
+        page.all('button, a[href], [role="button"], [role="link"]').each do |element|
+          next unless element.visible?
+          
+          text = element.text.strip
+          aria_label = element[:"aria-label"]
+          aria_labelledby = element[:"aria-labelledby"]
+          title = element[:title]
+          
+          if text.blank? && aria_label.blank? && aria_labelledby.blank? && title.blank?
+            element_ctx = element_context(element)
+            tag = element.tag_name
+            
+            violations << violation(
+              message: "#{tag.capitalize} missing accessible name",
+              element_context: element_ctx,
+              wcag_reference: tag == 'a' ? "2.4.4" : "4.1.2",
+              remediation: generate_remediation(tag, element_ctx)
+            )
+          end
+        end
+        
+        violations
+      end
+      
+      private
+      
+      def generate_remediation(tag, element_context)
+        if tag == 'a'
+          "Choose ONE of these solutions:\n\n" \
+          "1. Add visible link text:\n" \
+          "   <%= link_to 'Descriptive Link Text', path %>\n\n" \
+          "2. Add aria-label (for icon-only links):\n" \
+          "   <%= link_to path, aria: { label: 'Descriptive action' } do %>\n" \
+          "     <i class='icon'></i>\n" \
+          "   <% end %>"
+        else
+          "Choose ONE of these solutions:\n\n" \
+          "1. Add visible button text:\n" \
+          "   <button>Descriptive Button Text</button>\n\n" \
+          "2. Add aria-label (for icon-only buttons):\n" \
+          "   <button aria-label='Descriptive action'>\n" \
+          "     <i class='icon'></i>\n" \
+          "   </button>"
+        end
+      end
+    end
+  end
+end
+