rails_accessibility_testing 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 232d290bc12c422c56aacad24fa16660eb12b3e106939fc6b4cac0a639740532
-  data.tar.gz: 2b5a248555626127007ef893c84bd10f8aac41e195dba54c86bebd7b1f4e1448
+  metadata.gz: 61344dc6a53b7678ea457fdfca0237fb7dfece5ef7825aaf0449fea1d187737d
+  data.tar.gz: c843795ff4c676607b4fde8d207a7055db5a9b128054583964843a6d41cc6ece
 SHA512:
-  metadata.gz: 566c195bcf20d08247c58c97f11e8fe1158488d998a78eb12e293f9e70451db5076c0e314c1a383a2cdcdf5f50f9dd6c291665f2516c070cbf972de6c25ee186
-  data.tar.gz: 71e9fb76ac0b894e872397a7cc822a874acf33a32bf128c1a8ca7932a0ca283389b23534b567a5929652470239d565777de7d6a0113469eb1ac688331cbd8491
+  metadata.gz: c9e66513f4b0d427e8ae5d1dbd91d4aa1da7d6758d71993ce54cd8a1e083e241c297d76ea15dde99adab4b345165fd22d7ab7d070124fdd123dfa42eccaca049
+  data.tar.gz: 4b4a86455dd1e46c4f4b08c4edae141d49f533be9dd3ce86971a52ea4eb7e203b3a0c23e5730c78e04be31d36b0cfb315011201e479049302e9843e1655d74c3

data/CHANGELOG.md

@@ -5,6 +5,23 @@ 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

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module RailsAccessibilityTesting
-  VERSION = "1.6.0"
+  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.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Regan Maharjan
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-12-11 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