rails_accessibility_testing 1.5.10 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f8824e08bc8db71c7a6598998b44c6b39826f367398c8c98a1ef85366a044e2
-  data.tar.gz: bd9337c4b6b89deae25b1adfc9dbec92645c934703e930d5f5048c71a59117b5
+  metadata.gz: 61344dc6a53b7678ea457fdfca0237fb7dfece5ef7825aaf0449fea1d187737d
+  data.tar.gz: c843795ff4c676607b4fde8d207a7055db5a9b128054583964843a6d41cc6ece
 SHA512:
-  metadata.gz: cd9fdfced6342b861ae5d1db4ee852b4c566c9572d62dac463fdc0d7566d37ef1201201c36c3af4d45393d24af7f0a504f76f7eaf25322e7025a577eeb3d94dc
-  data.tar.gz: a2672850fd85a29fb3a304243f1367215c282a34e63df58f5878d274dd31176465afaad23734699124bd6649032b68ff578f0d6a1ae4b6ec853d2f4ffd7ef23c
+  metadata.gz: c9e66513f4b0d427e8ae5d1dbd91d4aa1da7d6758d71993ce54cd8a1e083e241c297d76ea15dde99adab4b345165fd22d7ab7d070124fdd123dfa42eccaca049
+  data.tar.gz: 4b4a86455dd1e46c4f4b08c4edae141d49f533be9dd3ce86971a52ea4eb7e203b3a0c23e5730c78e04be31d36b0cfb315011201e479049302e9843e1655d74c3

data/CHANGELOG.md

@@ -5,6 +5,50 @@ 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).
 
+## [Unreleased]
+
+## [1.7.0] - 2026-02-11
+
+### Changed
+- **Generator Templates Updated**: Improved default configuration based on production best practices
+  - `accessibility.yml`: Changed `accessibility_enabled` default from `true` to `false` with detailed CI/CD documentation
+  - `rails_a11y.rb`: Added production safety guard (`if defined?(RailsAccessibilityTesting)`) and set `auto_run_checks = false` by default
+  - `all_pages_accessibility_spec.rb`: Changed RSpec type from `:system` to `:accessibility` and improved error formatting with unified helper method
+  - Updated documentation URLs to correct GitHub Pages link
+  - Generator now creates `spec/accessibility/` directory instead of `spec/system/` for better organization
+- **Best Practices Guide**: Added comprehensive [Best Practices guide](GUIDES/best_practices.md) documenting production-tested configuration patterns
+
+### Added
+- **[Best Practices Guide](GUIDES/best_practices.md)**: New guide documenting recommended configuration patterns based on real-world production usage, including CI/CD safety, production guards, and improved error formatting
+- **Template Updates Summary**: Added `TEMPLATE_UPDATES_SUMMARY.md` documenting all template improvements
+
+## [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

data/GUIDES/best_practices.md

