Update: Generator templates with production-tested best practices

rayraycodes · cursoragent · rayraycodes · commit 7be49cefb836 · 2026-02-11T13:48:26.000-05:00
- Set accessibility_enabled default to false for CI/CD safety
- Add production safety guard in initializer
- Set auto_run_checks to false by default
- Change RSpec type to :accessibility
- Improve error formatting in spec template
- Update generator to create spec/accessibility/ directory
- Update documentation URLs to GitHub Pages
- Add Best Practices guide
- Update CI guide with best practices

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/BOSS_MESSAGE_1.6.0.txt b/BOSS_MESSAGE_1.6.0.txt
@@ -0,0 +1,25 @@
+Subject: Rails Accessibility Testing v1.6.0 Release - Fixed False Positives
+
+Hi [Boss Name],
+
+I've just released version 1.6.0 of the Rails Accessibility Testing gem, which addresses critical false positive issues that were affecting accuracy.
+
+**Main Problem Solved:**
+The static file scanner was incorrectly flagging checkbox and radio button groups with dynamic IDs (common in Rails ERB templates) as missing labels or duplicate IDs, even when they were correctly implemented.
+
+**Key Improvements:**
+✅ Fixed false positives for dynamic form elements (checkbox/radio groups in loops)
+✅ Enhanced ERB template processing to accurately handle Rails patterns
+✅ Improved label matching for dynamically generated form inputs
+✅ Better duplicate ID detection that excludes dynamic IDs
+✅ Fixed link accessibility detection to avoid false positives
+
+**Impact:**
+This release significantly improves the scanner's accuracy for real-world Rails applications, reducing noise in reports and making the tool more reliable for teams. The changes ensure that correctly implemented accessibility features aren't flagged as errors.
+
+The release is now available on RubyGems and has been tagged in GitHub.
+
+Best regards,
+[Your Name]
+
+
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,19 @@ 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]
+
+### 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
+- **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
+
 ## [1.6.0] - 2024-12-XX
 
 ### Added
diff --git a/GUIDES/continuous_integration.md b/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
 
