rails_accessibility_testing 1.5.8 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: deb1a679b569b2ea1335bd383dd3c3c35a604291cd504acf83b02d6bc8093a33
-  data.tar.gz: beeb61ac0b6d7ba710485c03f340427943b5580e77b04c5d77b4b2ea2b395e16
+  metadata.gz: 232d290bc12c422c56aacad24fa16660eb12b3e106939fc6b4cac0a639740532
+  data.tar.gz: 2b5a248555626127007ef893c84bd10f8aac41e195dba54c86bebd7b1f4e1448
 SHA512:
-  metadata.gz: e5712af98873a226fe1d6b834e4c57983897787859adcd4613c24dafd4c2cd60ed9629b6b4865d595dadcfd2452e60766d4ac703a41ffe5ca98a5510801cc9c2
-  data.tar.gz: b3d7cad5a19ddd2b502e4e5a44721e8ecfb787c901ffe65d5904cd98daea202d5d4cd04c8da454f28158d98e2d5450166a6cee953681e762f9aad636c4c2f863
+  metadata.gz: 566c195bcf20d08247c58c97f11e8fe1158488d998a78eb12e293f9e70451db5076c0e314c1a383a2cdcdf5f50f9dd6c291665f2516c070cbf972de6c25ee186
+  data.tar.gz: 71e9fb76ac0b894e872397a7cc822a874acf33a32bf128c1a8ca7932a0ca283389b23534b567a5929652470239d565777de7d6a0113469eb1ac688331cbd8491

data/CHANGELOG.md

