rails_accessibility_testing 1.4.3 → 1.5.1

data/GUIDES/getting_started.md

@@ -15,6 +15,7 @@ Add to your `Gemfile`:
 ```ruby
 group :development, :test do
   gem 'rails_accessibility_testing'
+  gem 'rspec-rails', '~> 8.0'  # Required for system specs
   gem 'axe-core-capybara', '~> 4.0'
   gem 'capybara', '~> 3.40'
   gem 'selenium-webdriver', '~> 4.0'
@@ -22,7 +23,9 @@ group :development, :test do
 end
 ```
 
-**Important:** You must explicitly add `selenium-webdriver` to your Gemfile. It's not automatically included as a dependency.
+**Important:** 
+- You must explicitly add `selenium-webdriver` to your Gemfile. It's not automatically included as a dependency.
+- **RSpec Rails is required** - The generator creates system specs that require `rspec-rails`. If you're using Minitest, you'll need to manually create your accessibility tests.
 
 Then run:
 
@@ -41,70 +44,13 @@ rails generate rails_a11y:install
 This creates:
 - `config/initializers/rails_a11y.rb` - Configuration
 - `config/accessibility.yml` - Check settings
+- `spec/system/all_pages_accessibility_spec.rb` - Comprehensive spec that tests all GET routes with smart change detection
 - Updates `spec/rails_helper.rb` (if using RSpec)
+- Updates `Procfile.dev` - Adds accessibility watch command (optional)
 
