rails_accessibility_testing 1.5.5 → 1.5.6

data/docs_site/ci_integration.md

@@ -3,74 +3,129 @@ layout: default
 title: CI Integration
 ---
 
-# Continuous Integration with Rails Accessibility Testing
+# CI/CD Integration
 
-This guide shows you how to integrate Rails Accessibility Testing into your CI/CD pipeline to catch accessibility issues before they reach production.
+Automating accessibility tests in your Continuous Integration (CI) pipeline ensures no new violations are merged.
 
-## Why CI Integration?
-
-- **Catch issues early** - Before code is merged
-- **Prevent regressions** - Ensure fixes stay fixed
-- **Team accountability** - Everyone sees accessibility status
-- **Compliance tracking** - Document WCAG compliance
-
-## GitHub Actions
+---
 
-### Basic Setup
+## GitHub Actions (Recommended)
 
-Create `.github/workflows/accessibility.yml`:
+Add this workflow file to your project at `.github/workflows/accessibility.yml`:
 
 ```yaml
-name: Accessibility Tests
+name: Accessibility
 
-on:
-  pull_request:
-  push:
-    branches: [main]
+on: [push, pull_request]
 
 jobs:
-  accessibility:
+  scan:
     runs-on: ubuntu-latest
-    
     services:
       postgres:
         image: postgres:14
         env:
-          POSTGRES_PASSWORD: postgres
+          POSTGRES_PASSWORD: password
+        ports: ['5432:5432']
         options: >-
           --health-cmd pg_isready
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
-    
+
     steps:
       - uses: actions/checkout@v3
       
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 3.1
+          ruby-version: 3.2
           bundler-cache: true
-      
+          
       - name: Install Chrome
         run: |
           sudo apt-get update
           sudo apt-get install -y google-chrome-stable
-      
-      - name: Setup test database
+
+      - name: Setup Database
         env:
           RAILS_ENV: test
-          DATABASE_URL: postgres://postgres:postgres@localhost/test
+          DATABASE_URL: postgres://postgres:password@localhost:5432/test_db
         run: |
-          bundle exec rails db:create db:schema:load
-      
-      - name: Run accessibility tests
+          bin/rails db:create db:schema:load
+
+      - name: Run Accessibility Tests
         env:
           RAILS_ENV: test
-          DATABASE_URL: postgres://postgres:postgres@localhost/test
+          RAILS_A11Y_PROFILE: ci
         run: |
-          bundle exec rspec spec/system/ --format documentation
+          bundle exec rspec spec/system/
 ```
 