@@ -5,6 +5,99 @@ 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.6.0] - 2024-12-XX
+
+### Added
+- **Intelligent ERB Template Handling**: Enhanced ERB extractor to preserve dynamic ID structure from ERB templates
+- **Dynamic ID Support**: Static scanner now correctly handles checkbox/radio inputs with ERB-generated IDs (e.g., `collection_answers_<%= question.id %>_<%= option.id %>_`)
+- **Label Matching for Dynamic IDs**: Form labels check now correctly matches labels to inputs with dynamic IDs by preserving ERB placeholder structure
+- **Smart Duplicate ID Detection**: Duplicate ID check now excludes dynamic IDs with ERB placeholders, preventing false positives for checkbox/radio groups in loops
+
+### Fixed
+- Fixed false positive "Form input missing label [id: collection_answers]" for checkbox groups with dynamic IDs
+- Fixed false positive "Duplicate ID 'collection_answers' found" when IDs contain ERB expressions
+- Fixed missing accessible name detection for links with `href="#"` - now only flags links that truly lack accessible names (visible text, aria-label, or aria-labelledby)
+- Improved `label_tag` helper conversion to handle string interpolation in ID arguments
+- Enhanced raw HTML input element processing to preserve ERB structure in attributes
+
+### Changed
+- **ERB Extractor**: Now processes raw HTML elements with ERB in attributes before removing ERB tags, preserving dynamic ID structure
+- **Form Labels Check**: Updated to handle ERB placeholders in IDs when checking for associated labels
+- **Duplicate IDs Check**: Now filters out IDs containing `ERB_CONTENT` placeholders from duplicate detection
+- **Interactive Elements Check**: Enhanced to correctly detect accessible names for links with `href="#"`, avoiding false positives
+- **RSpec Test File**: Refactored `all_pages_accessibility_spec.rb` to extract formatting helper and add proper assertions that fail tests when errors are found
+
+### Documentation
+- Added comprehensive documentation on ERB template handling and dynamic ID processing
+- Updated architecture documentation with details on how dynamic IDs are preserved
+- Added examples and explanations for checkbox/radio groups with ERB-generated IDs
+
+## [1.5.10] - 2024-12-01
+
+### Changed
+- **Configuration flag renamed**: The `enabled` flag has been renamed to `accessibility_enabled` for better clarity. The old `enabled` key is still supported for backward compatibility.
+
+### Added
+- **Composed Page Scanning**: The static scanner now analyzes complete page compositions (layout + view + partials) for page-level accessibility checks, eliminating false positives for heading hierarchy, ARIA landmarks, duplicate IDs, and heading issues.
+- **View Composition Builder**: New comprehensive system that traces the complete page structure by finding all partials recursively across all directories in `app/views`.
+- **Exhaustive Partial Detection**: Enhanced partial detection that finds partials in any subdirectory, not just specific folders. Works for deeply nested namespaces (e.g., `collections/collection_questions`).
+- **ERB Content Detection**: Improved handling of ERB expressions (`<%= ... %>`) to prevent false positives for empty headings and missing accessible names on buttons.
+
+### Changed
+- **Heading Hierarchy Checks**: Now performed on the complete composed page instead of individual files, preventing false positives when H1 is in layout or partials.
+- **ARIA Landmarks Checks**: Now checks for `<main>` landmark across the entire composed page.
+- **Duplicate ID Checks**: Now checks for duplicate IDs across the complete page composition.
+- **Empty Heading Checks**: Now checks for empty headings across the complete composed page.
+- **Partial Search**: Enhanced to traverse ALL folders in `app/views` recursively using `Dir.glob`, making it a general solution that works for any folder structure.
+
+### Fixed
+- Fixed false positive for "Page missing MAIN landmark" when `<main>` is in the layout file.
+- Fixed false positive for "Page has h2 but no h1 heading" when H1 is in a partial rendered via `render @model`.
+- Fixed false positive for "Heading hierarchy skipped (h0 to h2)" when first heading is h2.
+- Fixed false positive for "Duplicate ID 'ERB_CONTENT'" by filtering out ERB placeholder strings.
+- Fixed partial detection for Rails shorthand patterns (`render @model`, `render collection: @models`).
+- Fixed namespaced partial path resolution (e.g., `layouts/_advance_search`).
+- Fixed path normalization to handle both relative and absolute paths consistently.
+
+### Performance
+- Optimized exhaustive directory search to return first match found instead of checking all matches.
+
+## [Unreleased]
+
+### Added
+- **Composed Page Scanning**: The static scanner now analyzes complete page compositions (layout + view + partials) for page-level accessibility checks, eliminating false positives for heading hierarchy, ARIA landmarks, duplicate IDs, and heading issues.
+- **View Composition Builder**: New comprehensive system that traces the complete page structure by finding all partials recursively across all directories in `app/views`.
+- **Exhaustive Partial Detection**: Enhanced partial detection that finds partials in any subdirectory, not just specific folders. Works for deeply nested namespaces (e.g., `collections/collection_questions`).
+- **ERB Content Detection**: Improved handling of ERB expressions (`<%= ... %>`) to prevent false positives for empty headings and missing accessible names on buttons.
+
+### Changed
+- **Heading Hierarchy Checks**: Now performed on the complete composed page instead of individual files, preventing false positives when H1 is in layout or partials.
+- **ARIA Landmarks Checks**: Now checks for `<main>` landmark across the entire composed page.
+- **Duplicate ID Checks**: Now checks for duplicate IDs across the complete page composition.
+- **Empty Heading Checks**: Now checks for empty headings across the complete composed page.
+- **Partial Search**: Enhanced to traverse ALL folders in `app/views` recursively using `Dir.glob`, making it a general solution that works for any folder structure.
+
+### Fixed
+- Fixed false positive for "Page missing MAIN landmark" when `<main>` is in the layout file.
+- Fixed false positive for "Page has h2 but no h1 heading" when H1 is in a partial rendered via `render @model`.
+- Fixed false positive for "Heading hierarchy skipped (h0 to h2)" when first heading is h2.
+- Fixed false positive for "Duplicate ID 'ERB_CONTENT'" by filtering out ERB placeholder strings.
+- Fixed partial detection for Rails shorthand patterns (`render @model`, `render collection: @models`).
+- Fixed namespaced partial path resolution (e.g., `layouts/_advance_search`).
+- Fixed path normalization to handle both relative and absolute paths consistently.
+
+### Performance
+- Optimized exhaustive directory search to return first match found instead of checking all matches.
+
+## [1.5.9] - 2024-12-01
+
+### Added
+- **Force option for manual checks**: Added `force: true` parameter to `check_comprehensive_accessibility` and `check_basic_accessibility` to bypass `enabled: false` setting
+- **Manual check flexibility**: You can now force manual checks to run even when accessibility checks are globally disabled
+
+### Improved
+- **Manual check documentation**: Clarified that manual checks can be run separately in RSpec specs regardless of configuration
+
 ## [1.5.8] - 2024-12-01
 
 ### Fixed