-### Step 2.5: Configure Capybara Driver (Required for System Tests)
+**Note:** If you already have system tests set up in your Rails application, you can skip to Step 3. If you need help configuring Capybara or installing Chrome, see the [FAQ section](#troubleshooting) below.
 
-For system tests to work, you need to configure Capybara with a Selenium driver. Create `spec/support/driver.rb`:
-
-```ruby
-# spec/support/driver.rb
-require 'selenium-webdriver'
-require 'capybara/rails'
-require 'capybara/rspec'
-
-# Configure Chrome options
-browser_options = Selenium::WebDriver::Chrome::Options.new
-browser_options.add_argument('--window-size=1920,1080')
-browser_options.add_argument('--headless') unless ENV['SHOW_TEST_BROWSER']
-
-# Register the driver
-Capybara.register_driver :selenium_chrome_headless do |app|
-  Capybara::Selenium::Driver.new(
-    app,
-    browser: :chrome,
-    options: browser_options
-  )
-end
-
-# Set as default JavaScript driver
-Capybara.javascript_driver = :selenium_chrome_headless
-
-# Configure RSpec to use the driver for system tests
-RSpec.configure do |config|
-  config.before(:each, type: :system) do
-    driven_by :selenium_chrome_headless
-  end
-end
-```
-
-**Note for Rails 8:** Rails 8 uses `driven_by` to configure system tests. Make sure your `spec/support/driver.rb` is loaded by `rails_helper.rb` (it should be automatically loaded if it's in the `spec/support/` directory).
-
-### Step 3: Install Chrome/Chromium (Required)
-
-System tests require Chrome or Chromium to be installed on your system:
-
-**macOS:**
-```bash
-brew install --cask google-chrome
-# or for Chromium:
-brew install --cask chromium
-```
-
-**Linux (Ubuntu/Debian):**
-```bash
-sudo apt-get update
-sudo apt-get install -y google-chrome-stable
-# or for Chromium:
-sudo apt-get install -y chromium-browser
-```
-
-**Windows:**
-Download and install Chrome from [google.com/chrome](https://www.google.com/chrome/)
-
-The `webdrivers` gem will automatically download and manage the ChromeDriver binary for you.
-
-### Step 4: Run Your Tests
+### Step 3: Run Your Tests
 
 You can run accessibility checks in several ways:
 
@@ -118,7 +64,7 @@ Accessibility checks run automatically on every system test that visits a page.
 
 #### Option B: Run Continuously with Procfile (Recommended for Development)
 
-For continuous accessibility checking during development, add to your `Procfile.dev`:
+The generator automatically adds an accessibility watch command to your `Procfile.dev`:
 
 ```procfile
 web: bin/rails server
@@ -139,6 +85,28 @@ This will:
 
 The accessibility checker will continuously monitor your pages and alert you to any issues as you develop!
 
+#### Option C: All Pages Spec with Smart Change Detection
+
+The generator creates `spec/system/all_pages_accessibility_spec.rb` which automatically tests all GET routes in your application. This spec includes **smart change detection**:
+
+- **Only tests pages when their related files change** - Views, controllers, or helpers
+- **Detects changes via Git** - Uncommitted changes in monitored directories (`app/views`, `app/controllers`, `app/helpers`)
+- **File modification tracking** - Files changed in the last 5 minutes
+- **Layout/helper changes** - Automatically tests all pages when layouts or helpers change (they affect everything)
+- **First run** - Tests all pages on first run (when no changes detected)
+- **Manual override** - Set `TEST_ALL_PAGES=true` to force testing all pages regardless of changes
+
+This makes your test suite faster and more focused, only running checks when relevant code changes. The spec automatically:
+- Skips routes that require authentication
+- Handles routes with parameters
+- Filters out API routes and Rails internal routes
+- Provides clear skip messages when pages aren't affected by changes
+
+Run it manually:
+```bash
+bundle exec rspec spec/system/all_pages_accessibility_spec.rb
+```
+
 ## Your First Accessibility Check
 
 Let's see it in action. Create a simple system spec:
@@ -159,13 +127,12 @@ end
 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
+# spec/system/my_page_accessibility_spec.rb
 require 'rails_helper'
 
-RSpec.describe 'Home Page Accessibility', type: :system do
+RSpec.describe 'My 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
@@ -226,14 +193,14 @@ Rails A11y runs **11 comprehensive checks** automatically. These checks are WCAG
 
 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
+3. **Interactive Elements** - Buttons, links, and other interactive elements have accessible names (including links with images that have alt text)
+4. **Heading Hierarchy** - Proper h1-h6 structure without skipping levels (detects missing h1, skipped levels, and h2+ without h1)
 5. **Keyboard Accessibility** - All interactive elements are keyboard accessible
 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
+10. **Skip Links** - Skip navigation links are present for keyboard users (detects various patterns: `skip-link`, `skiplink`, `href="#main"`, `href="#maincontent"`, etc.)
 11. **Color Contrast** - Text meets WCAG contrast requirements (optional, disabled by default for performance)
 
 ### What `check_comprehensive_accessibility` Does
@@ -318,6 +285,67 @@ end
 
 ## Troubleshooting
 
+### How do I configure Capybara for system tests?
+
+If you don't already have system tests configured, you need to set up Capybara with a Selenium driver. Create `spec/support/driver.rb`:
+
+```ruby
+# spec/support/driver.rb
+require 'selenium-webdriver'
+require 'capybara/rails'
+require 'capybara/rspec'
+
+# Configure Chrome options
+browser_options = Selenium::WebDriver::Chrome::Options.new
+browser_options.add_argument('--window-size=1920,1080')
+browser_options.add_argument('--headless') unless ENV['SHOW_TEST_BROWSER']
+
+# Register the driver
+Capybara.register_driver :selenium_chrome_headless do |app|
+  Capybara::Selenium::Driver.new(
+    app,
+    browser: :chrome,
+    options: browser_options
+  )
+end
+
+# Set as default JavaScript driver
+Capybara.javascript_driver = :selenium_chrome_headless
+
+# Configure RSpec to use the driver for system tests
+RSpec.configure do |config|
+  config.before(:each, type: :system) do
+    driven_by :selenium_chrome_headless
+  end
+end
+```
+
+**Note for Rails 8:** Rails 8 uses `driven_by` to configure system tests. Make sure your `spec/support/driver.rb` is loaded by `rails_helper.rb` (it should be automatically loaded if it's in the `spec/support/` directory).
+
+### How do I install Chrome/Chromium?
+
+System tests require Chrome or Chromium to be installed on your system:
+
+**macOS:**
+```bash
+brew install --cask google-chrome
+# or for Chromium:
+brew install --cask chromium
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt-get update
+sudo apt-get install -y google-chrome-stable
+# or for Chromium:
+sudo apt-get install -y chromium-browser
+```
+
+**Windows:**
+Download and install Chrome from [google.com/chrome](https://www.google.com/chrome/)
+
+The `webdrivers` gem will automatically download and manage the ChromeDriver binary for you.
+
 ### Error: `uninitialized constant Selenium::WebDriver::DriverFinder`
 
 This error typically occurs when:
@@ -370,14 +398,14 @@ development:
 
 For best results, use these compatible versions:
 
-| Component | Recommended Version | Minimum Version |
-|-----------|-------------------|-----------------|
-| Ruby | 3.1+ | 3.0+ |
-| Rails | 7.1+ / 8.0+ | 6.0+ |
-| RSpec Rails | 6.0+ | 5.0+ |
-| Capybara | ~> 3.40 | 3.0+ |
-| selenium-webdriver | ~> 4.10 | 4.0+ |
-| webdrivers | ~> 5.3 | 5.0+ |
+| Component | Recommended Version | Minimum Version | Required |
+|-----------|-------------------|-----------------|----------|
+| Ruby | 3.1+ | 3.0+ | Yes |
+| Rails | 7.1+ / 8.0+ | 6.0+ | Yes |
+| **RSpec Rails** | **8.0+** | **6.0+** | **Yes (for system specs)** |
+| Capybara | ~> 3.40 | 3.0+ | Yes |
+| selenium-webdriver | ~> 4.10 | 4.0+ | Yes |
+| webdrivers | ~> 5.3 | 5.0+ | Optional |
 
 **Rails 8 Notes:**
 - Rails 8 requires `selenium-webdriver` 4.6.0+ for `DriverFinder` support

data/GUIDES/system_specs_for_accessibility.md

@@ -12,18 +12,19 @@ System specs are the **recommended and most reliable** way to run accessibility
 
 ## Quick Setup
 
-### 1. Create System Specs
+### 1. Use the Generated Specs
 
-Create system specs for the pages you want to test. Name them with `_accessibility_spec.rb` suffix for clarity:
+The generator creates `spec/system/all_pages_accessibility_spec.rb` which automatically tests all GET routes in your application with **smart change detection**. This spec only tests pages when their related files (views, controllers, helpers) have changed, making it fast and focused.
+
+You can also create custom system specs for specific pages. Name them with `_accessibility_spec.rb` suffix for clarity:
 
 ```ruby
-# spec/system/home_page_accessibility_spec.rb
+# spec/system/my_page_accessibility_spec.rb
 require 'rails_helper'
 
-RSpec.describe 'Home Page Accessibility', type: :system do
+RSpec.describe 'My 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
@@ -37,27 +38,27 @@ end
 
 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)
+### 3. Continuous Testing with Procfile (Optional)
 
-For continuous testing during development, add to your `Procfile.dev`:
+The generator automatically adds an accessibility watch command to your `Procfile.dev`:
 
 ```ruby
-web: $(bundle show rails_accessibility_testing)/exe/rails_server_safe
+web: bin/rails server
 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.
+This will run your accessibility specs every 30 seconds while you develop. The `all_pages_accessibility_spec.rb` uses smart change detection to only test pages when their related files change, making it fast and focused.
 
 ## Example Specs
 
 ### Basic Page Check
 
 ```ruby
-# spec/system/home_page_accessibility_spec.rb
+# spec/system/my_page_accessibility_spec.rb
 require 'rails_helper'
 
-RSpec.describe 'Home Page Accessibility', type: :system do
+RSpec.describe 'My 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!
@@ -189,7 +190,7 @@ bundle exec rspec spec/system/*_accessibility_spec.rb
 ### Run Specific Spec
 
 ```bash
-bundle exec rspec spec/system/home_page_accessibility_spec.rb
+bundle exec rspec spec/system/all_pages_accessibility_spec.rb
 ```
 
 ### Run with Documentation Format

data/README.md

@@ -7,7 +7,7 @@
 
 **The RSpec + RuboCop of accessibility for Rails. Catch WCAG violations before they reach production.**
 
-**Current Version:** 1.4.3
+**Current Version:** 1.5.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)
 
@@ -19,16 +19,46 @@ Rails Accessibility Testing fills a critical gap in the Rails testing ecosystem.
 
 ## ✨ Features
 
+### Core Capabilities
 - 🚀 **Zero Configuration** - Works out of the box with smart defaults
 - 🎯 **11+ Comprehensive Checks** - WCAG 2.1 AA aligned
-- 📍 **File Location Hints** - Know exactly which view file to fix
+- 📍 **Precise File Location** - Know exactly which view file or partial to fix
 - 🔧 **Actionable Error Messages** - Code examples showing how to fix issues
-- ⚡ **Smart Change Detection** - Only runs when relevant code changes
 - 🎨 **Beautiful CLI** - Human-readable and JSON reports
 - 🔌 **Rails Generator** - One command setup
 - 🧪 **RSpec & Minitest** - Works with both test frameworks
 - ⚙️ **YAML Configuration** - Profile-based config (dev/test/CI)
-- 📚 **Comprehensive Guides** - Learn as you go
+
+### 🆕 Version 1.5.0 Highlights
+
+#### 🎯 Live Accessibility Scanner
+- **Real-time scanning**: Automatically scans pages as you browse during development
+- **Smart cancellation**: Cancels scans when you navigate to new pages, focusing on current page
+- **Integrated workflow**: Works seamlessly with `bin/dev` via Procfile.dev
+- **Detailed reporting**: Shows exactly what's being scanned with page URLs and view files
+
+#### 📝 Enhanced Error Reporting
+- **View file priority**: Rails view files shown prominently instead of URLs
+- **Comprehensive summaries**: Overall test report showing all pages tested with statistics
+- **Accurate error counting**: Properly tracks and displays error/warning counts
+- **Persistent output**: Errors stay visible in terminal (no clearing)
+
+#### 🔍 Smart View File Detection
+- **Intelligent matching**: Automatically finds view files even when action names don't match
+- **Controller directory scanning**: Searches all view files to find the correct template
+- **Fuzzy matching**: Handles variations and naming conventions
+- **Partial detection**: Shows exact partial file when issues are found
+
+#### ⚡ Performance Optimizations
+- **Optimized DOM queries**: Faster image alt checks without JavaScript evaluation
+- **Removed delays**: Eliminated unnecessary sleep calls in live scanner
+- **Efficient scanning**: ~25-30% faster page scans
+
+#### 🎨 Enhanced Developer Experience
+- **Real-time progress**: Step-by-step feedback during accessibility checks
+- **Clear summaries**: Comprehensive test reports with view files and statistics
+- **Better error context**: Shows view files, paths, and element details
+- **Focused scanning**: Live scanner adapts to your browsing behavior
 
 ## 🚀 Quick Start
 
@@ -39,14 +69,16 @@ Add to your `Gemfile`:
 ```ruby
 group :development, :test do
   gem 'rails_accessibility_testing'
+  gem 'rspec-rails', '~> 8.0'  # Required for system specs
   gem 'axe-core-capybara', '~> 4.0'
   gem 'capybara', '~> 3.40'
   gem 'selenium-webdriver', '~> 4.0'
-  gem 'webdrivers', '~> 5.0'  # Optional but recommended for automatic driver management
+  gem 'webdrivers', '~> 5.0'  # Optional but recommended
+  gem 'csv'  # Required for Ruby 3.3+ (CSV removed from standard library in Ruby 3.4)
 end
 ```
 
-**Important:** You must explicitly add `selenium-webdriver` to your Gemfile. It's not automatically included as a dependency. The gem has minimal dependencies - you control your own driver setup.
+**Important:** You must explicitly add `selenium-webdriver` and `csv` (for Ruby 3.3+) to your Gemfile. The gem has minimal dependencies - you control your own driver setup.
 
 Then run:
 
@@ -65,7 +97,9 @@ rails generate rails_a11y:install
 This creates:
 - `config/initializers/rails_a11y.rb` - Configuration
 - `config/accessibility.yml` - Check settings
+- `spec/system/all_pages_accessibility_spec.rb` - Comprehensive spec that dynamically tests all GET routes
 - Updates `spec/rails_helper.rb` (if using RSpec)
+- Updates `Procfile.dev` with accessibility watch command (if present)
 
 ### Setup (Option 2: Manual)
 
@@ -100,7 +134,7 @@ 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')
+    expect(page).to have_content('Welcome')
     
     # Run comprehensive accessibility checks
     check_comprehensive_accessibility
@@ -111,25 +145,22 @@ end
 
 **Accessibility checks run automatically after each `visit` in system specs!**
 
-#### Continuous Testing with Procfile (Recommended for Development)
-
-For continuous accessibility checking during development, add to your `Procfile.dev`:
-
-```procfile
-web: bin/rails server
-css: bin/rails dartsass:watch
-a11y: while true; do bundle exec rspec spec/system/*_accessibility_spec.rb; sleep 30; done
-```
+### All Pages Accessibility Spec
 
-Then run:
-
-```bash
-bin/dev
-```
+The generator creates `spec/system/all_pages_accessibility_spec.rb` which automatically tests all GET routes in your application. The spec:
 
-This will automatically run accessibility checks every 30 seconds on all `*_accessibility_spec.rb` files, giving you continuous feedback as you develop!
+- **Dynamically discovers routes** at runtime - works for any Rails app
+- **Smart change detection** - Only tests pages when their related files (views, controllers, helpers, CSS/JS) have changed
+- **First-run optimization** - Tests all pages on first run, then only changed files
+- **Intelligent skipping** - Skips routes that require authentication, have errors, or aren't accessible
+- **Friendly summaries** - Shows passed/failed/skipped counts with clear reasons
 
-📖 **[See the full System Specs Guide](GUIDES/system_specs_for_accessibility.md)** for detailed examples and best practices.
+The spec automatically:
+- Tests all GET routes (filters out API, internal Rails routes)
+- Handles routes with parameters by substituting test values
+- Detects view files even when action names don't match
+- Shows which files changed and which pages are affected
+- Provides helpful tips and next steps
 
 ### Automatic Checks
 
@@ -169,6 +200,18 @@ it "meets all accessibility standards" do
 end
 ```
 
+### Continuous Development Testing
+
+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 bin/check_a11y_changes && (test -f bin/rspec && bin/rspec spec/system/*_accessibility_spec.rb --format progress --no-profile || bundle exec rspec spec/system/*_accessibility_spec.rb --format progress --no-profile) 2>&1 | grep -v "^[[:space:]]*[0-9]*)[[:space:]]*All Pages Accessibility checks accessibility" | grep -v "# Skipping" || echo '⏭️  No changes detected, skipping tests'; sleep 30; done
+```
+
+This runs accessibility tests every 30 seconds, but only when files have changed!
+
 ### CLI Usage
 
 Run checks against URLs or Rails routes:
@@ -196,14 +239,14 @@ 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
+3. ✅ **Interactive Elements** - Buttons, links have accessible names (including links with images that have alt text)
+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
-10. ✅ **Skip Links** - Skip navigation links present
+10. ✅ **Skip Links** - Skip navigation links present (detects various patterns)
 11. ✅ **Color Contrast** - Text meets contrast requirements (optional)
 
 ## ⚙️ Configuration
@@ -221,7 +264,7 @@ checks:
   form_labels: true
   image_alt_text: true
   interactive_elements: true
-  heading_hierarchy: true
+  heading: true  # Note: renamed from heading_hierarchy in 1.5.0
   keyboard_accessibility: true
   aria_landmarks: true
   form_errors: true
@@ -268,7 +311,7 @@ end
 
 ## 📋 Example Error Output
 
-When accessibility issues are found, you get detailed, actionable errors:
+When accessibility issues are found, you get detailed, actionable errors with precise file locations:
 
 ```
 ======================================================================
@@ -276,9 +319,10 @@ When accessibility issues are found, you get detailed, actionable errors:
 ======================================================================
 
 📄 Page Being Tested:
-   URL: http://localhost:3000/
-   Path: /
-   📝 Likely View File: app/views/shared/_header.html.erb
+   URL: http://localhost:3000/items/search
+   Path: /items/search
+   📝 View File: app/views/items/search_result.html.erb
+   📝 Partial: app/views/layouts/_advance_search.html.erb
 
 📍 Element Details:
    Tag: <img>
@@ -298,10 +342,40 @@ When accessibility issues are found, you get detailed, actionable errors:
    💡 Best Practice: All images must have alt attribute.
       Use empty alt="" only for purely decorative images.
 
-📖 WCAG Reference: https://www.w3.org/WAI/WCAG21/Understanding/
+📖 WCAG Reference: https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html
 ======================================================================
 ```
 
+**Notice:** The error shows both the main view file (`search_result.html.erb`) and the partial where the issue actually occurs (`_advance_search.html.erb`). This makes fixing issues much faster!
+
+## 🚀 Performance Features
+
+### Smart Change Detection
+
+The gem automatically detects when files change and only tests affected pages:
+
+- **View files**: Tests pages when their view files change
+- **Partials**: Tests pages that render changed partials
+- **Controllers**: Tests all routes for a controller when the controller changes
+- **Helpers**: Tests all pages when helpers change (they can affect any view)
+- **Assets**: Tests all pages when CSS/JS changes (can affect accessibility globally)
+
+### Page Scanning Cache
+
+Prevents duplicate scans of the same page during a test run:
+
+- **Automatic caching**: Each page is scanned once per test suite execution
+- **Efficient tracking**: Uses page path or URL as cache key
+- **Silent skipping**: Already-scanned pages are skipped without output
+- **Manual reset**: Use `reset_scanned_pages_cache` if needed
+
+### First-Run Optimization
+
+- **Initial baseline**: Tests all pages on first run to establish baseline
+- **Subsequent runs**: Only tests changed files for faster feedback
+- **Marker file**: Creates `.rails_a11y_initialized` to track first run
+- **Force all pages**: Set `TEST_ALL_PAGES=true` to test all pages anytime
+
 ## 📚 Documentation
 
 ### 🌐 Online Documentation
@@ -337,9 +411,12 @@ View at `doc/index.html`
 
 Rails Accessibility Testing is built with a clean, modular architecture:
 
-- **Rule Engine** - Evaluates accessibility checks
-- **Check Definitions** - WCAG-aligned check implementations
+- **Rule Engine** - Evaluates accessibility checks with configurable profiles
+- **Check Definitions** - WCAG-aligned check implementations (11+ checks)
 - **Violation Collector** - Aggregates and formats violations
+- **View File Detection** - Intelligent detection of view files and partials
+- **Change Detector** - Smart detection of file changes and their impact
+- **Page Scanning Cache** - Prevents duplicate scans for performance
 - **Rails Integration** - Railtie, RSpec, Minitest helpers
 - **CLI** - Command-line interface for URL/route scanning
 - **Configuration** - YAML-based config with profiles
@@ -350,13 +427,50 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architecture documentation.
 
 - Ruby 3.0+ (3.1+ recommended)
 - Rails 6.0+ (7.1+ recommended)
-- RSpec Rails 6.0+ (for RSpec) or Minitest (for Minitest)
+- **RSpec Rails 6.0+ (required for system specs)** or Minitest (for Minitest)
 - Capybara 3.0+ (provided by your project)
 - selenium-webdriver 4.0+ (provided by your project, for system specs)
 - webdrivers (optional, provided by your project, for automatic driver management)
+- **csv gem** (required for Ruby 3.3+, as CSV is removed from standard library in Ruby 3.4)
 - Chrome/Chromium browser
 
-**Note:** As of version 1.2.0, the gem has minimal dependencies. You provide and configure Capybara, selenium-webdriver, and webdrivers in your own Gemfile, giving you full control over your test driver setup.
+**Note:** The generator creates system specs that require `rspec-rails`. If you're using Minitest, you'll need to manually create your accessibility tests.
+
+**Note:** As of version 1.2.0, the gem has minimal dependencies. You provide and configure Capybara, selenium-webdriver, webdrivers, and csv in your own Gemfile, giving you full control over your test driver setup.
+
+## 🆕 What's New in 1.5.0
+
+### Major Improvements
+
+1. **🎯 Live Accessibility Scanner**
+   - Real-time scanning as you browse during development
+   - Integrated with `bin/dev` via Procfile.dev
+   - Smart cancellation when navigating to new pages
+   - Detailed reporting showing exactly what's being scanned
+
+2. **📝 Enhanced Error Reporting**
+   - View files shown prominently instead of URLs
+   - Comprehensive overall test summaries
+   - Accurate error counting and persistent output
+   - Better context with view files and element details
+
+3. **🔍 Smart View File Detection**
+   - Automatically finds view files even when action names don't match
+   - Scans controller directories intelligently
+   - Handles edge cases and naming variations
+   - Advanced partial detection and mapping
+
+4. **⚡ Performance Optimizations**
+   - Page scanning cache prevents duplicate work
+   - Smart change detection only tests affected pages
+   - First-run optimization for faster initial setup
+
+4. **Enhanced Developer Experience**
+   - Friendly test summaries with clear counts and reasons
+   - Better error messages with precise file locations
+   - Cleaner output with suppressed verbose messages
+
+See [CHANGELOG.md](CHANGELOG.md) for complete details.
 
 ## 🤝 Contributing