@@ -0,0 +1,261 @@
+# Best Practices for Rails Accessibility Testing
+
+This guide documents recommended practices for configuring and using Rails Accessibility Testing in your Rails application, based on real-world usage and production experience.
+
+## Configuration Best Practices
+
+### 1. Disable by Default for CI/CD Safety
+
+**Recommended:** Set `accessibility_enabled: false` in `config/accessibility.yml`
+
+```yaml
+# config/accessibility.yml
+accessibility_enabled: false
+```
+
+**Why?**
+- Prevents accessibility test failures from blocking your entire CI/CD pipeline
+- Allows other RSpec tests to pass even if accessibility tests fail
+- Gives you control over when to run accessibility checks
+- Enables manual testing: `rspec spec/accessibility/all_pages_accessibility_spec.rb`
+
+**When to enable:**
+- Set to `true` when you want accessibility tests to run automatically
+- Use manual invocation for focused accessibility testing
+- Enable in CI only when you're ready to enforce accessibility compliance
+
+**Example:**
+```yaml
+# Default: false 
+#   (Set to false to allow other RSpec tests to pass in GitHub Actions CI even if accessibility tests fail.
+#    When true, any failing accessibility tests will cause the entire CI pipeline to fail.)
+# Set to true to run accessibility checks manually: rspec spec/accessibility/all_pages_accessibility_spec.rb
+accessibility_enabled: false
+```
+
+### 2. Production Safety Guard
+
+**Recommended:** Wrap configuration in conditional check
+
+```ruby
+# config/initializers/rails_a11y.rb
+if defined?(RailsAccessibilityTesting)
+  RailsAccessibilityTesting.configure do |config|
+    config.auto_run_checks = false
+    # ... other config
+  end
+end
+```
+
+**Why?**
+- Prevents errors if gem is not available in production
+- Allows gem to be excluded from production bundle
+- Safe deployment even if gem configuration is present
+
+### 3. Manual Control Over Automatic Checks
+
+**Recommended:** Set `auto_run_checks = false` in initializer
+
+```ruby
+config.auto_run_checks = false
+```
+
+**Why?**
+- Gives developers explicit control over when checks run
+- Prevents unexpected test failures during development
+- Allows focused accessibility testing when needed
+- Use `check_comprehensive_accessibility` explicitly in specs when desired
+
+**Alternative:** Enable per-environment
+```ruby
+config.auto_run_checks = Rails.env.development? || Rails.env.test?
+```
+
+### 4. Use Accessibility-Specific RSpec Type
+
+**Recommended:** Use `type: :accessibility` for accessibility specs
+
+```ruby
+RSpec.describe 'All Pages Accessibility', type: :accessibility do
+  # ...
+end
+```
+
+**Why?**
+- Proper RSpec integration with accessibility helpers
+- Better test organization and filtering
+- Clearer intent in test files
+
+### 5. Improved Error Formatting
+
+**Recommended:** Use unified formatting method for better output
+
+The generator now creates a `format_issues_by_file` helper method that:
+- Groups errors and warnings by file
+- Shows errors first, then warnings
+- Provides better structure and readability
+- Uses proper test assertions (`expect(errors).to be_empty`)
+
+## CI/CD Integration Best Practices
+
+### GitHub Actions
+
+**Recommended approach:**
+
+1. **Keep accessibility disabled by default:**
+   ```yaml
+   # config/accessibility.yml
+   accessibility_enabled: false
+   ```
+
+2. **Run accessibility tests separately:**
+   ```yaml
+   # .github/workflows/accessibility.yml
+   - name: Run accessibility tests
+     run: |
+       bundle exec rspec spec/accessibility/all_pages_accessibility_spec.rb
+     continue-on-error: true  # Don't block PRs initially
+   ```
+
+3. **Gradually enforce:**
+   - Start with `continue-on-error: true` to see results
+   - Fix existing issues
+   - Then set `continue-on-error: false` to enforce
+
+### Profile-Based Configuration
+
+Use different profiles for different environments:
+
+```yaml
+# config/accessibility.yml
+development:
+  checks:
+    color_contrast: false  # Skip expensive checks in dev
+
+test:
+  checks:
+    # Use global settings
+
+ci:
+  checks:
+    color_contrast: true   # Full checks in CI
+```
+
+Then set profile in CI:
+```bash
+RAILS_A11Y_PROFILE=ci bundle exec rspec spec/accessibility/
+```
+
+## Development Workflow Best Practices
+
+### 1. Use Static Scanner During Development
+
+Add to `Procfile.dev`:
+```procfile
+a11y: bundle exec a11y_static_scanner
+```
+
+**Benefits:**
+- Fast feedback without browser
+- Only scans changed files
+- Continuous monitoring as you code
+- Precise file locations and line numbers
+
+### 2. Manual Testing When Needed
+
+Run accessibility tests explicitly:
+```bash
+# Test all pages
+rspec spec/accessibility/all_pages_accessibility_spec.rb
+
+# Test specific page
+rspec spec/system/home_page_accessibility_spec.rb
+```
+
+### 3. Fix Issues Incrementally
+
+1. **Start with critical issues** - Focus on errors first
+2. **Fix by file** - Address all issues in one file at a time
+3. **Test incrementally** - Run tests after each fix
+4. **Document exceptions** - Use `ignored_rules` with reasons
+
+## Configuration File Best Practices
+
+### Documentation URLs
+
+Always use the correct documentation URL:
+```yaml
+# See https://rayraycodes.github.io/rails-accessibility-testing/ for full documentation.
+```
+
+### Comprehensive Comments
+
+Add detailed comments explaining decisions:
+```yaml
+# 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: false 
+#   (Set to false to allow other RSpec tests to pass in GitHub Actions CI even if accessibility tests fail.
+#    When true, any failing accessibility tests will cause the entire CI pipeline to fail.)
+# Set to true to run accessibility checks manually: rspec spec/accessibility/all_pages_accessibility_spec.rb
+accessibility_enabled: false
+```
+
+## Test Spec Best Practices
+
+### 1. Use Proper Test Assertions
+
+**Recommended:**
+```ruby
+if errors.any? || warnings.any?
+  expect(errors).to be_empty, format_static_errors(errors, warnings)
+else
+  puts "\n✅ #{view_file}: No errors found"
+end
+```
+
+**Why?**
+- Cleaner test output
+- Proper RSpec integration
+- Better error messages
+- Only fails on errors, not warnings
+
+### 2. Improved Error Formatting
+
+Use unified formatting method:
+```ruby
+def format_issues_by_file(issues_by_file, output, issue_type)
+  issues_by_file.each_with_index do |(file_path, file_issues), file_index|
+    output << "" if file_index > 0
+    output << "📝 #{file_path} (#{file_issues.length} #{issue_type}#{'s' if file_issues.length != 1})"
+    # ... format each issue
+  end
+end
+```
+
+**Benefits:**
+- Consistent formatting
+- Better readability
+- Easier to maintain
+
+## Summary
+
+These best practices are based on real-world production usage and help ensure:
+
+1. **CI/CD Safety** - Accessibility tests don't block other tests
+2. **Production Safety** - No errors if gem isn't available
+3. **Developer Control** - Explicit control over when checks run
+4. **Better UX** - Improved error formatting and test output
+5. **Incremental Adoption** - Easy to start and gradually enforce
+
+## Credits
+
+These best practices were refined based on contributions from:
+- **Margarita Barvinok** - Production configuration improvements
+- Real-world usage in Rails applications
+- Community feedback and testing
+
+---
+
+**Questions?** See the main [README](../README.md) or open an issue.