data/README.md

@@ -7,7 +7,7 @@
 
 **The RSpec + RuboCop of accessibility for Rails. Catch WCAG violations before they reach production.**
 
-**Current Version:** 1.5.5
+**Current Version:** 1.5.9
 
 📖 **[📚 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)
 
@@ -51,6 +51,13 @@ Rails Accessibility Testing fills a critical gap in the Rails testing ecosystem.
 - **Accurate error counting**: Properly tracks and displays error/warning counts
 - **Persistent output**: Errors stay visible in terminal (no clearing)
 
+#### 🔍 Composed Page Scanning (NEW in 1.5.9+)
+- **Complete page analysis**: Analyzes full page composition (layout + view + partials) for page-level checks
+- **Eliminates false positives**: No more false positives when H1 is in layout or partials
+- **Exhaustive partial finding**: Traverses ALL folders recursively to find all partials
+- **Works for any structure**: General solution that works for any Rails folder structure (collections, items, profiles, loan_requests, etc.)
+- **Page-level checks**: Heading hierarchy, ARIA landmarks, duplicate IDs, and empty headings checked across complete page
+
 #### 🔍 Smart View File Detection
 - **Intelligent matching**: Automatically finds view files even when action names don't match
 - **Controller directory scanning**: Searches all view files to find the correct template
@@ -61,6 +68,7 @@ Rails Accessibility Testing fills a critical gap in the Rails testing ecosystem.
 - **Optimized DOM queries**: Faster image alt checks without JavaScript evaluation
 - **Removed delays**: Eliminated unnecessary sleep calls in live scanner
 - **Efficient scanning**: ~25-30% faster page scans
+- **Optimized directory search**: Returns first match found instead of checking all matches
 
 #### 🎨 Enhanced Developer Experience
 - **Real-time progress**: Step-by-step feedback during accessibility checks

data/docs_site/architecture.md

@@ -3,7 +3,45 @@ layout: default
 title: Architecture
 ---
 
-# Architecture Overview
+# Architecture
+
+## Composed Page Scanning
+
+The gem now uses **composed page scanning** for page-level accessibility checks. This ensures that checks like heading hierarchy, ARIA landmarks, and duplicate IDs are evaluated against the complete rendered page (layout + view + partials), not individual files.
+
+### View Composition Builder
+
+The `ViewCompositionBuilder` class traces the complete page structure:
+
+1. **Finds Layout File**: Identifies the layout file (defaults to `application.html.erb`)
+2. **Finds View File**: The main view file being rendered
+3. **Recursively Finds Partials**: Discovers all partials rendered in the view, including:
+   - Partials in the same directory
+   - Partials in `layouts/`, `shared/`, `application/`
+   - Partials in any subdirectory (exhaustive search)
+   - Nested partials (partials within partials)
+
+### Partial Detection
+
+The gem detects all Rails render patterns:
+- `render 'partial'`
+- `render partial: 'partial'`
+- `render @model` (Rails shorthand)
+- `render collection: @models`
+- `render partial: 'item', collection: @items`
+- `render partial: 'form', locals: {...}`
+
+### Exhaustive Folder Traversal
+
+The partial search traverses ALL folders in `app/views` recursively using `Dir.glob`, ensuring partials are found regardless of their location:
+- `app/views/collections/`
+- `app/views/collections/collection_questions/`
+- `app/views/items/`
+- `app/views/profiles/`
+- `app/views/loan_requests/`
+- Any other nested structure
+
+This makes it a general solution that works for any Rails application structure. Overview
 
 This guide explains how Rails Accessibility Testing works under the hood in simple terms.
 
