capybara_accessibility_audit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c9d57dbd535b2d7c257f1dd19975788449178add55e5368aa3dec36ca7239612
+  data.tar.gz: 0a5b06b7b534d613052590db1242ef6c1d28db0820fcea718588c297aebcbc0b
+SHA512:
+  metadata.gz: 6d143c9f23767f861bc58481e0bd2513285de60b8fae286153c269ff52c36da9cf2aeca9a834d15e629bcd12b8dd49d364aadd6a25b5fcebdc861e42090ca395
+  data.tar.gz: 423c722319bcc0118f8ee87ca4927626a24f3a327f92469b8f8f1fb4540c4a871213bba05fd439d234fe49553057a3317094c8139ed8ebdfccb332bcba7f2563

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Sean Doyle
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,228 @@
+# CapybaraAccessibilityAudit
+
+:warning: This is pre-release software. :warning:
+
+Extend your Capybara-powered System Tests to automatically audit the page for
+WCAG Stardards-based accessibility violations.
+
+## Usage
+
+```
+Failure:
+Found 1 accessibility violation:
+
+1) label: Form elements must have labels (critical)
+    https://dequeuniversity.com/rules/axe/4.4/label?application=axeAPI
+    The following 1 node violate this rule:
+
+        Selector: input
+        HTML: <input>
+        Fix any of the following:
+        - Form element does not have an implicit (wrapped) <label>
+        - Form element does not have an explicit <label>
+        - aria-label attribute does not exist or is empty
+        - aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
+        - Element has no title attribute
+        - Element has no placeholder attribute
+        - Element's default semantics were not overridden with role="none" or role="presentation"
+
+Invocation: axe.run({:exclude=>[]}, {}, callback);
+```
+
+Installing the gem will automatically configure your System Tests to audit for
+accessibility violations after common actions, including:
+
+* [`visit`](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Session:visit)
+* [`click_button`](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Actions#click_button-instance_method)
+* [`click_link`](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Actions#click_link-instance_method)
+* [`click_link_or_button`](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Actions#click_link_or_button-instance_method)
+* [`click_on`](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Actions:click_on)
+
+Under the hood, `capybara_accessibility_audit` relies on [axe-core-rspec][], which uses [aXe][]
+to audit for accessibility violations. To configure which options are passed to
+the `be_axe_clean` matcher, override the class-level
+`accessibility_audit_options`. Supported keys include:
+
+* [`according_to:`](https://github.com/dequelabs/axe-core-gems/blob/develop/packages/axe-core-rspec/README.md#according_to---accessibility-standard-tag-clause)
+* [`checking_only:`](https://github.com/dequelabs/axe-core-gems/blob/develop/packages/axe-core-rspec/README.md#checking_only---exclusive-rules-clause)
+* [`checking:`](https://github.com/dequelabs/axe-core-gems/blob/develop/packages/axe-core-rspec/README.md#checking---checking-rules-clause)
+* [`excluding:`](https://github.com/dequelabs/axe-core-gems/blob/develop/packages/axe-core-rspec/README.md#excluding---exclusion-clause)
+* [`skipping:`](https://github.com/dequelabs/axe-core-gems/blob/develop/packages/axe-core-rspec/README.md#skipping---skipping-rules-clause)
+* [`within:`](https://github.com/dequelabs/axe-core-gems/blob/develop/packages/axe-core-rspec/README.md#within---inclusion-clause)
+
+To override the class-level setting, wrap code in calls to the
+`with_accessibility_audit_options` method:
+
+```ruby
+with_accessibility_audit_options according_to: :wcag21aaa do
+  visit page_with_violations_path
+end
+```
+
+[aXe]: https://www.deque.com/axe/
+[axe-core-rspec]: https://github.com/dequelabs/axe-core-gems/blob/develop/packages/axe-core-rspec/README.md#matcher
+
+## Frequently Asked Questions
+
+My application already exists, will automated accessibility audits are uncovering violations left and right. Do I have to fix them all at once?
+---
+
+Your suite has control over which rules are skipped and which rules are
+enforced through the `accessibility_audit_options` configuration.
+
+Configuration overrides can occur at any scope, ranging from class-wide to
+block-wide.
+
+For example, to skip a rule at the suite-level, override it in your
+`ApplicationSystemTestCase`:
+
+```ruby
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  accessibility_audit_options.skipping = %w[label button-name image-alt]
+end
+```
+
+To skip a rule at the test-level, wrap the test in a
+`with_accessibility_audit_options` block:
+
+```ruby
+class MySystemTest < ApplicationSystemTestCase
+  test "with overridden accessibility audit options" do
+    with_accessibility_audit_options skipping: %w[label button-name image-alt] do
+      visit examples_path
+      # ...
+    end
+  end
+end
+```
+
+To skip a rule at the block-level, wrap the code in a
+`with_accessibility_audit_options` block:
+
+```ruby
+class MySystemTest < ApplicationSystemTestCase
+  test "with overridden accessibility audit options" do
+    visit examples_path
+
+    with_accessibility_audit_options skipping: %w[label button-name image-alt] do
+      click_on "A link to a page with a violation"
+    end
+
+    # ...
+  end
+end
+```
+
+As you resolve the violations, you can remove entries from the list of skipped
+rules.
+
+I've implemented a custom Capybara action to toggle a disclosure element. How can I automatically audit for violations after it's called?
+---
+
+You can add the method to the list of methods that will initiate an automated
+audit:
+
+```ruby
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  def toggle_disclosure(locator)
+    # ...
+  end
+
+  accessibility_audit_after :toggle_disclosure
+end
+```
+
+How can I turn off auditing for the entire suite?
+---
+
+You can disable automated auditing within your `ApplicationSystemTestCase`:
+
+```ruby
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  self.accessibility_audit_enabled = false
+end
+```
+
+How can I turn off auditing for a block of code?
+---
+
+You can disable automated auditing temporarily by wrapping code in a
+`skip_accessibility_audits` block:
+
+```ruby
+class MySystemTest < ApplicationSystemTestCase
+  test "with overridden accessibility audit options" do
+    skip_accessibility_audits do
+      visit a_page_with_violations_path
+
+      click_on "A link to a page with a violation"
+    end
+
+    # ...
+  end
+end
+```
+
+How can I turn off auditing hooks for a method?
+---
+
+You can remove the method from the test's [Set][] of
+`accessibility_audit_after_methods` configuration by calling
+`skip_accessibility_audit_after`:
+
+```ruby
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  skip_accessibility_audit_after :visit
+end
+```
+
+[Set]: https://ruby-doc.org/stdlib-3.0.1/libdoc/set/rdoc/Set.html
+
+How can I turn off auditing for a test file?
+---
+
+You can disable automated auditing at the class-level:
+
+```ruby
+class MySystemTest < ApplicationSystemTestCase
+  self.accessibility_audit_enabled = false
+end
+```
+
+As you gradually address violations, you can re-enable audits within
+`with_accessibility_audits` blocks:
+
+```ruby
+class MySystemTest < ApplicationSystemTestCase
+  self.accessibility_audit_enabled = false
+
+  test "a test with a violation" do
+    visit examples_path
+
+    with_accessibility_audits do
+      click_on "A link to a page with violations"
+    end
+  end
+end
+```
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "capybara_accessibility_audit",
+  github: "thoughtbot/capybara_accessibility_audit",
+  branch: "main"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+## Contributing
+
+Please read [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,21 @@
+require "bundler/setup"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+require "standard/rake"
+
+namespace :test do
+  task :prepare do
+  end
+
+  desc "Runs all tests, including system tests"
+  task all: %w[test test:system]
+
+  desc "Run system tests only"
+  task system: %w[test:prepare] do
+    $: << "test"
+
+    Rails::TestUnit::Runner.rake_run(["test/system"])
+  end
+end

data/lib/capybara_accessibility_audit/audit_system_test_extensions.rb

@@ -0,0 +1,96 @@
+require "axe-capybara"
+require "axe/matchers/be_axe_clean"
+
+module CapybaraAccessibilityAudit
+  module AuditSystemTestExtensions
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :accessibility_audit_after_methods, default: Set.new
+      class_attribute :accessibility_audit_enabled, default: true
+      class_attribute :accessibility_audit_options, default: ActiveSupport::OrderedOptions.new
+    end
+
+    class_methods do
+      def inherited(descendant)
+        super
+
+        descendant.accessibility_audit_options = accessibility_audit_options.deep_dup
+        descendant.accessibility_audit_after_methods = accessibility_audit_after_methods.dup
+      end
+
+      def accessibility_audit_after(*methods)
+        (methods.flatten.to_set - accessibility_audit_after_methods).each do |method|
+          define_method method do |*arguments, **options, &block|
+            super(*arguments, **options, &block).tap { Auditor.new(self).audit!(method) }
+          end
+
+          accessibility_audit_after_methods << method
+        end
+      end
+
+      def skip_accessibility_audit_after(*methods)
+        methods.each { |method| accessibility_audit_after_methods.delete(method) }
+      end
+    end
+
+    delegate :accessibility_audit_after, :skip_accessibility_audit_after, to: :class
+
+    def with_accessibility_audits(**options, &block)
+      accessibility_audit_enabled = self.accessibility_audit_enabled
+      self.accessibility_audit_enabled = true
+
+      if options.present?
+        with_accessibility_audit_options(**options, &block)
+      else
+        block.call
+      end
+    ensure
+      self.accessibility_audit_enabled = accessibility_audit_enabled
+    end
+
+    def with_accessibility_audit_options(**options, &block)
+      accessibility_audit_options = self.accessibility_audit_options
+      self.accessibility_audit_options = accessibility_audit_options.merge(options)
+
+      block.call
+    ensure
+      self.accessibility_audit_options = accessibility_audit_options
+    end
+
+    def skip_accessibility_audits(&block)
+      accessibility_audit_enabled = self.accessibility_audit_enabled
+      self.accessibility_audit_enabled = false
+
+      block.call
+    ensure
+      self.accessibility_audit_enabled = accessibility_audit_enabled
+    end
+
+    def skip_accessibility_violations(value, &block)
+      skipping = accessibility_audit_options.skipping
+      accessibility_audit_options.skipping = Array(value)
+
+      block.call
+    ensure
+      accessibility_audit_options.skipping = skipping
+    end
+
+    def assert_no_accessibility_violations(**options)
+      options.assert_valid_keys(
+        :according_to,
+        :checking,
+        :checking_only,
+        :excluding,
+        :skipping,
+        :within
+      )
+      options.compact_blank!
+
+      axe_matcher = Axe::Matchers::BeAxeClean.new
+      axe_matcher = options.inject(axe_matcher) { |matcher, option| matcher.public_send(*option) }
+
+      assert axe_matcher.matches?(page), axe_matcher.failure_message
+    end
+  end
+end

data/lib/capybara_accessibility_audit/auditor.rb

@@ -0,0 +1,24 @@
+module CapybaraAccessibilityAudit
+  class Auditor
+    delegate_missing_to :@test
+
+    def initialize(test)
+      @test = test
+    end
+
+    def audit!(method)
+      if accessibility_audit_enabled && method.in?(accessibility_audit_after_methods) && javascript_enabled?
+        assert_no_accessibility_violations(**accessibility_audit_options)
+      end
+    end
+
+    private
+
+    def javascript_enabled?
+      case page.driver
+      when Capybara::RackTest::Driver then false
+      else true
+      end
+    end
+  end
+end

data/lib/capybara_accessibility_audit/engine.rb

@@ -0,0 +1,37 @@
+module CapybaraAccessibilityAudit
+  class Engine < ::Rails::Engine
+    config.capybara_accessibility_audit = ActiveSupport::OrderedOptions.new
+    config.capybara_accessibility_audit.audit_after = %i[
+      visit
+      click_button
+      click_link
+      click_link_or_button
+      click_on
+    ]
+    config.capybara_accessibility_audit.audit_enabled = true
+
+    ActiveSupport.on_load :action_dispatch_system_test_case do
+      include CapybaraAccessibilityAudit::AuditSystemTestExtensions
+
+      self.accessibility_audit_enabled = Rails.configuration.capybara_accessibility_audit.audit_enabled
+
+      accessibility_audit_after Rails.configuration.capybara_accessibility_audit.audit_after
+    end
+
+    if defined?(RSpec)
+      RSpec.configure do |config|
+        config.include CapybaraAccessibilityAudit::AuditSystemTestExtensions, type: :system
+        config.include CapybaraAccessibilityAudit::AuditSystemTestExtensions, type: :feature
+
+        configure = proc do
+          self.accessibility_audit_enabled = Rails.configuration.capybara_accessibility_audit.audit_enabled
+
+          accessibility_audit_after Rails.configuration.capybara_accessibility_audit.audit_after
+        end
+
+        config.before(type: :system, &configure)
+        config.before(type: :feature, &configure)
+      end
+    end
+  end
+end

data/lib/capybara_accessibility_audit/version.rb

@@ -0,0 +1,3 @@
+module CapybaraAccessibilityAudit
+  VERSION = "0.1.0"
+end

data/lib/capybara_accessibility_audit.rb

@@ -0,0 +1,9 @@
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module CapybaraAccessibilityAudit
+  # Your code goes here...
+end
+
+loader.eager_load

data/lib/tasks/capybara_accessibility_audit.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :capybara_accessibility_audit do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: capybara_accessibility_audit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sean Doyle
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-07-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: axe-core-capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Accessibility tooling for Capybara
+email:
+- sean.p.doyle24@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/capybara_accessibility_audit.rb
+- lib/capybara_accessibility_audit/audit_system_test_extensions.rb
+- lib/capybara_accessibility_audit/auditor.rb
+- lib/capybara_accessibility_audit/engine.rb
+- lib/capybara_accessibility_audit/version.rb
+- lib/tasks/capybara_accessibility_audit.rake
+homepage: https://github.com/thoughtbot/capybara_accessibility_audit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/thoughtbot/capybara_accessibility_audit
+  source_code_uri: https://github.com/thoughtbot/capybara_accessibility_audit
+  changelog_uri: https://github.com/thoughtbot/capybara_accessibility_audit/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Accessibility tooling for Capybara
+test_files: []