rails_accessibility_testing 1.5.7 → 1.5.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fee81eff828caeb719396eaf7a2e63d282b71b5490ffe192ec6600715fee9a1
-  data.tar.gz: 418f0068868d27e49c6916ff81da722bda53e6cad97504f43a36f3b98b64ba21
+  metadata.gz: 9f8824e08bc8db71c7a6598998b44c6b39826f367398c8c98a1ef85366a044e2
+  data.tar.gz: bd9337c4b6b89deae25b1adfc9dbec92645c934703e930d5f5048c71a59117b5
 SHA512:
-  metadata.gz: 16dd572d50a671dc94d0cfaf62b0cc6988dd009d929e9e9f98ad38df482b1653d99c3d3d80b1bf3fc956a24d94ce6bb64853d184d130f1eb18181bc031a4df2a
-  data.tar.gz: 6cbd86e0ea02ba00c5d297ffe44c941366f17592cc81b3b02e24ca65660bde2c784eb0f024411da9bbfd3d9598d168de141ae0df19dbe225f14de83766f94c7c
+  metadata.gz: cd9fdfced6342b861ae5d1db4ee852b4c566c9572d62dac463fdc0d7566d37ef1201201c36c3af4d45393d24af7f0a504f76f7eaf25322e7025a577eeb3d94dc
+  data.tar.gz: a2672850fd85a29fb3a304243f1367215c282a34e63df58f5878d274dd31176465afaad23734699124bd6649032b68ff578f0d6a1ae4b6ec853d2f4ffd7ef23c

data/CHANGELOG.md

@@ -5,6 +5,88 @@ 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.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
+- **ERB template detection**: Fixed false positives for empty headings and missing accessible names when ERB output tags (`<%= ... %>`) are present
+- **Static scanning**: ERB tags are now replaced with placeholder text so checks can detect that content will be present at runtime
+- **Scanner process management**: Static and live scanners now stay alive (sleep loop) when `enabled: false` instead of exiting, preventing Foreman from killing other processes
+
+### Added
+- **Global enable/disable flag**: Added `enabled` configuration option in `accessibility.yml` to completely disable all accessibility checks (manual and automatic)
+- **ERB content detection**: `ErbExtractor` now replaces `<%= ... %>` with `"ERB_CONTENT"` placeholder instead of removing it
+- **ERB-aware checks**: `HeadingCheck` and `InteractiveElementsCheck` now detect ERB placeholders and skip empty checks
+
+### Improved
+- **Static scanner behavior**: When `enabled: false`, scanner shows message and keeps running instead of exiting
+- **Live scanner behavior**: When `enabled: false`, scanner shows message and keeps running instead of exiting
+
 ## [1.5.7] - 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.
 

data/docs_site/getting_started.md

@@ -144,12 +144,12 @@ Rails Accessibility Testing runs **11 comprehensive checks** automatically. Thes
 1. **Form Labels** - All form inputs have associated labels
 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
+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)
 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.5.9
 
 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.
 

data/exe/a11y_live_scanner

@@ -29,6 +29,28 @@ begin
   unless defined?(RailsAccessibilityTesting::AccessibilityHelper)
     raise LoadError, "RailsAccessibilityTesting::AccessibilityHelper not found after requiring gem"
   end
+  
+  # Check if accessibility checks are globally disabled
+  begin
+    require 'rails_accessibility_testing/config/yaml_loader'
+    profile = defined?(Rails) && Rails.env.test? ? :test : :development
+    config = RailsAccessibilityTesting::Config::YamlLoader.load(profile: profile)
+    # 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 (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
+      # Sleep indefinitely until interrupted
+      loop do
+        sleep 60
+      end
+    end
+  rescue StandardError => e
+    # If config can't be loaded, continue (assume enabled)
+  end
 rescue LoadError => e
   $stderr.puts "❌ Error loading rails_accessibility_testing gem: #{e.message}"
   $stderr.puts "   Make sure the gem is installed: bundle install"

data/exe/a11y_static_scanner

@@ -23,6 +23,28 @@ begin
   require 'rails_accessibility_testing'
   require 'rails_accessibility_testing/static_file_scanner'
   require 'rails_accessibility_testing/file_change_tracker'
+  
+  # Check if accessibility checks are globally disabled
+  begin
+    require 'rails_accessibility_testing/config/yaml_loader'
+    profile = defined?(Rails) && Rails.env.test? ? :test : :development
+    config = RailsAccessibilityTesting::Config::YamlLoader.load(profile: profile)
+    # 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 (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
+      # Sleep indefinitely until interrupted
+      loop do
+        sleep 60
+      end
+    end
+  rescue StandardError => e
+    # If config can't be loaded, continue (assume enabled)
+  end
 rescue LoadError => e
   $stderr.puts "❌ Error loading rails_accessibility_testing gem: #{e.message}"
   $stderr.puts "   Make sure the gem is installed: bundle install"

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