@@ -129,6 +167,61 @@ graph TB
     style Report fill:#ffeaa7
 ```
 
+### ERB Template Handling and Dynamic IDs
+
+The static scanner intelligently handles ERB templates with dynamic content, particularly for form inputs with dynamic IDs.
+
+#### How Dynamic IDs Are Preserved
+
+When the scanner encounters ERB templates with dynamic IDs, it preserves the structure instead of collapsing them:
+
+**Example ERB Template:**
+```erb
+<% question.collection_options.each do |option| %>
+  <input type="checkbox" 
+         id="collection_answers_<%= question.id %>_<%= option.id %>_"
+         name="collection_answers[<%= question.id %>][]" />
+  <%= label_tag "collection_answers_#{question.id}_#{option.id}_", option.value %>
+<% end %>
+```
+
+**How It's Processed:**
+- ERB expressions (`<%= question.id %>`, `<%= option.id %>`) are replaced with `ERB_CONTENT` placeholders
+- The structure is preserved: `collection_answers_ERB_CONTENT_ERB_CONTENT_`
+- This allows the scanner to correctly match inputs with their labels, even when IDs are dynamic
+
+#### Label Matching with Dynamic IDs
+
+The **Form Labels Check** correctly matches labels to inputs with dynamic IDs:
+- Input: `id="collection_answers_ERB_CONTENT_ERB_CONTENT_"`
+- Label: `for="collection_answers_ERB_CONTENT_ERB_CONTENT_"`
+- ✅ **Match found** - The scanner recognizes these as matching pairs
+
+#### Duplicate ID Detection
+
+The **Duplicate IDs Check** intelligently handles dynamic IDs:
+- IDs containing `ERB_CONTENT` are excluded from duplicate checking
+- These represent dynamic IDs that will have different values at runtime
+- Only static IDs (without ERB placeholders) are checked for duplicates
+- This prevents false positives for checkbox/radio groups in loops
+
+#### Links with href="#"
+
+The **Interactive Elements Check** correctly handles anchor links:
+- Only flags links with `href="#"` that have **no accessible name**
+- An accessible name can be: visible text, `aria-label`, or `aria-labelledby`
+- Links with `href="#"` that have proper labeling are **not flagged** (avoids false positives)
+
+**Example - Valid (not flagged):**
+```erb
+<%= link_to "Click me", "#", aria: { label: "Navigate to section" } %>
+```
+
+**Example - Invalid (flagged):**
+```erb
+<a href="#"></a>  <!-- No text, no aria-label, no aria-labelledby -->
+```
+
 ---
 
 ## Configuration & Profiles

data/docs_site/getting_started.md

@@ -142,14 +142,20 @@ end
 Rails Accessibility Testing runs **11 comprehensive checks** automatically. These checks are WCAG 2.1 AA aligned:
 
 1. **Form Labels** - All form inputs have associated labels
+   - ✅ Correctly handles dynamic IDs from ERB templates (e.g., `collection_answers_<%= question.id %>_<%= option.id %>_`)
+   - ✅ Matches labels to inputs even when IDs contain ERB expressions
 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 without skipping levels
+   - ✅ Only flags links with `href="#"` that have no accessible name (visible text, `aria-label`, or `aria-labelledby`)
+   - ✅ Avoids false positives for valid anchor links with proper labeling
+4. **Heading Hierarchy** - Proper h1-h6 structure without skipping levels (checked across complete page: layout + view + partials)
 5. **Keyboard Accessibility** - All interactive elements are keyboard accessible
-6. **ARIA Landmarks** - Proper use of ARIA landmark roles
+6. **ARIA Landmarks** - Proper use of ARIA landmark roles (checked across complete page: layout + view + partials)
 7. **Form Error Associations** - Form errors are properly linked to form fields
 8. **Table Structure** - Tables have proper headers
-9. **Duplicate IDs** - No duplicate ID attributes
+9. **Duplicate IDs** - No duplicate ID attributes (checked across complete page: layout + view + partials)
+   - ✅ Intelligently excludes dynamic IDs with ERB placeholders from duplicate checking
+   - ✅ Prevents false positives for checkbox/radio groups in loops
 10. **Skip Links** - Skip navigation links present
 11. **Color Contrast** - Text meets WCAG contrast requirements (optional, disabled by default)
 

data/docs_site/index.md

@@ -7,7 +7,7 @@ title: Home
 
 **The RSpec + RuboCop of accessibility for Rails. Catch WCAG violations before they reach production.**
 
-**Version:** 1.5.5
+**Version:** 1.6.0
 
 Rails Accessibility Testing is a comprehensive, opinionated but configurable gem that makes accessibility testing as natural as unit testing. It integrates seamlessly into your Rails workflow, catching accessibility issues as you code—not after deployment.
 
@@ -36,6 +36,10 @@ Rails Accessibility Testing fills a critical gap in the Rails testing ecosystem.
 - **Continuous monitoring**: Watches for file changes and re-scans automatically
 - **YAML configuration**: Fully configurable via `config/accessibility.yml`
 - **Reuses existing checks**: Leverages all 11 accessibility checks via RuleEngine
+- **Intelligent ERB handling**: Correctly processes dynamic IDs and ERB expressions
+  - Preserves structure of dynamic IDs (e.g., `collection_answers_<%= question.id %>_<%= option.id %>_`)
+  - Matches labels to inputs with dynamic IDs
+  - Excludes dynamic IDs from duplicate checking (prevents false positives)
 
 #### 🎯 Live Accessibility Scanner
 - **Real-time scanning**: Automatically scans pages as you browse during development
@@ -140,15 +144,15 @@ This will:
 
 The gem automatically runs **11 comprehensive accessibility checks**:
 
-1. ✅ **Form Labels** - All form inputs have associated labels
+1. ✅ **Form Labels** - All form inputs have associated labels (handles dynamic IDs from ERB templates)
 2. ✅ **Image Alt Text** - All images have descriptive alt attributes
-3. ✅ **Interactive Elements** - Buttons, links have accessible names (including links with images that have alt text)
+3. ✅ **Interactive Elements** - Buttons, links have accessible names (including links with images that have alt text; correctly handles links with `href="#"`)
 4. ✅ **Heading Hierarchy** - Proper h1-h6 structure (detects missing h1, multiple h1s, skipped levels, and h2+ without h1)
 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
+9. ✅ **Duplicate IDs** - No duplicate ID attributes (intelligently handles dynamic IDs from ERB templates)
 10. ✅ **Skip Links** - Skip navigation links present (detects various patterns)
 11. ✅ **Color Contrast** - Text meets contrast requirements (optional)
 

data/exe/a11y_live_scanner

@@ -35,10 +35,11 @@ begin
     require 'rails_accessibility_testing/config/yaml_loader'
     profile = defined?(Rails) && Rails.env.test? ? :test : :development
     config = RailsAccessibilityTesting::Config::YamlLoader.load(profile: profile)
-    enabled = config.fetch('enabled', true)
+    # Support both 'accessibility_enabled' (new) and 'enabled' (legacy) for backward compatibility
+    enabled = config.fetch('accessibility_enabled', config.fetch('enabled', true))
     unless enabled
-      puts "⏸️  Accessibility checks are disabled (enabled: false in config/accessibility.yml)"
-      puts "   Set enabled: true to enable accessibility scanning"
+      puts "⏸️  Accessibility checks are disabled (accessibility_enabled: false in config/accessibility.yml)"
+      puts "   Set accessibility_enabled: true to enable accessibility scanning"
       puts "   Scanner process will remain running but will not scan files"
       puts ""
       # Keep process alive so Foreman doesn't kill other processes

data/exe/a11y_static_scanner

@@ -29,10 +29,11 @@ begin
     require 'rails_accessibility_testing/config/yaml_loader'
     profile = defined?(Rails) && Rails.env.test? ? :test : :development
     config = RailsAccessibilityTesting::Config::YamlLoader.load(profile: profile)
-    enabled = config.fetch('enabled', true)
+    # Support both 'accessibility_enabled' (new) and 'enabled' (legacy) for backward compatibility
+    enabled = config.fetch('accessibility_enabled', config.fetch('enabled', true))
     unless enabled
-      puts "⏸️  Accessibility checks are disabled (enabled: false in config/accessibility.yml)"
-      puts "   Set enabled: true to enable accessibility scanning"
+      puts "⏸️  Accessibility checks are disabled (accessibility_enabled: false in config/accessibility.yml)"
+      puts "   Set accessibility_enabled: true to enable accessibility scanning"
       puts "   Scanner process will remain running but will not scan files"
       puts ""
       # Keep process alive so Foreman doesn't kill other processes

data/lib/generators/rails_a11y/install/templates/accessibility.yml.erb

@@ -3,11 +3,11 @@
 # This file configures accessibility checks for your Rails application.
 # See https://github.com/your-org/rails-a11y for full documentation.
 
-# Global enable/disable flag
+# Global enable/disable flag for all accessibility checks
 # Set to false to completely disable all accessibility checks (manual and automatic)
 # When false, check_comprehensive_accessibility and automatic checks will be skipped
 # Default: true
-enabled: true
+accessibility_enabled: true
 
 # WCAG compliance level (A, AA, AAA)
 wcag_level: AA

data/lib/rails_accessibility_testing/accessibility_helper.rb

@@ -46,14 +46,34 @@ module RailsAccessibilityTesting
         # render partial: "partial_name"
         # render 'path/to/partial'
         # render partial: 'path/to/partial'
+        # render @model (Rails shorthand - renders _model.html.erb)
+        # render collection: @models (renders _model.html.erb for each)
+        # render partial: 'partial', locals: {...}
+        # render partial: 'partial', collection: @items
         # <%= render 'partial_name' %>
         # <%= render partial: 'partial_name' %>
+        # <%= render @model %>
+        # <%= render collection: @models %>
         
         patterns = [
+          # Standard partial renders (with or without partial: keyword)
           /render\s+(?:partial:\s*)?['"]([^'"]+)['"]/,
           /render\s+(?:partial:\s*)?:(\w+)/,
           /<%=?\s*render\s+(?:partial:\s*)?['"]([^'"]+)['"]/,
-          /<%=?\s*render\s+(?:partial:\s*)?:(\w+)/
+          /<%=?\s*render\s+(?:partial:\s*)?:(\w+)/,
+          # Rails shorthand: render @model (renders _model.html.erb)
+          /render\s+@(\w+)/,
+          /<%=?\s*render\s+@(\w+)/,
+          # Collection renders: render collection: @models (renders _model.html.erb)
+          /render\s+collection:\s*@(\w+)/,
+          /<%=?\s*render\s+collection:\s*@(\w+)/,
+          # Partial with collection: render partial: 'item', collection: @items
+          /render\s+partial:\s*['"]([^'"]+)['"]\s*,\s*collection:/,
+          /<%=?\s*render\s+partial:\s*['"]([^'"]+)['"]\s*,\s*collection:/,
+          # Partial with locals: render partial: 'form', locals: {...}
+          # (extract just the partial name, ignore locals)
+          /render\s+partial:\s*['"]([^'"]+)['"]\s*,\s*locals:/,
+          /<%=?\s*render\s+partial:\s*['"]([^'"]+)['"]\s*,\s*locals:/
         ]
         
         patterns.each do |pattern|
@@ -77,6 +97,23 @@ module RailsAccessibilityTesting
           end
         end
         
+        # Also check for Rails shorthand: render @model (renders _model.html.erb)
+        # This is separate because it needs special handling
+        content.scan(/render\s+@(\w+)/) do |match|
+          model_name = match[0]
+          partial_name = model_name.underscore
+          partial_name = "_#{partial_name}" unless partial_name.start_with?('_')
+          partials << partial_name unless partials.include?(partial_name)
+        end
+        
+        # Check for collection renders: render collection: @models
+        content.scan(/render\s+collection:\s*@(\w+)/) do |match|
+          model_name = match[0]
+          partial_name = model_name.underscore.singularize  # collection uses singular
+          partial_name = "_#{partial_name}" unless partial_name.start_with?('_')
+          partials << partial_name unless partials.include?(partial_name)
+        end
+        
         partials
       end
       
@@ -210,9 +247,11 @@ module RailsAccessibilityTesting
   end
 
   # Basic accessibility check - runs 5 basic checks
-  def check_basic_accessibility
+  # @param force [Boolean] If true, bypasses the accessibility_enabled: false setting (default: false)
+  def check_basic_accessibility(force: false)
     # Check if accessibility checks are globally disabled
-    return if accessibility_disabled?
+    # Manual calls can use force: true to bypass the accessibility_enabled: false setting
+    return if !force && accessibility_disabled?
     
     @accessibility_errors ||= []
     @accessibility_warnings ||= []
@@ -244,10 +283,12 @@ module RailsAccessibilityTesting
 
   # Full comprehensive check - runs all 11 checks including advanced
   # Uses the RuleEngine and checks from the checks/ folder for consistency
+  # @param force [Boolean] If true, bypasses the accessibility_enabled: false setting (default: false)
   # @return [Hash] Hash with :errors and :warnings counts
-  def check_comprehensive_accessibility
+  def check_comprehensive_accessibility(force: false)
     # Check if accessibility checks are globally disabled - do this FIRST before any output
-    if accessibility_disabled?
+    # Manual calls can use force: true to bypass the accessibility_enabled: false setting
+    if !force && accessibility_disabled?
       return { errors: 0, warnings: 0, page_context: {} }
     end
     
@@ -447,7 +488,8 @@ module RailsAccessibilityTesting
       require 'rails_accessibility_testing/config/yaml_loader'
       profile = defined?(Rails) && Rails.env.test? ? :test : :development
       config = RailsAccessibilityTesting::Config::YamlLoader.load(profile: profile)
-      enabled = config.fetch('enabled', true)  # Default to enabled if not specified
+      # Support both 'accessibility_enabled' (new) and 'enabled' (legacy) for backward compatibility
+      enabled = config.fetch('accessibility_enabled', config.fetch('enabled', true))  # Default to enabled if not specified
       disabled = !enabled  # Return true if disabled
       disabled
     rescue StandardError => e

data/lib/rails_accessibility_testing/checks/duplicate_ids_check.rb

@@ -6,6 +6,13 @@ module RailsAccessibilityTesting
     #
     # WCAG 2.1 AA: 4.1.1 Parsing (Level A)
     #
+    # @note ERB template handling:
+    #   - IDs containing "ERB_CONTENT" placeholders are excluded from duplicate checking
+    #   - These are dynamic IDs that will have different values at runtime
+    #   - Example: "collection_answers_ERB_CONTENT_ERB_CONTENT_" represents a dynamic ID
+    #     that will be unique for each checkbox/radio option when rendered
+    #   - Static analysis cannot determine if dynamic IDs will be duplicates, so they are skipped
+    #
     # @api private
     class DuplicateIdsCheck < BaseCheck
       def self.rule_name
@@ -14,7 +21,11 @@ module RailsAccessibilityTesting
       
       def check
         violations = []
-        all_ids = page.all('[id]').map { |el| el[:id] }.compact
+        # Collect all IDs, filtering out those with ERB_CONTENT placeholders
+        # IDs with ERB_CONTENT are dynamic and can't be statically verified for duplicates
+        # Example: "collection_answers_ERB_CONTENT_ERB_CONTENT_" - the actual IDs will be different at runtime
+        # because the ERB expressions will evaluate to different values
+        all_ids = page.all('[id]').map { |el| el[:id] }.compact.reject { |id| id.include?('ERB_CONTENT') }
         duplicates = all_ids.group_by(&:itself).select { |_k, v| v.length > 1 }.keys
         
         if duplicates.any?

data/lib/rails_accessibility_testing/checks/form_labels_check.rb

@@ -6,6 +6,15 @@ module RailsAccessibilityTesting
     #
     # WCAG 2.1 AA: 1.3.1 Info and Relationships (Level A)
     #
+    # @note ERB template handling:
+    #   - Dynamic IDs with ERB placeholders (e.g., "collection_answers_ERB_CONTENT_ERB_CONTENT_")
+    #     are matched against labels with the same ERB structure
+    #   - ErbExtractor ensures that IDs and label "for" attributes with matching ERB patterns
+    #     will have the same "ERB_CONTENT" placeholder structure, allowing exact matching
+    #   - This correctly handles cases like:
+    #     <input id="collection_answers_<%= question.id %>_<%= option.id %>_">
+    #     <%= label_tag "collection_answers_#{question.id}_#{option.id}_", option.value %>
+    #
     # @api private
     class FormLabelsCheck < BaseCheck
       def self.rule_name
@@ -16,11 +25,21 @@ module RailsAccessibilityTesting
         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|
+        # Also check checkbox and radio inputs (they need labels too)
+        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"], input[type="checkbox"], input[type="radio"], textarea, select').each do |input|
           id = input[:id]
           next if id.nil? || id.to_s.strip.empty?
           
+          # Skip ERB_CONTENT placeholder - it's not a real ID, just a marker for dynamic content
+          next if id == 'ERB_CONTENT'
+          
+          # Check for label with matching for attribute
+          # Handle ERB placeholders in IDs: ErbExtractor preserves the structure of dynamic IDs
+          # so "collection_answers_<%= question.id %>_<%= option.id %>_" becomes
+          # "collection_answers_ERB_CONTENT_ERB_CONTENT_", and label_tag with the same pattern
+          # will also become "collection_answers_ERB_CONTENT_ERB_CONTENT_", so they should match exactly
           has_label = page.has_css?("label[for='#{id}']", wait: false)
+          
           aria_label = input[:"aria-label"]
           aria_labelledby = input[:"aria-labelledby"]
           has_aria_label = aria_label && !aria_label.to_s.strip.empty?

data/lib/rails_accessibility_testing/checks/heading_check.rb

@@ -23,7 +23,7 @@ module RailsAccessibilityTesting
           return violations  # Warning only, not error
         end
         
-        # Check 1: Missing H1
+        # Check 1: Missing H1 (page-level check - checks complete composed page)
         h1_count = headings.count { |h| h.tag_name == 'h1' }
         first_heading = headings.first
         first_heading_level = first_heading ? first_heading.tag_name[1].to_i : nil
@@ -32,30 +32,35 @@ module RailsAccessibilityTesting
           # If the first heading is h2 or higher, provide a more specific message
           if first_heading_level && first_heading_level >= 2
             element_ctx = element_context(first_heading)
+            # Mark as page-level check - H1 might be in layout or partial
+            element_ctx[:page_level_check] = true
+            element_ctx[:check_type] = 'heading_hierarchy'
             violations << violation(
-              message: "Page has h#{first_heading_level} but no h1 heading",
+              message: "Page has h#{first_heading_level} but no h1 heading (checked complete page: layout + view + partials)",
               element_context: element_ctx,
               wcag_reference: "1.3.1",
-              remediation: "Add an <h1> heading before the first h#{first_heading_level}:\n\n<h1>Main Page Title</h1>\n<h#{first_heading_level}>#{first_heading.text}</h#{first_heading_level}>"
+              remediation: "Add an <h1> heading to your page. The H1 can be in the layout, view, or a partial:\n\n<h1>Main Page Title</h1>\n<h#{first_heading_level}>#{first_heading.text}</h#{first_heading_level}>"
             )
           else
             violations << violation(
-              message: "Page missing H1 heading",
-              element_context: { tag: 'page', text: 'Page has no H1 heading' },
+              message: "Page missing H1 heading (checked complete page: layout + view + partials)",
+              element_context: { tag: 'page', text: 'Page has no H1 heading', page_level_check: true, check_type: 'heading_hierarchy' },
               wcag_reference: "1.3.1",
-              remediation: "Add an <h1> heading to your page:\n\n<h1>Main Page Title</h1>"
+              remediation: "Add an <h1> heading to your page. The H1 can be in the layout, view, or a partial:\n\n<h1>Main Page Title</h1>"
             )
           end
         end
         
-        # Check 2: Multiple H1s (WCAG 1.3.1)
+        # Check 2: Multiple H1s (WCAG 1.3.1) - page-level check
         if h1_count > 1
           # Report error for each h1 after the first one
           h1_elements = headings.select { |h| h.tag_name == 'h1' }
           h1_elements[1..-1].each do |h1|
             element_ctx = element_context(h1)
+            element_ctx[:page_level_check] = true
+            element_ctx[:check_type] = 'heading_hierarchy'
             violations << violation(
-              message: "Page has multiple h1 headings (#{h1_count} total) - only one h1 should be used per page",
+              message: "Page has multiple h1 headings (#{h1_count} total) - only one h1 should be used per page (checked complete page: layout + view + partials)",
               element_context: element_ctx,
               wcag_reference: "1.3.1",
               remediation: "Use only one <h1> per page. Convert additional h1s to h2 or lower:\n\n<h1>Main Title</h1>\n<h2>Section Title</h2>"
@@ -63,14 +68,16 @@ module RailsAccessibilityTesting
           end
         end
         
-        # Check 3: Heading hierarchy skipped levels (WCAG 1.3.1)
+        # Check 3: Heading hierarchy skipped levels (WCAG 1.3.1) - page-level check
         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)
+            element_ctx[:page_level_check] = true
+            element_ctx[:check_type] = 'heading_hierarchy'
             violations << violation(
-              message: "Heading hierarchy skipped (h#{previous_level} to h#{current_level})",
+              message: "Heading hierarchy skipped (h#{previous_level} to h#{current_level}) - checked complete page: layout + view + partials",
               element_context: element_ctx,
               wcag_reference: "1.3.1",
               remediation: "Fix the heading hierarchy. Don't skip levels. Use h#{previous_level + 1} instead of h#{current_level}."