diff --git a/README.md b/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
diff --git a/RELEASE_NOTES_1.6.0.md b/RELEASE_NOTES_1.6.0.md
@@ -0,0 +1,44 @@
+# Release Notes for Version 1.6.0
+
+## Summary
+
+Version 1.6.0 addresses critical false positive issues in the static file scanner, particularly for Rails applications using ERB templates with dynamic form elements. This release significantly improves accuracy and reduces noise in accessibility testing reports.
+
+## Key Improvements
+
+### 🐛 **Fixed False Positives for Dynamic Form Elements**
+- **Problem Solved**: The scanner was incorrectly flagging checkbox and radio button groups with ERB-generated IDs (e.g., `collection_answers_<%= question.id %>_<%= option.id %>_`) as missing labels or duplicate IDs.
+- **Solution**: Enhanced ERB template processing to preserve dynamic ID structure instead of collapsing them, allowing accurate label-to-input matching.
+- **Impact**: Eliminates false positives for common Rails patterns like checkbox groups in loops, making the scanner more reliable for real-world applications.
+
+### 🔍 **Enhanced ERB Template Handling**
+- Improved static analysis of ERB templates to correctly handle:
+  - Dynamic IDs in form inputs
+  - String interpolation in `label_tag` helpers
+  - Raw HTML elements with ERB expressions in attributes
+- The scanner now preserves the structure of dynamic IDs (using `ERB_CONTENT` placeholders) rather than collapsing them, enabling accurate accessibility checks.
+
+### ✅ **Improved Accessibility Rule Accuracy**
+- **Form Labels Check**: Now correctly matches labels to inputs with dynamic IDs from ERB templates
+- **Duplicate ID Detection**: Intelligently excludes dynamic IDs from duplicate checking (prevents false positives for checkbox/radio groups)
+- **Interactive Elements Check**: Fixed detection for links with `href="#"` - now only flags links that truly lack accessible names, avoiding false positives for valid anchor links
+
+### 📝 **Better Test Integration**
+- Refactored RSpec test file to properly assert on errors (tests now fail when accessibility errors are found)
+- Extracted formatting logic into reusable helpers
+- Warnings are displayed but don't fail tests (only errors cause failures)
+
+### 📚 **Documentation Updates**
+- Added comprehensive documentation on ERB template handling
+- Updated architecture docs with details on dynamic ID processing
+- Added examples for common Rails patterns
+
+## Technical Details
+
+The core improvement is in the `ErbExtractor` class, which now processes raw HTML elements with ERB in attributes before removing ERB tags. This preserves the structure of dynamic IDs like `collection_answers_ERB_CONTENT_ERB_CONTENT_` instead of collapsing them to just `collection_answers`, enabling accurate matching between inputs and labels.
+
+## Impact
+
+This release makes the static file scanner significantly more reliable for Rails applications, reducing false positives by correctly handling common ERB patterns. Teams can now trust the scanner results more, leading to faster development cycles and more accurate accessibility compliance reporting.
+
+
diff --git a/TEMPLATE_UPDATES_SUMMARY.md b/TEMPLATE_UPDATES_SUMMARY.md
@@ -0,0 +1,130 @@
+# Generator Template Updates Summary
+
+This document summarizes the updates made to the Rails Accessibility Testing generator templates based on production best practices from Margarita Barvinok's implementation.
+
+## Overview
+
+The generator templates have been updated to incorporate production-tested best practices that improve CI/CD safety, production deployment safety, and developer experience.
+
+## Files Updated
+
+### 1. `lib/generators/rails_a11y/install/templates/accessibility.yml.erb`
+
+**Changes:**
+- ✅ Changed `accessibility_enabled` default from `true` → `false`
+- ✅ Added comprehensive documentation explaining CI/CD behavior
+- ✅ Updated documentation URL to correct GitHub Pages link
+- ✅ Added detailed comments explaining when to enable/disable
+
+**Impact:**
+- Prevents accessibility test failures from blocking CI/CD pipelines
+- Allows other RSpec tests to pass even if accessibility tests fail
+- Gives developers explicit control over when to run accessibility checks
+
+### 2. `lib/generators/rails_a11y/install/templates/initializer.rb.erb`
+
+**Changes:**
+- ✅ Added production safety guard: `if defined?(RailsAccessibilityTesting)`
+- ✅ Changed `auto_run_checks` default from `true` → `false`
+- ✅ Updated documentation URL to correct GitHub Pages link
+- ✅ Added `@see` tag for better documentation
+
+**Impact:**
+- Prevents errors if gem is not available in production
+- Allows gem to be excluded from production bundle
+- Gives developers explicit control over automatic checks
+- Safe deployment even if gem configuration is present
+
+### 3. `lib/generators/rails_a11y/install/templates/all_pages_accessibility_spec.rb.erb`
+
+**Changes:**
+- ✅ Changed RSpec type from `type: :system` → `type: :accessibility`
+- ✅ Improved error formatting with unified `format_issues_by_file` helper method
+- ✅ Changed test assertion to use `expect(errors).to be_empty` with formatted message
+- ✅ Better success message formatting
+
+**Impact:**
+- Proper RSpec integration with accessibility helpers
+- Better test organization and filtering
+- Cleaner test output
+- Improved error messages with better structure
+
+## New Documentation
+
+### `GUIDES/best_practices.md`
+
+Created comprehensive best practices guide covering:
+- Configuration best practices
+- CI/CD integration patterns
+- Development workflow recommendations
+- Production deployment safety
+- Real-world usage examples
+
+### Updated Documentation
+
+- ✅ `README.md` - Added link to Best Practices guide
+- ✅ `GUIDES/continuous_integration.md` - Added best practice about disabling by default
+- ✅ `CHANGELOG.md` - Documented template updates
+
+## Key Improvements
+
+### 1. CI/CD Safety
+- Accessibility tests disabled by default
+- Won't block other RSpec tests in CI
+- Manual invocation when needed
+
+### 2. Production Safety
+- Conditional configuration prevents errors
+- Safe deployment even without gem
+- No production dependencies
+
+### 3. Developer Control
+- Explicit control over automatic checks
+- Manual testing when needed
+- Better error formatting
+
+### 4. Better UX
+- Improved error messages
+- Proper RSpec integration
+- Cleaner test output
+
+## Migration Notes
+
+For existing installations:
+
+1. **Update `config/accessibility.yml`:**
+   ```yaml
+   accessibility_enabled: false  # Add this if not present
+   ```
+
+2. **Update `config/initializers/rails_a11y.rb`:**
+   ```ruby
+   if defined?(RailsAccessibilityTesting)
+     RailsAccessibilityTesting.configure do |config|
+       config.auto_run_checks = false  # Change from true if needed
+     end
+   end
+   ```
+
+3. **Update `spec/accessibility/all_pages_accessibility_spec.rb`:**
+   - Change `type: :system` to `type: :accessibility`
+   - Update error formatting to use unified helper method
+
+## Credits
+
+These improvements are based on production-tested configurations from:
+- **Margarita Barvinok** - Production configuration improvements
+- Real-world usage in Rails applications
+- Community feedback and testing
+
+## Next Steps
+
+1. Test generator with `rails generate rails_a11y:install`
+2. Verify templates generate correct configuration
+3. Update existing projects using migration notes above
+4. Share feedback and improvements
+
+---
+
+**Date:** February 2026  
+**Version:** Unreleased (will be in next release)
diff --git a/lib/generators/rails_a11y/install/install_generator.rb b/lib/generators/rails_a11y/install/install_generator.rb
@@ -43,7 +43,11 @@ def add_to_rails_helper
       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 @@ def show_instructions
         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"
diff --git a/lib/generators/rails_a11y/install/templates/accessibility.yml.erb b/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
diff --git a/lib/generators/rails_a11y/install/templates/all_pages_accessibility_spec.rb.erb b/lib/generators/rails_a11y/install/templates/all_pages_accessibility_spec.rb.erb
diff --git a/lib/generators/rails_a11y/install/templates/initializer.rb.erb b/lib/generators/rails_a11y/install/templates/initializer.rb.erb