data/GUIDES/continuous_integration.md

@@ -280,6 +280,7 @@ Upload reports to:
 3. **Fail on violations** - Don't allow merging with issues
 4. **Report results** - Make status visible to team
 5. **Track trends** - Monitor violation counts over time
+6. **Disable by default** - Set `accessibility_enabled: false` in `config/accessibility.yml` to prevent accessibility tests from blocking other RSpec tests in CI. Enable manually when needed: `rspec spec/accessibility/all_pages_accessibility_spec.rb`
 
 ## Troubleshooting
 

data/README.md

@@ -447,6 +447,7 @@ Complete documentation site with all guides, examples, and API reference. The do
 ### Guides
 
 - **[System Specs for Accessibility](GUIDES/system_specs_for_accessibility.md)** - ⭐ **Recommended approach** - Using system specs for reliable accessibility testing
+- **[Best Practices](GUIDES/best_practices.md)** - ⭐ **Configuration recommendations** - Production-tested configuration patterns
 - **[Getting Started](GUIDES/getting_started.md)** - Quick start guide
 - **[Continuous Integration](GUIDES/continuous_integration.md)** - CI/CD setup
 - **[Writing Accessible Views](GUIDES/writing_accessible_views_in_rails.md)** - Best practices

data/docs_site/architecture.md