@@ -3,6 +3,12 @@
 # This file configures accessibility checks for your Rails application.
 # See https://github.com/your-org/rails-a11y for full documentation.
 
+# 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
+accessibility_enabled: true
+
 # WCAG compliance level (A, AA, AAA)
 wcag_level: AA
 

data/lib/generators/rails_a11y/install/templates/all_pages_accessibility_spec.rb.erb

@@ -142,7 +142,7 @@ RSpec.describe 'All Pages Accessibility', type: :system do
           puts format_static_errors(errors, warnings)
           
           if errors.any?
-            raise "Found #{errors.length} accessibility error#{'s' if errors.length != 1} in #{view_file}"
+            puts "Found #{errors.length} accessibility error#{'s' if errors.length != 1} in #{view_file}"
           end
         else
           puts "✅ #{view_file}: No errors found"

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,7 +247,12 @@ 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
+    # Manual calls can use force: true to bypass the accessibility_enabled: false setting
+    return if !force && accessibility_disabled?
+    
     @accessibility_errors ||= []
     @accessibility_warnings ||= []
     
@@ -241,8 +283,15 @@ 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
+    # 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
+    
     # Note: Page scanning cache is disabled for RSpec tests to ensure accurate error reporting
     # The cache is only used in live scanner to avoid duplicate scans
     
@@ -433,6 +482,22 @@ module RailsAccessibilityTesting
 
   private
 
+  # Check if accessibility checks are globally disabled via config
+  def accessibility_disabled?
+    begin
+      require 'rails_accessibility_testing/config/yaml_loader'
+      profile = defined?(Rails) && Rails.env.test? ? :test : :development
+      config = RailsAccessibilityTesting::Config::YamlLoader.load(profile: profile)
+      # 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
+      # If config can't be loaded, assume enabled
+      false
+    end
+  end
+
   # Format timestamp for terminal output (shorter, more readable)
   def format_timestamp_for_terminal
     # Use just time for same-day reports, or full date if different day

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}."
@@ -82,8 +89,14 @@ module RailsAccessibilityTesting
         # Check 4: Empty headings (WCAG 4.1.2)
         headings.each do |heading|
           heading_text = heading.text.strip
+          
+          # Check if heading contains ERB placeholder (for static scanning)
+          # ErbExtractor replaces <%= ... %> with "ERB_CONTENT" so we can detect it
+          has_erb_content = heading_text.include?('ERB_CONTENT')
+          
           # Check if heading is empty or only contains whitespace/formatting
-          if heading_text.empty? || heading_text.match?(/^\s*$/)
+          # Skip if it contains ERB content (will be populated at runtime)
+          if (heading_text.empty? || heading_text.match?(/^\s*$/)) && !has_erb_content
             element_ctx = element_context(heading)
             violations << violation(
               message: "Empty heading detected (<#{heading.tag_name}>) - headings must have accessible text",

data/lib/rails_accessibility_testing/checks/interactive_elements_check.rb

@@ -46,16 +46,24 @@ module RailsAccessibilityTesting
           aria_labelledby = element[:"aria-labelledby"]
           title = element[:title]
           
+          # Check if element contains ERB placeholder (for static scanning)
+          # ErbExtractor replaces <%= ... %> with "ERB_CONTENT" so we can detect it
+          # If text includes "ERB_CONTENT", it means there's ERB code that will produce content at runtime
+          has_erb_content = text.include?('ERB_CONTENT')
+          
           # Check if element contains an image with alt text (common pattern for logo links)
           has_image_with_alt = false
-          if text.empty?
+          if text.empty? && !has_erb_content
             # For static scanning, we can't easily check images within elements
             # This check works better in dynamic scanning with Capybara
             # For now, skip image checking in static mode
             has_image_with_alt = false
           end
           
-          text_empty = text.empty?
+          # Text is empty only if it's actually empty AND doesn't contain ERB content
+          # If it contains ERB_CONTENT, it will have content at runtime, so it's not empty
+          text_empty = text.empty? && !has_erb_content
+          
           aria_label_empty = aria_label.nil? || aria_label.to_s.strip.empty?
           aria_labelledby_empty = aria_labelledby.nil? || aria_labelledby.to_s.strip.empty?
           title_empty = title.nil? || title.to_s.strip.empty?