rails_accessibility_testing 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 916b677bef5f630731d65df12bdd430949d70876ec0c5a9c047e15353084ae7b
-  data.tar.gz: 4960a239874be87bc96a74ba7804cfc3213ae0ea62a4b9a367d437fed337e0d0
+  metadata.gz: 5ed11e69796995b294eeaa17e2627e46b3122356d7383e2e1ad3b213c8f2ac78
+  data.tar.gz: 410f9e2c88b5e27e0a6319fb62bb854d832f8e74a25d7b3970aaf9b3f07a0fe5
 SHA512:
-  metadata.gz: f0d0e645d4d2929da2b0d2461459510759dab172192e7564be8dd2e57f2771ff86144f4fb8ece7fcbd04351ba2cc0ee08964ea7a0e07d65485171718e7608a5c
-  data.tar.gz: d8678b98bd3978104dd2158ff04f3494ff291d690b75ecee4bc29121eb76d283fd378a1cb6f763f14904060a1e8cc9e39288dcc4ca7f8ab8420253fcbc1273e1
+  metadata.gz: b3c309bbcc50838e5a981cf997c74051e10a79ce0b03d67450ad3e0dac8486d6ed79cfad4cd201e2cd25abf432370d80799a67ca9f136e11e2c055724e5f9dee
+  data.tar.gz: d8f2aaaad2e708e83dc4c9f7fd283ec815904557549f33c2f4b491fdeeed6c196b55c759b79effe7074bfda21cb4e3d07ccdefedcf07e065cdf4302f4395b74d

data/CHANGELOG.md

@@ -5,7 +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).
 
-## [1.3.0] - 2024-12-XX
+## [1.4.0] - 2025-11-18
+
+### Changed
+- Updated documentation examples to use clearer language ("runs accessibility checks" instead of "passes accessibility checks")
+- Improved test descriptions to accurately reflect that tests will fail if accessibility issues are found
+- Enhanced comments in examples to clarify when success messages appear
+
+### Improved
+- Better clarity in documentation about when accessibility checks pass vs fail
+- More accurate test descriptions that don't imply tests will pass when they may fail
+- Improved user understanding of accessibility check behavior
+
+## [1.3.0] - 2025-11-18
 
 ### Added
 - CLI reports now use ErrorMessageBuilder for detailed, formatted error messages

data/GUIDES/getting_started.md

@@ -54,7 +54,7 @@ Let's see it in action. Create a simple system spec:
 
 ```ruby
 # spec/system/home_spec.rb
-RSpec.describe "Home Page" do
+RSpec.describe "Home Page", type: :system do
   it "displays the welcome message" do
     visit root_path
     expect(page).to have_content("Welcome")
@@ -63,6 +63,41 @@ RSpec.describe "Home Page" do
 end
 ```
 