@@ -167,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
+   - ✅ 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 (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 (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.9
+**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/lib/generators/rails_a11y/install/install_generator.rb

@@ -43,7 +43,11 @@ module RailsA11y
       end
       
       def create_all_pages_spec
-        spec_path = 'spec/system/all_pages_accessibility_spec.rb'
+        # Create spec/accessibility directory if it doesn't exist
+        spec_dir = 'spec/accessibility'
+        FileUtils.mkdir_p(spec_dir) unless File.directory?(spec_dir)
+        
+        spec_path = 'spec/accessibility/all_pages_accessibility_spec.rb'
         
         if File.exist?(spec_path)
           say "⚠️  #{spec_path} already exists. Skipping creation.", :yellow
@@ -113,7 +117,7 @@ module RailsA11y
         say "\n📋 Next Steps:", :yellow
         say ""
         say "  1. Run the accessibility tests:", :cyan
-        say "     bundle exec rspec spec/system/all_pages_accessibility_spec.rb"
+        say "     bundle exec rspec spec/accessibility/all_pages_accessibility_spec.rb"
         say ""
         say "  2. For static file scanning during development:", :cyan
         say "     bin/dev  # Starts web server + static accessibility scanner"

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

@@ -1,13 +1,16 @@
 # Rails A11y Configuration
 #
 # This file configures accessibility checks for your Rails application.
-# See https://github.com/your-org/rails-a11y for full documentation.
+# See https://rayraycodes.github.io/rails-accessibility-testing/ 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
+# Default: false 
+#   (Set to false to allow other RSpec tests to pass in GitHub Actions CI even if accessibility tests fail.
+#    When true, any failing accessibility tests will cause the entire CI pipeline to fail.)
+# Set to true to run accessibility checks manually: rspec spec/accessibility/all_pages_accessibility_spec.rb
+accessibility_enabled: false
 
 # WCAG compliance level (A, AA, AAA)
 wcag_level: AA

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

@@ -1,6 +1,6 @@
 require 'rails_helper'
 
-RSpec.describe 'All Pages Accessibility', type: :system do
+RSpec.describe 'All Pages Accessibility', type: :accessibility do
   # Test all view files for accessibility using static file scanning
   # Generated automatically by rails_a11y:install generator
   
@@ -35,7 +35,7 @@ RSpec.describe 'All Pages Accessibility', type: :system do
     
     output = []
     
-    # Group errors by file
+    # Group errors and warnings by file
     errors_by_file = errors.group_by { |e| e[:file] }
     warnings_by_file = warnings.group_by { |w| w[:file] }
     
@@ -43,37 +43,8 @@ RSpec.describe 'All Pages Accessibility', type: :system do
     if errors.any?
       output << "\n" + "="*70
       output << "❌ #{errors.length} error#{'s' if errors.length != 1} found"
-      output << "="*70
       output << ""
-      
-      errors_by_file.each_with_index do |(file_path, file_errors), file_index|
-        output << "" if file_index > 0
-        
-        output << "📝 #{file_path} (#{file_errors.length} error#{'s' if file_errors.length != 1})"
-        
-        file_errors.each do |error|
-          error_line = "   • #{error[:type]}"
-          
-          # Add line number if available
-          if error[:line]
-            error_line += " [Line #{error[:line]}]"
-          end
-          
-          # Add element identifier
-          if error[:element][:id].present?
-            error_line += " [id: #{error[:element][:id]}]"
-          elsif error[:element][:href].present?
-            href_display = error[:element][:href].length > 30 ? "#{error[:element][:href][0..27]}..." : error[:element][:href]
-            error_line += " [href: #{href_display}]"
-          elsif error[:element][:src].present?
-            src_display = error[:element][:src].length > 30 ? "#{error[:element][:src][0..27]}..." : error[:element][:src]
-            error_line += " [src: #{src_display}]"
-          end
-          
-          output << error_line
-        end
-      end
-      
+      format_issues_by_file(errors_by_file, output, 'error')
       output << ""
       output << "="*70
     end
@@ -85,33 +56,7 @@ RSpec.describe 'All Pages Accessibility', type: :system do
       output << "="*70
       output << ""
       
-      warnings_by_file.each_with_index do |(file_path, file_warnings), file_index|
-        output << "" if file_index > 0
-        
-        output << "📝 #{file_path} (#{file_warnings.length} warning#{'s' if file_warnings.length != 1})"
-        
-        file_warnings.each do |warning|
-          warning_line = "   • #{warning[:type]}"
-          
-          # Add line number if available
-          if warning[:line]
-            warning_line += " [Line #{warning[:line]}]"
-          end
-          
-          # Add element identifier
-          if warning[:element][:id].present?
-            warning_line += " [id: #{warning[:element][:id]}]"
-          elsif warning[:element][:href].present?
-            href_display = warning[:element][:href].length > 30 ? "#{warning[:element][:href][0..27]}..." : warning[:element][:href]
-            warning_line += " [href: #{href_display}]"
-          elsif warning[:element][:src].present?
-            src_display = warning[:element][:src].length > 30 ? "#{warning[:element][:src][0..27]}..." : warning[:element][:src]
-            warning_line += " [src: #{src_display}]"
-          end
-          
-          output << warning_line
-        end
-      end
+      format_issues_by_file(warnings_by_file, output, 'warning')
       
       output << ""
       output << "="*70
@@ -119,6 +64,36 @@ RSpec.describe 'All Pages Accessibility', type: :system do
     
     output.join("\n")
   end
+
+  def format_issues_by_file(issues_by_file, output, issue_type)
+    issues_by_file.each_with_index do |(file_path, file_issues), file_index|
+      output << "" if file_index > 0
+      
+      output << "📝 #{file_path} (#{file_issues.length} #{issue_type}#{'s' if file_issues.length != 1})"
+      
+      file_issues.each do |issue|
+        issue_line = "   • #{issue[:type]}"
+        
+        # Add line number if available
+        if issue[:line]
+          issue_line += " [Line #{issue[:line]}]"
+        end
+        
+        # Add element identifier
+        if issue[:element][:id].present?
+          issue_line += " [id: #{issue[:element][:id]}]"
+        elsif issue[:element][:href].present?
+          href_display = issue[:element][:href].length > 30 ? "#{issue[:element][:href][0..27]}..." : issue[:element][:href]
+          issue_line += " [href: #{href_display}]"
+        elsif issue[:element][:src].present?
+          src_display = issue[:element][:src].length > 30 ? "#{issue[:element][:src][0..27]}..." : issue[:element][:src]
+          issue_line += " [src: #{src_display}]"
+        end
+        
+        output << issue_line
+      end
+    end
+  end
   
   # Scan all view files statically
   view_files = get_all_view_files
@@ -139,13 +114,9 @@ RSpec.describe 'All Pages Accessibility', type: :system do
         warnings = result[:warnings] || []
         
         if errors.any? || warnings.any?
-          puts format_static_errors(errors, warnings)
-          
-          if errors.any?
-            puts "Found #{errors.length} accessibility error#{'s' if errors.length != 1} in #{view_file}"
-          end
+          expect(errors).to be_empty, format_static_errors(errors, warnings)
         else
-          puts "✅ #{view_file}: No errors found"
+          puts "\n✅ #{view_file}: No errors found"
         end
       end
     end

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

@@ -4,12 +4,14 @@
 #
 # Configure accessibility testing behavior for your Rails application.
 #
-# @see https://github.com/your-org/rails-a11y for documentation
+# @see https://rayraycodes.github.io/rails-accessibility-testing/ for documentation
 
-RailsAccessibilityTesting.configure do |config|
-  # Automatically run checks after system specs
-  # Set to false to disable automatic checks
-  config.auto_run_checks = true
+# Only configure if the gem is available (not in production)
+if defined?(RailsAccessibilityTesting)
+  RailsAccessibilityTesting.configure do |config|
+    # Automatically run checks after system specs
+    # Set to false to disable automatic checks
+    config.auto_run_checks = false
   
   # Logger for accessibility check output
   # Set to nil to use default logger
@@ -18,7 +20,8 @@ RailsAccessibilityTesting.configure do |config|
   # Configuration file path (relative to Rails.root)
   # config.config_path = 'config/accessibility.yml'
   
-  # Default profile to use (development, test, ci)
-  # config.default_profile = :test
+    # Default profile to use (development, test, ci)
+    # config.default_profile = :test
+  end
 end
 

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/interactive_elements_check.rb

@@ -6,6 +6,12 @@ module RailsAccessibilityTesting
     #
     # WCAG 2.1 AA: 2.4.4 Link Purpose (Level A), 4.1.2 Name, Role, Value (Level A)
     #
+    # @note Links with href="#":
+    #   - Only flags anchors with href="#" that have NO accessible name
+    #   - An accessible name can be: visible text, aria-label, or aria-labelledby
+    #   - Links with href="#" that have visible text or ARIA attributes are valid and NOT flagged
+    #   - This avoids false positives for valid anchor links that use href="#" with proper labeling
+    #
     # @api private
     class InteractiveElementsCheck < BaseCheck
       def self.rule_name
@@ -45,6 +51,7 @@ module RailsAccessibilityTesting
           aria_label = element[:"aria-label"]
           aria_labelledby = element[:"aria-labelledby"]
           title = element[:title]
+          href = element[:href]
           
           # Check if element contains ERB placeholder (for static scanning)
           # ErbExtractor replaces <%= ... %> with "ERB_CONTENT" so we can detect it
@@ -68,12 +75,24 @@ module RailsAccessibilityTesting
           aria_labelledby_empty = aria_labelledby.nil? || aria_labelledby.to_s.strip.empty?
           title_empty = title.nil? || title.to_s.strip.empty?
           
+          # Only report violation if element has no accessible name
+          # For links with href="#", we only flag if they have no text AND no aria-label AND no aria-labelledby
+          # Links with href="#" that have visible text or ARIA attributes are valid and should not be flagged
           if text_empty && aria_label_empty && aria_labelledby_empty && title_empty && !has_image_with_alt
             element_ctx = element_context(element)
             tag = element.tag_name
             
+            # Special message for empty links with href="#"
+            # This rule correctly detects anchors with href="#" that have no accessible name,
+            # but avoids false positives when they have visible text or aria-label/aria-labelledby
+            message = if tag == 'a' && (href == '#' || href.to_s.strip == '#')
+              "Link missing accessible name [href: #]"
+            else
+              "#{tag.capitalize} missing accessible name"
+            end
+            
             violations << violation(
-              message: "#{tag.capitalize} missing accessible name",
+              message: message,
               element_context: element_ctx,
               wcag_reference: tag == 'a' ? "2.4.4" : "4.1.2",
               remediation: generate_remediation(tag, element_ctx)

data/lib/rails_accessibility_testing/composed_page_scanner.rb

@@ -203,6 +203,10 @@ module RailsAccessibilityTesting
           next if id.nil? || id.to_s.strip.empty?
           # Skip ERB_CONTENT placeholder - it's not a real ID
           next if id == 'ERB_CONTENT'
+          # Skip IDs that contain ERB_CONTENT - these are dynamic IDs that can't be statically verified
+          # Example: "collection_answers_ERB_CONTENT_ERB_CONTENT_" - the actual IDs will be different at runtime
+          # because the ERB expressions will evaluate to different values
+          next if id.include?('ERB_CONTENT')
           
           id_map[id] ||= []
           line = find_line_number_for_element(content, element)

data/lib/rails_accessibility_testing/erb_extractor.rb

@@ -4,6 +4,12 @@ module RailsAccessibilityTesting
   # Extracts HTML from ERB templates by converting Rails helpers to HTML
   # This allows static analysis of view files without rendering them
   #
+  # @note ERB and ID handling:
+  #   - Dynamic IDs like "collection_answers_<%= question.id %>_<%= option.id %>_" are preserved
+  #   - ERB expressions are replaced with "ERB_CONTENT" placeholder to maintain structure
+  #   - This ensures IDs like "collection_answers_ERB_CONTENT_ERB_CONTENT_" are not collapsed
+  #   - Labels with matching ERB structure will also have "ERB_CONTENT" and can be matched
+  #
   # @api private
   class ErbExtractor
     # Convert ERB template to HTML for static analysis
@@ -26,8 +32,57 @@ module RailsAccessibilityTesting
 
     private
 
+    # Convert raw HTML elements that have ERB in their attributes
+    # This handles cases like: <input id="collection_answers_<%= question.id %>_<%= option.id %>_">
+    # We need to preserve the structure of dynamic IDs so they don't get collapsed
+    # 
+    # @note This must run BEFORE remove_erb_tags to preserve ERB structure in attributes
+    def convert_raw_html_with_erb
+      # Handle input elements (checkbox, radio, text, etc.) with ERB in attributes
+      # Pattern: <input ... id="...<%= ... %>..." ... />
+      @content.gsub!(/<input\s+([^>]*?)>/i) do |match|
+        attrs = $1
+        # Replace ERB in attributes with placeholder, preserving structure
+        # This ensures "id='collection_answers_<%= question.id %>_<%= option.id %>_'" 
+        # becomes "id='collection_answers_ERB_CONTENT_ERB_CONTENT_'"
+        attrs_with_placeholders = attrs.gsub(/<%=(.*?)%>/m, 'ERB_CONTENT')
+        "<input #{attrs_with_placeholders}>"
+      end
+      
+      # Handle label_tag with string interpolation in first argument: <%= label_tag "collection_answers_#{question.id}_#{option.id}_", option.value %>
+      # This handles string interpolation like "collection_answers_#{question.id}_#{option.id}_"
+      # Must match BEFORE the simple string pattern
+      @content.gsub!(/<%=\s*label_tag\s+["']([^"']*#\{[^}]+\}[^"']*)["'],\s*([^,]+)(?:,\s*[^%]*)?%>/) do
+        id_template = $1
+        text_expr = $2
+        # Replace Ruby interpolation with placeholder
+        id_with_placeholder = id_template.gsub(/#\{[^}]+\}/, 'ERB_CONTENT')
+        # Handle text expression - could be a variable, string, or method call
+        text_placeholder = if text_expr.strip.match?(/^["']/)
+          # It's a string literal
+          text_expr.strip.gsub(/^["']|["']$/, '')
+        else
+          # It's a variable or method call - will produce content at runtime
+          'ERB_CONTENT'
+        end
+        "<label for=\"#{id_with_placeholder}\">#{text_placeholder}</label>"
+      end
+      
+      # Handle label_tag helper with simple string: <%= label_tag "id_string", "text", options %>
+      # Pattern: label_tag "id_string", "text", options
+      @content.gsub!(/<%=\s*label_tag\s+["']([^"']+)["'],\s*["']?([^"']*?)["']?[^%]*%>/) do
+        id = $1
+        text = $2
+        # Replace ERB in id string with placeholder (if any)
+        id_with_placeholder = id.gsub(/<%=(.*?)%>/m, 'ERB_CONTENT')
+        "<label for=\"#{id_with_placeholder}\">#{text}</label>"
+      end
+    end
+
     # Convert Rails helpers to placeholder HTML
     def convert_rails_helpers
+      # First, handle raw HTML elements with ERB in attributes (before removing ERB tags)
+      convert_raw_html_with_erb
       convert_form_helpers
       convert_image_helpers
       convert_link_helpers

data/lib/rails_accessibility_testing/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module RailsAccessibilityTesting
-  VERSION = "1.5.10"
+  VERSION = "1.7.0"
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_accessibility_testing
 version: !ruby/object:Gem::Version
-  version: 1.5.10
+  version: 1.7.0
 platform: ruby
 authors:
 - Regan Maharjan
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-12-01 00:00:00.000000000 Z
+date: 2026-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: axe-core-capybara
@@ -97,6 +97,7 @@ files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
+- GUIDES/best_practices.md
 - GUIDES/continuous_integration.md
 - GUIDES/getting_started.md
 - GUIDES/system_specs_for_accessibility.md