rails_accessibility_testing 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 44226ec4973a99bf8f1547ea8097b1692149aff661462c49e49f231fa922ee68
+  data.tar.gz: 6cbe080229e8ab7895b9a43c318e613b23c9f47630ee3d059f3c62a155d79840
+SHA512:
+  metadata.gz: 6a9ebf9993e2e0c62ebfee115edd8af562ea7545ad9ea3324e76f08d2cc0ad7617d92c7703a8cac2eb703381b4e8737b57e6fb238fb90918aecfe84c383ef65d
+  data.tar.gz: 2c8063de81c13388d38f01b289a6cf5a806aac8e0e176496857a4c4fbc714a18f187c2fb90d846cefded37e5e2896454eaddbfa87a98262548a420633c95aec4

data/ARCHITECTURE.md

@@ -0,0 +1,307 @@
+# Rails Accessibility Testing Gem - Architecture Overview
+
+## Project Identity
+
+### Gem Name Options
+
+After careful consideration, we've selected:
+
+**Final Name: `rails_accessibility_testing`**
+
+**Note:** The gem uses `rails_a11y` as a short alias for the generator command and CLI tool, but the official gem name is `rails_accessibility_testing`.
+
+**Alternative names considered:**
+1. `rails_accessibility_testing` - **SELECTED** - Clear and descriptive
+2. `rails_a11y` - Short alias used for CLI and generator
+3. `a11y_rails` - Alternative short form
+4. `accessible_rails` - Descriptive but longer
+
+### Tagline
+
+**"The RSpec + RuboCop of accessibility for Rails. Catch WCAG violations before they reach production."**
+
+### Positioning Statement
+
+Rails Accessibility Testing fills a critical gap in the Rails testing ecosystem. While RSpec ensures code works and RuboCop ensures code style, Rails Accessibility Testing ensures applications are accessible to everyone. Unlike manual accessibility audits that happen late in development, Rails Accessibility Testing integrates directly into your test suite, catching violations as you code. It's opinionated enough to guide teams new to accessibility, yet configurable enough for experienced teams. By making accessibility testing as natural as unit testing, Rails Accessibility Testing helps teams build accessible applications from day one, not as an afterthought.
+
+---
+
+## Architecture Overview
+
+### Core Principles
+
+1. **DevX First**: Every feature prioritizes developer experience
+2. **Accessibility at Core**: WCAG 2.1 AA compliance is the foundation
+3. **Rails Native**: Feels like a natural part of Rails, not a bolt-on
+4. **Progressive Enhancement**: Works with zero config, scales with configuration
+
+### Component Architecture
+
+```
+rails_a11y/
+├── Core Engine
+│   ├── Rule Engine          # Evaluates accessibility rules
+│   ├── Check Definitions    # WCAG-aligned check implementations
+│   └── Violation Collector  # Aggregates and formats violations
+│
+├── Rails Integration
+│   ├── Railtie             # Rails initialization hooks
+│   ├── RSpec Integration    # RSpec helpers and matchers
+│   ├── Minitest Integration # Minitest helpers
+│   └── System Test Helpers  # Capybara integration
+│
+├── Configuration
+│   ├── YAML Config Loader   # Loads config/accessibility.yml
+│   ├── Profile Manager      # Dev/test/CI profiles
+│   └── Rule Overrides       # Ignore rules with comments
+│
+├── CLI
+│   ├── Command Runner       # Main CLI entry point
+│   ├── URL Scanner          # Scans URLs/routes
+│   └── Report Generator     # Human-readable + JSON reports
+│
+├── Generators
+│   └── Install Generator    # Rails generator for setup
+│
+└── Documentation
+    ├── Guides/              # Practical guides
+    ├── API Docs (YARD)      # Generated documentation
+    └── Doc Site             # Static documentation site
+```
+
+### Data Flow
+
+```
+Test Execution
+    ↓
+System Test Helper (RSpec/Minitest)
+    ↓
+Rule Engine
+    ↓
+Check Definitions (11+ checks)
+    ↓
+Violation Collector
+    ↓
+Error Message Builder
+    ↓
+Test Failure / CLI Report
+```
+
+### Rule Engine Design
+
+The rule engine is the heart of the gem. It:
+
+1. **Loads Configuration**: Reads `config/accessibility.yml` with profile support**
+2. **Applies Rule Overrides**: Respects ignored rules with comments
+3. **Executes Checks**: Runs enabled checks in order
+4. **Collects Violations**: Aggregates all violations before reporting
+5. **Formats Output**: Creates actionable error messages
+
+### Check Definition Structure
+
+Each check is a self-contained class that:
+
+- Implements a standard interface
+- Returns violations with context
+- Includes WCAG references
+- Provides remediation suggestions
+- Can be enabled/disabled via config
+
+---
+
+## Key Design Decisions
+
+### 1. YAML Configuration
+
+**Why YAML?** 
+- Human-readable and comment-friendly
+- Easy to version control
+- Familiar to Rails developers
+- Supports profiles (dev/test/CI)
+
+### 2. Rule-Based Architecture
+
+**Why separate rules?**
+- Easy to enable/disable specific checks
+- Allows teams to gradually adopt stricter rules
+- Makes it easy to add custom rules later
+- Clear separation of concerns
+
+### 3. Violation Collection vs Immediate Failure
+
+**Why collect then fail?**
+- Shows all issues at once (better DX)
+- Allows prioritization
+- More efficient than stopping at first error
+- Better for CI/CD reports
+
+### 4. View File Detection
+
+**Why detect view files?**
+- Points developers to exact file to fix
+- Works with partials and layouts
+- Reduces debugging time
+- Makes errors actionable
+
+### 5. Dual Test Framework Support
+
+**Why both RSpec and Minitest?**
+- Rails teams use both
+- Reduces friction for adoption
+- Shared core logic, different interfaces
+- Better market fit
+
+---
+
+## File Structure
+
+```
+lib/
+├── rails_a11y.rb                    # Main entry point
+├── rails_a11y/
+│   ├── version.rb
+│   ├── configuration.rb             # Config management
+│   ├── railtie.rb                   # Rails integration
+│   │
+│   ├── engine/
+│   │   ├── rule_engine.rb           # Core rule evaluator
+│   │   ├── violation_collector.rb   # Aggregates violations
+│   │   └── check_context.rb         # Context for checks
+│   │
+│   ├── checks/
+│   │   ├── base_check.rb            # Base class for all checks
+│   │   ├── form_labels_check.rb
+│   │   ├── image_alt_text_check.rb
+│   │   ├── interactive_elements_check.rb
+│   │   ├── heading_hierarchy_check.rb
+│   │   ├── keyboard_accessibility_check.rb
+│   │   ├── aria_landmarks_check.rb
+│   │   ├── form_errors_check.rb
+│   │   ├── table_structure_check.rb
+│   │   ├── duplicate_ids_check.rb
+│   │   ├── skip_links_check.rb
+│   │   └── color_contrast_check.rb   # New
+│   │
+│   ├── integration/
+│   │   ├── rspec_integration.rb
+│   │   ├── minitest_integration.rb
+│   │   └── system_test_helper.rb    # Shared Capybara helpers
+│   │
+│   ├── cli/
+│   │   ├── command.rb                # Main CLI command
+│   │   ├── url_scanner.rb            # Scans URLs/routes
+│   │   └── report_generator.rb       # Generates reports
+│   │
+│   ├── config/
+│   │   ├── yaml_loader.rb            # Loads YAML config
+│   │   ├── profile_manager.rb        # Manages profiles
+│   │   └── rule_override.rb          # Handles ignored rules
+│   │
+│   ├── errors/
+│   │   ├── error_message_builder.rb  # Formats error messages
+│   │   └── violation_formatter.rb   # Formats individual violations
+│   │
+│   └── utils/
+│       ├── view_file_detector.rb     # Detects view files
+│       └── wcag_reference.rb         # WCAG reference data
+│
+├── generators/
+│   └── rails_a11y/
+│       └── install/
+│           ├── generator.rb
+│           └── templates/
+│               ├── initializer.rb.erb
+│               └── accessibility.yml.erb
+│
+└── tasks/
+    └── accessibility.rake            # Rake tasks
+
+exe/
+└── rails_a11y                        # CLI executable
+
+GUIDES/
+├── getting_started.md
+├── continuous_integration.md
+├── working_with_designers_and_content_authors.md
+└── writing_accessible_views_in_rails.md
+
+docs_site/
+├── index.html
+├── usage.html
+├── configuration.html
+├── ci_integration.html
+└── contributing.html
+```
+
+---
+
+## Extension Points
+
+### Adding Custom Checks
+
+```ruby
+module RailsA11y
+  module Checks
+    class CustomCheck < BaseCheck
+      def check
+        # Implementation
+      end
+    end
+  end
+end
+```
+
+### Custom Error Formatters
+
+```ruby
+module RailsA11y
+  module Errors
+    class CustomFormatter < ViolationFormatter
+      # Custom formatting logic
+    end
+  end
+end
+```
+
+### Profile-Specific Configuration
+
+```yaml
+# config/accessibility.yml
+development:
+  checks:
+    color_contrast: false  # Skip in dev for speed
+
+ci:
+  checks:
+    color_contrast: true   # Full checks in CI
+```
+
+---
+
+## Performance Considerations
+
+1. **Lazy Loading**: Checks loaded only when needed
+2. **Caching**: View file detection cached
+3. **Parallel Execution**: Checks can run in parallel (future)
+4. **Selective Execution**: Only run checks for changed files (existing feature)
+5. **Configurable Depth**: Expensive checks behind flags
+
+---
+
+## Testing Strategy
+
+1. **Unit Tests**: Each check tested in isolation
+2. **Integration Tests**: Full Rails app with RSpec/Minitest
+3. **CLI Tests**: Test CLI against real Rails routes
+4. **Documentation Tests**: Ensure examples work
+
+---
+
+## Future Enhancements
+
+1. **Custom Rules**: Allow teams to define custom checks
+2. **Visual Regression**: Screenshot comparison for visual issues
+3. **Performance Monitoring**: Track check performance
+4. **IDE Integration**: VS Code/IntelliJ plugins
+5. **CI/CD Templates**: Pre-built GitHub Actions, CircleCI configs
+