+## Running Comprehensive Checks Explicitly
+
+While checks run automatically after each `visit`, you can also run comprehensive checks explicitly at any point in your test:
+
+```ruby
+# spec/system/home_page_accessibility_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Home Page Accessibility', type: :system do
+  it 'loads the page and runs comprehensive accessibility checks' do
+    visit root_path
+    expect(page).to have_content('Welcome')
+    
+    # Run comprehensive accessibility checks explicitly
+    # This will fail the test if any accessibility issues are found
+    check_comprehensive_accessibility
+    # ✅ This runs all 11 comprehensive checks:
+    #    - Form labels, Image alt text, Interactive elements
+    #    - Heading hierarchy, Keyboard accessibility, ARIA landmarks
+    #    - Form errors, Table structure, Duplicate IDs
+    #    - Skip links, Color contrast (if enabled)
+    # If all checks pass, you'll see: "All comprehensive accessibility checks passed! (11 checks)"
+  end
+end
+```
+
+**When to use explicit checks:**
+- When you want to run checks at a specific point in your test (e.g., after filling a form)
+- When you want to ensure checks run even if the test might fail before the automatic check
+- When you want to test multiple pages in one spec and check each one explicitly
+
+**Note:** Even if you call `check_comprehensive_accessibility` explicitly, the automatic checks will still run after the test completes (unless the test fails before reaching the explicit check).
+
+### Example: Comprehensive Check Output
+
 If there are accessibility issues, you'll see detailed error messages like:
 
 ```
@@ -96,19 +131,33 @@ If there are accessibility issues, you'll see detailed error messages like:
 
 ## Understanding the Checks
 
-Rails A11y runs 11 comprehensive checks:
+Rails A11y runs **11 comprehensive checks** automatically. These checks are WCAG 2.1 AA aligned:
 
-1. **Form Labels** - All inputs have associated labels
-2. **Image Alt Text** - All images have alt attributes
-3. **Interactive Elements** - Buttons and links have accessible names
-4. **Heading Hierarchy** - Proper h1-h6 structure
+1. **Form Labels** - All form inputs have associated labels
+2. **Image Alt Text** - All images have descriptive alt attributes (including empty alt="" detection)
+3. **Interactive Elements** - Buttons, links, and other interactive elements have accessible names
+4. **Heading Hierarchy** - Proper h1-h6 structure without skipping levels
 5. **Keyboard Accessibility** - All interactive elements are 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
-10. **Skip Links** - Skip navigation links present
-11. **Color Contrast** - Text meets contrast requirements (optional)
+6. **ARIA Landmarks** - Proper use of ARIA landmark roles for page structure
+7. **Form Error Associations** - Form errors are properly linked to their form fields
+8. **Table Structure** - Tables have proper headers and structure
+9. **Duplicate IDs** - No duplicate ID attributes on the page
+10. **Skip Links** - Skip navigation links are present for keyboard users
+11. **Color Contrast** - Text meets WCAG contrast requirements (optional, disabled by default for performance)
+
+### What `check_comprehensive_accessibility` Does
+
+When you call `check_comprehensive_accessibility`, it runs all 11 checks above and provides detailed error messages for any violations found. Each error includes:
+
+- **File location hints** - Know exactly which view file to fix
+- **Element details** - Tag, ID, classes, and visible text
+- **Actionable fix instructions** - Code examples showing how to fix the issue
+- **WCAG references** - Links to relevant WCAG guidelines
+
+If all checks pass, you'll see:
+```
+✅ All comprehensive accessibility checks passed! (11 checks)
+```
 
 ## Configuration
 
@@ -171,6 +220,7 @@ end
 
 ## Next Steps
 
+- **⭐ Read the [System Specs Guide](system_specs_for_accessibility.md)** - Recommended approach for reliable accessibility testing
 - **Read the [CI Integration Guide](continuous_integration.md)** to set up automated checks
 - **Check out [Writing Accessible Views](writing_accessible_views_in_rails.md)** for best practices
 - **See [Working with Designers](working_with_designers_and_content_authors.md)** for team collaboration

data/GUIDES/system_specs_for_accessibility.md

@@ -0,0 +1,248 @@
+# Using System Specs for Accessibility Testing
+
+System specs are the **recommended and most reliable** way to run accessibility checks in your Rails application. This guide shows you how to set up continuous accessibility testing using RSpec system specs.
+
+## Why System Specs?
+
+✅ **More Reliable** - Runs in the same test environment as your other specs  
+✅ **Faster** - No need to wait for external server processes  
+✅ **Better Integration** - Works seamlessly with your existing test suite  
+✅ **Automatic** - Checks run automatically after each `visit` in system specs  
+✅ **Clear Feedback** - Detailed error messages with file locations and fix instructions  
+
+## Quick Setup
+
+### 1. Create System Specs
+
+Create system specs for the pages you want to test. Name them with `_accessibility_spec.rb` suffix for clarity:
+
+```ruby
+# spec/system/home_page_accessibility_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Home Page Accessibility', type: :system do
+  it 'loads the page and runs comprehensive accessibility checks' do
+    visit root_path
+    expect(page).to have_content('Biorepository').or have_content('Welcome')
+    
+    # Run comprehensive accessibility checks
+    # This will fail the test if any accessibility issues are found
+    check_comprehensive_accessibility
+    # ✅ If all checks pass, you'll see: "All comprehensive accessibility checks passed! (11 checks)"
+  end
+end
+```
+
+### 2. Automatic Checks
+
+The gem automatically runs comprehensive accessibility checks after each `visit` in system specs. You don't need to call `check_comprehensive_accessibility` manually unless you want to run checks at a specific point in your test.
+
+### 3. Add to Procfile.dev (Optional)
+
+For continuous testing during development, add to your `Procfile.dev`:
+
+```ruby
+web: $(bundle show rails_accessibility_testing)/exe/rails_server_safe
+css: bin/rails dartsass:watch
+a11y: while true; do bundle exec rspec spec/system/*_accessibility_spec.rb; sleep 30; done
+```
+
+This will run your accessibility specs every 30 seconds while you develop.
+
+## Example Specs
+
+### Basic Page Check
+
+```ruby
+# spec/system/home_page_accessibility_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Home Page Accessibility', type: :system do
+  it 'runs accessibility checks on the home page' do
+    visit root_path
+    # ✅ Comprehensive accessibility checks run automatically after this test!
+    # The test will fail if any accessibility issues are found
+  end
+end
+```
+
+### Multiple Pages
+
+```ruby
+# spec/system/pages_accessibility_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Pages Accessibility', type: :system do
+  it 'runs accessibility checks on home page' do
+    visit root_path
+    # Checks run automatically - test fails if issues found
+  end
+
+  it 'runs accessibility checks on about page' do
+    visit about_path
+    # Checks run automatically - test fails if issues found
+  end
+
+  it 'runs accessibility checks on contact page' do
+    visit contact_path
+    # Checks run automatically - test fails if issues found
+  end
+end
+```
+
+### With User Authentication
+
+```ruby
+# spec/system/dashboard_accessibility_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Dashboard Accessibility', type: :system do
+  before do
+    user = FactoryBot.create(:user)
+    sign_in user
+  end
+
+  it 'runs accessibility checks on dashboard' do
+    visit dashboard_path
+    # ✅ Comprehensive accessibility checks run automatically after authentication!
+    # The test will fail if any accessibility issues are found
+  end
+end
+```
+
+### Skip Checks for Specific Tests
+
+```ruby
+it 'does something without accessibility checks', skip_a11y: true do
+  visit some_path
+  # Accessibility checks won't run for this test
+end
+```
+
+## What Gets Checked
+
+The gem automatically runs **11 comprehensive accessibility checks**:
+
+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
+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
+10. ✅ **Skip Links** - Skip navigation links present
+11. ✅ **Color Contrast** - Text meets contrast requirements (optional, disabled by default)
+
+## Success Messages
+
+When all checks pass, you'll see:
+
+```
+✅ All comprehensive accessibility checks passed! (11 checks)
+```
+
+## Error Messages
+
+When issues are found, you get detailed, actionable errors:
+
+```
+======================================================================
+❌ ACCESSIBILITY ERROR: Page missing H1 heading
+======================================================================
+
+📄 Page Being Tested:
+   URL: http://127.0.0.1:54384/
+   Path: /
+   📝 Likely View File: app/views/home/about.html.erb
+
+📍 Element Details:
+   Tag: <page>
+   ID: (none)
+   Classes: (none)
+   Visible text: Page has no H1 heading
+
+🔧 HOW TO FIX:
+   Add an <h1> heading to your page:
+
+   <h1>Main Page Title</h1>
+
+   Or in Rails ERB:
+   <h1><%= @page_title || 'Default Title' %></h1>
+
+   💡 Best Practice: Every page should have exactly one <h1>.
+      It should describe the main purpose of the page.
+
+📖 WCAG Reference: https://www.w3.org/WAI/WCAG21/Understanding/
+======================================================================
+```
+
+## Running Specs
+
+### Run All Accessibility Specs
+
+```bash
+bundle exec rspec spec/system/*_accessibility_spec.rb
+```
+
+### Run Specific Spec
+
+```bash
+bundle exec rspec spec/system/home_page_accessibility_spec.rb
+```
+
+### Run with Documentation Format
+
+```bash
+bundle exec rspec spec/system/*_accessibility_spec.rb --format documentation
+```
+
+## Continuous Integration
+
+Add to your CI configuration:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Run Accessibility Tests
+  run: bundle exec rspec spec/system/*_accessibility_spec.rb
+```
+
+## Best Practices
+
+1. **Name your specs clearly** - Use `_accessibility_spec.rb` suffix
+2. **Test critical paths** - Focus on user-facing pages
+3. **Keep specs simple** - One page per spec is often enough
+4. **Use Procfile.dev** - For continuous testing during development
+5. **Run in CI** - Catch issues before they reach production
+
+## Troubleshooting
+
+### Checks Not Running
+
+Make sure:
+- Your spec has `type: :system`
+- You call `visit` in your test
+- The gem is properly configured in `spec/rails_helper.rb`
+
+### Success Message Not Showing
+
+The success message appears when all checks pass. If you don't see it, there may be silent failures. Check your RSpec output for any exceptions.
+
+### Slow Tests
+
+Disable color contrast checking in development:
+
+```yaml
+# config/accessibility.yml
+development:
+  checks:
+    color_contrast: false
+```
+
+## Next Steps
+
+- See [Getting Started Guide](getting_started.md) for initial setup
+- See [Continuous Integration Guide](continuous_integration.md) for CI/CD setup
+- See [Writing Accessible Views](writing_accessible_views_in_rails.md) for best practices
+

data/README.md

@@ -7,7 +7,7 @@
 
 **The RSpec + RuboCop of accessibility for Rails. Catch WCAG violations before they reach production.**
 
-**Current Version:** 1.2.0
+**Current Version:** 1.4.0
 
 📖 **[📚 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)
 
@@ -84,13 +84,45 @@ RailsAccessibilityTesting::Integration::MinitestIntegration.setup!
 
 ## 📖 Usage
 
+### System Specs (Recommended)
+
+**System specs are the recommended and most reliable way to run accessibility checks.** They're faster, more reliable, and integrate seamlessly with your test suite.
+
+Create system specs for your pages:
+
+```ruby
+# spec/system/home_page_accessibility_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Home Page Accessibility', type: :system do
+  it 'loads successfully and passes comprehensive accessibility checks' do
+    visit root_path
+    expect(page).to have_content('Biorepository').or have_content('Welcome')
+    
+    # Run comprehensive accessibility checks
+    check_comprehensive_accessibility
+    # ✅ Comprehensive accessibility checks (11 checks) also run automatically after this test!
+  end
+end
+```
+
+**Accessibility checks run automatically after each `visit` in system specs!**
+
+For continuous testing during development, add to your `Procfile.dev`:
+
+```ruby
+a11y: while true; do bundle exec rspec spec/system/*_accessibility_spec.rb; sleep 30; done
+```
+
+📖 **[See the full System Specs Guide](GUIDES/system_specs_for_accessibility.md)** for detailed examples and best practices.
+
 ### Automatic Checks
 
 Just write your specs normally - checks run automatically:
 
 ```ruby
 # spec/system/home_page_spec.rb
-RSpec.describe "Home Page" do
+RSpec.describe "Home Page", type: :system do
   it "displays welcome message" do
     visit root_path
     expect(page).to have_content("Welcome")
@@ -270,6 +302,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
 - **[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/rails_accessibility_testing/cli/command.rb

@@ -106,6 +106,9 @@ module RailsAccessibilityTesting
       end
       
       def run_checks(options, config)
+        # Reset wait attempts counter for each run
+        @wait_attempts = 0
+        
         require 'capybara'
         require 'capybara/dsl'
         require 'selenium-webdriver'
@@ -160,7 +163,12 @@ module RailsAccessibilityTesting
                 # If still not ready, skip this check and try next time
                 unless server_ready
                   # Server still starting - this is normal, will retry automatically
-                  $stderr.puts "Waiting for server to start... (will retry automatically)"
+                  # Only show message occasionally to avoid spam (every 3rd attempt)
+                  @wait_attempts ||= 0
+                  @wait_attempts += 1
+                  if @wait_attempts % 3 == 1
+                    $stderr.puts "Waiting for server to start... (will retry automatically)"
+                  end
                   next
                 end
               end

data/lib/rails_accessibility_testing/rspec_integration.rb

@@ -49,12 +49,13 @@ module RailsAccessibilityTesting
           instance = example.example_group_instance
           instance.check_comprehensive_accessibility
           
-          # Show success message if checks passed (no exception was raised)
-          unless example.exception
-            $stdout.puts "\n✅ All comprehensive accessibility checks passed! (11 checks)"
-            $stdout.flush
-          end
+          # If we get here without an exception, all checks passed
+          # Note: check_comprehensive_accessibility will raise if there are errors,
+          # so if we reach this point, checks passed successfully
+          $stdout.puts "\n✅ All comprehensive accessibility checks passed! (11 checks)"
+          $stdout.flush
         rescue StandardError => e
+          # Accessibility check failed - set the exception so test fails
           example.set_exception(e)
         end
       end

data/lib/rails_accessibility_testing/version.rb

@@ -1,4 +1,4 @@
 module RailsAccessibilityTesting
-  VERSION = "1.3.0"
+  VERSION = "1.4.0"
 end
 

data/lib/rails_accessibility_testing.rb

@@ -5,7 +5,7 @@
 # Automatically configures accessibility testing for Rails system specs with
 # comprehensive checks and detailed error messages.
 #
-# @version 1.1.0
+# @version 1.4.0
 # @author Regan Maharjan
 #
 # @example Basic usage
@@ -38,7 +38,7 @@ begin
   require_relative 'rails_accessibility_testing/version'
 rescue LoadError
   module RailsAccessibilityTesting
-    VERSION = '1.3.0'
+    VERSION = '1.4.0'
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_accessibility_testing
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Regan Maharjan
@@ -84,6 +84,7 @@ files:
 - CONTRIBUTING.md
 - GUIDES/continuous_integration.md
 - GUIDES/getting_started.md
+- GUIDES/system_specs_for_accessibility.md
 - GUIDES/working_with_designers_and_content_authors.md
 - GUIDES/writing_accessible_views_in_rails.md
 - LICENSE