Support executing with :cuprite and :playwright drivers

In an effort to support more than Selenium-based drivers, this change
modifies the underlying `axe.js` integration.

Prior to this change, this gem relied entirely on the [axe-core-api][]
dependency to execute the audit, collect the results, and raise any
violations as testing exceptions.

Unfortunately, that gem does not provide official support for drivers
other than Selenium ([axe-core-gems#243][]).

To account for that shortcoming, this commit changes the gem to
integrate with the `axe.js` JavaScript code more directly, including
changes that invoke the interface directly through a combination of
Capybara's [execute_script][], [evaluate_script][], and
[evaluate_async_script][].

In support of that integration, this commit also extracts the
`AxeAuditor` and `RaiseReporter` classes for the sake of abstracting the
auditing and reporting steps (and for future integrations with other
styles of audit reporting).

[axe-core-api]: https://github.com/dequelabs/axe-core-gems/tree/develop/packages/axe-core-api
[axe-core-gems#243]: dequelabs/axe-core-gems#243
[execute_script]: https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Session:execute_script
[evaluate_script]: https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Session:evaluate_script
[evaluate_async_script]: https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Session:evaluate_async_script

Author: seanpdoyle

.github/workflows/ci.yml

@@ -8,6 +8,10 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        driver:
+          - "cuprite"
+          - "playwright"
+          - "selenium_chrome_headless"
         ruby-version:
           - "3.2"
           - "3.3"
@@ -19,9 +23,10 @@ jobs:
           - "7.2"
 
     env:
+      DRIVER: ${{ matrix.driver }}
       RAILS_VERSION: ${{ matrix.rails-version }}
 
-    name: ${{ format('Tests (Ruby {0}, Rails {1})', matrix.ruby-version, matrix.rails-version) }}
+    name: ${{ format('Tests (Ruby {0}, Rails {1}, {2})', matrix.ruby-version, matrix.rails-version, matrix.driver) }}
     runs-on: "ubuntu-latest"
 
     steps:
@@ -31,6 +36,14 @@ jobs:
           ruby-version: ${{ matrix.ruby-version }}
           bundler-cache: true
 
+      - if: ${{ matrix.driver == 'playwright' }}
+        uses: "actions/setup-node@v5"
+        with:
+          cache: "yarn"
+
+      - if: ${{ matrix.driver == 'playwright' }}
+        run: yarn install && yarn playwright install
+
       - run: bin/rails standard
         if: matrix.ruby-version != 3.2
       - run: bin/rails test:all

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- Add support for `:cuprite` and `:playwright` system test drivers
 - Drop support for [End of Life Ruby versions 3.0 and 3.1](https://www.ruby-lang.org/en/downloads/branches/)
 - Drop support for [End of Life Rails versions 6.1, 7.0, and 7.1](https://rubyonrails.org/maintenance)
 

Gemfile

@@ -7,7 +7,7 @@ gemspec
 # Start debugger with binding.b [https://github.com/ruby/debug]
 # gem "debug", ">= 1.0.0"
 
-rails_version = ENV.fetch("RAILS_VERSION", "7.0")
+rails_version = ENV.fetch("RAILS_VERSION", "7.2")
 
 rails_constraint = if rails_version == "main"
   {github: "rails/rails"}
@@ -20,4 +20,6 @@ gem "rspec-rails"
 
 gem "puma"
 gem "standard", "~> 1.12"
+gem "capybara-playwright-driver", require: "capybara/playwright"
+gem "cuprite", require: "capybara/cuprite"
 gem "selenium-webdriver"

…/capybara_accessibility_audit/auditor.rb …/capybara_accessibility_audit/adapter.rblib/capybara_accessibility_audit/auditor.rb renamed to lib/capybara_accessibility_audit/adapter.rb lib/capybara_accessibility_audit/auditor.rb renamed to lib/capybara_accessibility_audit/adapter.rb

@@ -1,5 +1,5 @@
 module CapybaraAccessibilityAudit
-  class Auditor
+  class Adapter
     delegate_missing_to :@test
 
     def initialize(test)

lib/capybara_accessibility_audit/audit_system_test_extensions.rb

@@ -1,5 +1,3 @@
-require "axe/matchers/be_axe_clean"
-
 module CapybaraAccessibilityAudit
   module AuditSystemTestExtensions
     extend ActiveSupport::Concern
@@ -19,7 +17,7 @@ module AuditSystemTestExtensions
       MODAL_METHODS.each do |method|
         define_method method do |*arguments, **options, &block|
           result = super(*arguments, **options) { skip_accessibility_audits(&block) }
-          result.tap { Auditor.new(self).audit!(method) }
+          result.tap { Adapter.new(self).audit!(method) }
         end
       end
     end
@@ -35,7 +33,7 @@ def inherited(descendant)
       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) }
+            super(*arguments, **options, &block).tap { Adapter.new(self).audit!(method) }
           end
 
           accessibility_audit_after_methods << method
@@ -89,7 +87,7 @@ def skip_accessibility_violations(value, &block)
       accessibility_audit_options.skipping = skipping
     end
 
-    def assert_no_accessibility_violations(**options)
+    def assert_no_accessibility_violations(auditor: @accessibility_audit_auditor, **options)
       options.assert_valid_keys(
         :according_to,
         :checking,
@@ -100,10 +98,7 @@ def assert_no_accessibility_violations(**options)
       )
       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
+      auditor.audit(**options)
     end
   end
 end

lib/capybara_accessibility_audit/axe_auditor.rb

@@ -0,0 +1,59 @@
+require "axe/api/context"
+require "axe/api/options"
+require "axe/api/results"
+require "axe/configuration"
+
+module CapybaraAccessibilityAudit
+  class AxeAuditor
+    class_attribute :source, instance_accessor: false, default: Axe::Configuration.instance.jslib
+
+    def initialize(page, reporter)
+      @page = page
+      @reporter = reporter
+    end
+
+    def audit(**options)
+      install
+
+      results = run(options)
+
+      @reporter.report Axe::API::Results.new(results)
+    end
+
+    private
+
+    def run(config)
+      context, options = split(config)
+
+      @page.evaluate_async_script <<~JS, context.to_h, options.to_h
+        const [ context, options, callback ] = arguments
+
+        axe.run(context, options).then(callback)
+      JS
+    end
+
+    def split(config)
+      context = Axe::API::Context.new
+      options = Axe::API::Options.new
+
+      config.each do |name, value|
+        case name
+        when :within, :excluding then context.public_send(name, value)
+        else options.public_send(name, value)
+        end
+      end
+
+      [context, options]
+    end
+
+    def install
+      @page.execute_script(self.class.source) unless installed?
+    end
+
+    def installed?
+      @page.evaluate_script <<~JS
+        "axe" in window && typeof axe.run === "function"
+      JS
+    end
+  end
+end

lib/capybara_accessibility_audit/engine.rb

@@ -1,6 +1,7 @@
 module CapybaraAccessibilityAudit
   class Engine < ::Rails::Engine
     config.capybara_accessibility_audit = ActiveSupport::OrderedOptions.new
+    config.capybara_accessibility_audit.auditor = AxeAuditor
     config.capybara_accessibility_audit.audit_after = %i[
       visit
       click_button
@@ -9,6 +10,7 @@ class Engine < ::Rails::Engine
       click_on
     ]
     config.capybara_accessibility_audit.audit_enabled = true
+    config.capybara_accessibility_audit.reporter = RaiseReporter
 
     initializer "capybara_accessibility_audit.minitest" do |app|
       ActiveSupport.on_load :action_dispatch_system_test_case do
@@ -17,6 +19,13 @@ class Engine < ::Rails::Engine
         self.accessibility_audit_enabled = app.config.capybara_accessibility_audit.audit_enabled
 
         accessibility_audit_after app.config.capybara_accessibility_audit.audit_after
+
+        setup do
+          auditor_class = app.config.capybara_accessibility_audit.auditor
+          reporter_class = app.config.capybara_accessibility_audit.reporter
+
+          @accessibility_audit_auditor = auditor_class.new(page, reporter_class.new(self))
+        end
       end
     end
 
@@ -32,6 +41,11 @@ class Engine < ::Rails::Engine
             self.accessibility_audit_enabled = app.config.capybara_accessibility_audit.audit_enabled
 
             accessibility_audit_after app.config.capybara_accessibility_audit.audit_after
+
+            auditor_class = app.config.capybara_accessibility_audit.auditor
+            reporter_class = app.config.capybara_accessibility_audit.reporter
+
+            @accessibility_audit_auditor = auditor_class.new(page, reporter_class.new(self))
           end
 
           config.before(type: :system, &configure)

lib/capybara_accessibility_audit/raise_reporter.rb

@@ -0,0 +1,11 @@
+module CapybaraAccessibilityAudit
+  class RaiseReporter
+    def initialize(test)
+      @test = test
+    end
+
+    def report(results)
+      @test.assert results.violations.empty?, -> { results.failure_message }
+    end
+  end
+end

package.json

@@ -0,0 +1,5 @@
+{
+  "devDependencies": {
+    "playwright": "1.57.0"
+  }
+}

spec/spec_helper.rb

@@ -7,18 +7,11 @@
 
 Dummy::Application.initialize!
 
-module FeatureSpecBackports
-  def driven_by(name, **)
-    Capybara.current_driver = Capybara.javascript_driver = name
-  end
-end
-
 RSpec.configure do |config|
   config.use_active_record = false
 
   config.filter_rails_from_backtrace!
-
-  config.include FeatureSpecBackports, type: :feature
 end
 
+Capybara.javascript_driver = ENV.fetch("DRIVER", "selenium_chrome_headless").to_sym
 Capybara.server = :puma, {Silent: true}