data/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+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.1.0] - 2024-11-15
+
+### Added
+- GitHub Pages documentation site with Jekyll
+- Comprehensive GitHub Actions workflow for automatic documentation deployment
+- Enhanced workflow diagnostics and verification steps
+- Test step to verify index.html exists before deployment
+- Improved error messages and troubleshooting guides
+- Token support for GitHub Pages deployment (OIDC with PAT fallback)
+
+### Improved
+- Better artifact structure verification in CI/CD
+- Enhanced deployment diagnostics
+- More detailed build output and verification steps
+- Improved documentation structure and organization
+
+### Fixed
+- Jekyll build configuration and dependencies
+- GitHub Pages deployment path isolation
+- Artifact structure for subdirectory deployment
+
+## [1.0.0] - 2024-11-14
+
+### Added
+- Initial release of Rails Accessibility Testing gem
+- Automatic accessibility checking for Rails system specs
+- 11+ comprehensive accessibility checks:
+  - Form labels
+  - Image alt text
+  - Interactive element names
+  - Heading hierarchy
+  - Keyboard accessibility
+  - ARIA landmarks
+  - Form error associations
+  - Table structure
+  - Duplicate IDs
+  - Skip links
+  - Color contrast (optional)
+- Rule engine architecture for extensible checks
+- YAML configuration system with profile support (development, test, ci)
+- CLI tool (`rails_a11y`) for checking URLs and routes
+- Rails generator (`rails generate rails_a11y:install`) for easy setup
+- RSpec integration with automatic hooks
+- Minitest integration for system tests
+- Automatic system spec detection by file location
+- Smart change detection (only runs when code changes)
+- Detailed error messages with file locations and remediation steps
+- WCAG 2.1 AA compliance references
+- Zero-configuration setup with sensible defaults
+- Skip checks for specific tests via `skip_a11y: true` metadata
+- Manual comprehensive check method `check_comprehensive_accessibility`
+- Comprehensive documentation:
+  - Getting Started guide
+  - Continuous Integration guide
+  - Writing Accessible Views guide
+  - Working with Designers guide
+  - Architecture documentation
+- Error message builder with semantic element names
+- View file detection including partials and layouts
+- Batch error collection (reports all errors, not just first)
+- Human-readable and JSON report formats
+- Profile-based configuration for different environments
+
+### Technical Details
+- Built on axe-core-capybara for WCAG testing
+- Integrates with RSpec Rails and Minitest
+- Uses Capybara for browser automation
+- Supports Rails 6.0+ and Ruby 3.0+
+- Compatible with RSpec Rails 6.0+
+- Modular architecture with rule engine and check definitions
+
+[1.1.0]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.1.0
+[1.0.0]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.0.0
+

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,125 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently
+any contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+imregan@umich.edu. All complaints will be reviewed and investigated promptly and
+fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
+