-For complete CI integration documentation, see the [CI Integration guide](https://github.com/rayraycodes/rails-accessibility-testing/blob/main/GUIDES/continuous_integration.md) in the main repository.
+---
+
+## CircleCI
+
+Add this job to your `.circleci/config.yml`:
 
+```yaml
+jobs:
+  accessibility_check:
+    docker:
+      - image: cimg/ruby:3.2-browsers
+      - image: cimg/postgres:14.0
+    environment:
+      RAILS_ENV: test
+      RAILS_A11Y_PROFILE: ci
+    steps:
+      - checkout
+      - ruby/install-deps
+      - run:
+          name: Wait for DB
+          command: dockerize -wait tcp://localhost:5432 -timeout 1m
+      - run:
+          name: Database Setup
+          command: bin/rails db:schema:load
+      - run:
+          name: Run Accessibility Scans
+          command: bundle exec rspec spec/system/
+```
+
+---
+
+## GitLab CI
+
+Add this to your `.gitlab-ci.yml`:
+
+```yaml
+accessibility_test:
+  image: ruby:3.2
+  services:
+    - postgres:14
+  variables:
+    RAILS_ENV: test
+    RAILS_A11Y_PROFILE: ci
+  before_script:
+    - apt-get update -q && apt-get install -y google-chrome-stable
+    - bundle install
+    - bin/rails db:create db:schema:load
+  script:
+    - bundle exec rspec spec/system/
+```
+
+---
+
+## Best Practices for CI
+
+1.  **Use the CI Profile:** Set `RAILS_A11Y_PROFILE=ci` to enable strict checks (like color contrast) that you might skip in development.
+2.  **Fail the Build:** Ensure your tests return a non-zero exit code if accessibility violations are found (this is the default behavior).
+3.  **Artifacts:** If using the static scanner's report output, save the generated HTML/JSON report as a build artifact.
+
+```yaml
+      - name: Upload Report
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: accessibility-report
+          path: coverage/accessibility/
+```

data/docs_site/configuration.md

@@ -5,17 +5,63 @@ title: Configuration
 
 # Configuration
 
-Rails Accessibility Testing works out of the box with zero configuration, but you can customize it to fit your needs.
+You can customize how the gem works by creating a `config/accessibility.yml` file.
 
-## YAML Configuration
+---
+
+## Quick Start Configuration
 
-Create `config/accessibility.yml` in your Rails app:
+Here is the configuration file structure that gets generated when you run the installer:
 
 ```yaml
+# config/accessibility.yml
+
 # WCAG compliance level (A, AA, AAA)
 wcag_level: AA
 
+# Summary configuration
+# Control how accessibility test summaries are displayed
+summary:
+  # Show summary at end of test suite (true/false)
+  show_summary: true
+  
+  # Show only errors in summary, hide warnings (true/false)
+  errors_only: false
+  
+  # Show fix suggestions in error messages (true/false)
+  show_fixes: true
+  
+  # Ignore warnings completely - only show errors (true/false)
+  ignore_warnings: false
+
+# Scanning strategy
+# 'paths' - Scan by visiting routes/paths (default)
+# 'view_files' - Scan by finding view files and visiting their routes
+scan_strategy: 'view_files'
+
+# Static scanner configuration
+# Controls behavior of the static file scanner (a11y_static_scanner)
+static_scanner:
+  # Only scan files that have changed since last scan (true/false)
+  scan_changed_only: true
+  
+  # Check interval in seconds when running continuously
+  check_interval: 3
+  
+  # Force full scan on startup (true/false)
+  full_scan_on_startup: true
+
+# System specs configuration
+# Controls behavior of accessibility checks in RSpec system specs
+system_specs:
+  # Automatically run accessibility checks after each system spec (true/false)
+  # When true, checks run automatically after each `visit` in system specs
+  # When false, checks only run when explicitly called (e.g., check_comprehensive_accessibility)
+  # Can be overridden per-profile (see profile sections below)
+  auto_run: true
+
 # Global check configuration
+# Set to false to disable a check globally
 checks:
   form_labels: true
   image_alt_text: true
@@ -27,88 +73,110 @@ checks:
   table_structure: true
   duplicate_ids: true
   skip_links: true
-  color_contrast: false  # Disabled by default (expensive)
+  color_contrast: false  # Disabled by default (requires JS evaluation)
+```
+
+---
+
+## Profiles (Environments)
+
+You can define different configurations for different environments:
+
+```yaml
+# ... base config above ...
 
-# Profile-specific configurations
 development:
   checks:
     color_contrast: false  # Skip in dev for speed
+  # system_specs:
+  #   auto_run: false  # Disable auto-run in development for faster tests
 
 test:
   checks:
     # Test environment uses global settings by default
+  # system_specs:
+  #   auto_run: true  # Enable auto-run in test (default)
 
 ci:
   checks:
     color_contrast: true   # Full checks in CI
+  # system_specs:
+  #   auto_run: true  # Always run in CI
+```
 
-# Ignored rules with reasons
-ignored_rules:
-  # - rule: form_labels
-  #   reason: "Legacy form, scheduled for refactor in Q2"
-  #   comment: "Will be fixed in PR #123"
+To run a specific profile:
+```bash
+RAILS_A11Y_PROFILE=ci bundle exec rspec
 ```
 
-## Ruby Configuration
+---
 
-Edit `config/initializers/rails_a11y.rb`:
+## Ignoring Specific Rules
 
-```ruby
-RailsAccessibilityTesting.configure do |config|
-  # Automatically run checks after system specs
-  config.auto_run_checks = true
-  
-  # Logger for accessibility check output
-  config.logger = Rails.logger
-  
-  # Configuration file path (relative to Rails.root)
-  config.config_path = 'config/accessibility.yml'
-  
-  # Default profile to use (development, test, ci)
-  config.default_profile = :test
-end
+Temporarily ignore specific rules while fixing issues:
+
+```yaml
+ignored_rules:
+  - rule: form_labels
+    reason: "Legacy form, scheduled for refactor in Q2"
+    comment: "Will be fixed in PR #123"
 ```
 
-## Profiles
+**Important:** Always include a reason and plan to fix. This is for temporary exceptions, not permanent workarounds.
 
-Use different configurations for different environments:
+---
 
-- **development**: Faster checks, skip expensive operations
-- **test**: Default settings, balanced checks
-- **ci**: Full checks, strict validation
+## System Specs Configuration
 
-Set the profile via environment variable:
+Control whether accessibility checks run automatically in system specs:
 
-```bash
-RAILS_A11Y_PROFILE=ci bundle exec rspec spec/system/
+```yaml
+# config/accessibility.yml
+system_specs:
+  auto_run: true  # Run checks automatically (default: true)
 ```
 
-## Ignoring Rules
+**When `auto_run: true`** (default):
+- Checks run automatically after each `visit` in system specs
+- No need to manually call `check_comprehensive_accessibility`
+- Great for continuous testing
 
-Temporarily ignore specific rules while fixing issues:
+**When `auto_run: false`**:
+- Checks only run when explicitly called
+- Use `check_comprehensive_accessibility` in your specs
+- Useful when you want more control over when checks run
+
+**Profile-specific overrides:**
 
 ```yaml
-ignored_rules:
-  - rule: form_labels
-    reason: "Legacy form, scheduled for refactor in Q2"
-    comment: "Will be fixed in PR #123"
+development:
+  system_specs:
+    auto_run: false  # Disable in development for faster tests
+
+test:
+  system_specs:
+    auto_run: true   # Always run in test environment
+
+ci:
+  system_specs:
+    auto_run: true   # Always run in CI
 ```
 
-**Important:** Always include a reason and plan to fix. This is for temporary exceptions, not permanent workarounds.
+**Note:** YAML configuration takes precedence over the Ruby initializer configuration. If `system_specs.auto_run` is set in YAML, it will override `config.auto_run_checks` from the initializer.
 
-## Skipping Checks in Tests
+---
 
-Skip accessibility checks for specific tests:
+## Ruby Configuration
 
-```ruby
-# RSpec
-it "does something", skip_a11y: true do
-  # Accessibility checks won't run
-end
+For advanced setup (like changing the logger), create an initializer:
 
-# Minitest
-test "does something", skip_a11y: true do
-  # Accessibility checks won't run
+```ruby
+# config/initializers/rails_a11y.rb
+RailsAccessibilityTesting.configure do |config|
+  config.auto_run_checks = true  # Note: Can be overridden by YAML config
+  config.logger = Rails.logger
+  config.default_profile = :test
 end
 ```
 
+**Important:** The YAML `system_specs.auto_run` setting takes precedence over `config.auto_run_checks` from the initializer. Use YAML for environment-specific control.

data/docs_site/contributing.md

@@ -7,7 +7,11 @@ title: Contributing
 
 Thank you for your interest in contributing to Rails Accessibility Testing! This document provides guidelines and instructions for contributing.
 
-## Getting Started
+## 🤝 Code of Conduct
+
+This project adheres to a code of conduct that all contributors are expected to follow. Please be respectful and constructive in all interactions.
+
+## 🚀 Getting Started
 
 ### Prerequisites
 
@@ -19,27 +23,31 @@ Thank you for your interest in contributing to Rails Accessibility Testing! This
 ### Setting Up Development Environment
 
 1. **Fork the repository**
-2. **Clone your fork**
    ```bash
+   # Fork on GitHub, then clone your fork
    git clone https://github.com/your-username/rails-accessibility-testing.git
    cd rails-accessibility-testing
    ```
 
-3. **Install dependencies**
+2. **Install dependencies**
    ```bash
    bundle install
    ```
 
-4. **Run tests**
+3. **Run tests**
    ```bash
    bundle exec rspec
    ```
 
-## Making Changes
+## 📝 Making Changes
+
+### Development Workflow
 
 1. **Create a branch**
    ```bash
    git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/your-bug-fix
    ```
 
 2. **Make your changes**
@@ -64,6 +72,158 @@ Thank you for your interest in contributing to Rails Accessibility Testing! This
    ```
 
 6. **Open a Pull Request**
+   - Go to the original repository on GitHub
+   - Click "New Pull Request"
+   - Select your branch
+   - Fill out the PR template
+
+## 📋 Commit Message Guidelines
+
+We follow conventional commit message format:
+
+```
+type: short description
+
+Longer description if needed
+
+- Bullet point 1
+- Bullet point 2
+```
+
+**Types:**
+- `Add:` - New feature
+- `Fix:` - Bug fix
+- `Update:` - Update existing feature
+- `Refactor:` - Code refactoring
+- `Docs:` - Documentation changes
+- `Test:` - Test additions/changes
+- `Chore:` - Maintenance tasks
+
+**Examples:**
+```
+Add: support for custom accessibility rules
+
+Allows users to define custom accessibility checks
+beyond the default 11 checks.
+
+- Add configuration for custom rules
+- Add validation for custom rule format
+- Update documentation
+```
+
+## 🧪 Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/path/to/spec.rb
+
+# Run with coverage
+COVERAGE=true bundle exec rspec
+```
+
+### Writing Tests
+
+- Write tests for all new features
+- Ensure existing tests still pass
+- Aim for good test coverage
+- Test edge cases
+
+## 📚 Documentation
+
+### Updating Documentation
+
+- Update README.md for user-facing changes
+- Update CHANGELOG.md for all changes
+- Update inline code documentation
+- Update setup guides if needed
+
+### Documentation Standards
+
+- Use clear, concise language
+- Include code examples
+- Explain the "why" not just the "what"
+- Keep examples up-to-date
+
+## 🐛 Reporting Bugs
+
+### Before Submitting
+
+1. Check if the bug has already been reported
+2. Check if it's fixed in the latest version
+3. Try to reproduce the issue
+
+### Bug Report Template
+
+```markdown
+**Describe the bug**
+A clear description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce:
+1. ...
+2. ...
+
+**Expected behavior**
+What you expected to happen.
+
+**Actual behavior**
+What actually happened.
+
+**Environment**
+- Ruby version:
+- Rails version:
+- RSpec version:
+- Gem version:
+
+**Additional context**
+Any other relevant information.
+```
+
+## 💡 Suggesting Features
+
+### Feature Request Template
+
+```markdown
+**Is your feature request related to a problem?**
+A clear description of the problem.
+
+**Describe the solution you'd like**
+What you want to happen.
+
+**Describe alternatives you've considered**
+Other solutions you've thought about.
+
+**Additional context**
+Any other relevant information.
+```
+
+## 🔍 Code Review Process
+
+1. All PRs require at least one approval
+2. Maintainers will review your code
+3. Address any feedback
+4. Once approved, maintainers will merge
+
+## 📦 Releasing
+
+Only maintainers can release new versions. The process:
+
+1. Update version in `lib/rails_accessibility_testing/version.rb`
+2. Update CHANGELOG.md
+3. Create git tag
+4. Build and push gem to RubyGems
+
+## ❓ Questions?
+
+- Open an issue for questions
+- Check existing issues and discussions
+- Email: imregan@umich.edu
 
-For complete contributing guidelines, see [CONTRIBUTING.md](https://github.com/rayraycodes/rails-accessibility-testing/blob/main/CONTRIBUTING.md) in the main repository.
+## 🙏 Thank You!
 
+Your contributions make this project better for everyone. Thank you for taking the time to contribute!

data/docs_site/favicon.svg

@@ -0,0 +1,31 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <defs>
+    <linearGradient id="bgGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#CC0000;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#8B0000;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient id="checkGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#4CAF50;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#2E7D32;stop-opacity:1" />
+    </linearGradient>
+  </defs>
+  
+  <!-- Background circle with Rails red -->
+  <circle cx="50" cy="50" r="48" fill="url(#bgGrad)" stroke="#fff" stroke-width="2"/>
+  
+  <!-- Letter "A" for Accessibility -->
+  <path d="M 50 20 L 35 75 M 50 20 L 65 75 M 40 55 L 60 55" 
+        stroke="#fff" 
+        stroke-width="6" 
+        stroke-linecap="round" 
+        stroke-linejoin="round" 
+        fill="none"/>
+  
+  <!-- Checkmark overlay centered (representing testing/validation) -->
+  <path d="M 35 50 L 45 60 L 65 40" 
+        stroke="url(#checkGrad)" 
+        stroke-width="5" 
+        stroke-linecap="round" 
+        stroke-linejoin="round" 
+        fill="none"/>
+</svg>