Integrate with Active Support instrumentation

Capybara Accessibility Audit integrates with [Active Support's
instrumentation][] through publishing [ActiveSupport::Notifications][].

`audit.capybara_accessibility_audit` notification
---

Subscribe to `audit.capybara_accessibility_audit` notifications emitted
when an accessibility audit is automatically conducted. In addition to
the metadata provided by default (like `name`, `duration`, and
`allocations`, etc.), the `payload` includes additional information:

| Payload       | Type                               | Description |
| ------------- | ---------------------------------- | ----------- |
| method        | Symbol                             | The Capybara method that triggered the audit
| options       | [ActiveSupport::OrderedOptions][]  | The audit's configuration
| test          | [ActionDispatch::SystemTestCase][] | The test case that triggered the audit

> [!NOTE]
> The `audit.capybara_accessibility_audit` notifications are only published when
> an audit is conducted automatically. No `audit.capybara_accessibility_audit`
> notifications will be published when `assert_no_accessibility_violations` is
> invoked directly.

[Active Support's instrumentation]: https://guides.rubyonrails.org/active_support_instrumentation.html
[ActiveSupport::Notifications]: https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html
[ActiveSupport::OrderedOptions]: https://api.rubyonrails.org/classes/ActiveSupport/OrderedOptions.html
[ActionDispatch::SystemTestCase]: https://api.rubyonrails.org/classes/ActionDispatch/SystemTestCase.html

Author: seanpdoyle

Gemfile

@@ -18,6 +18,7 @@ end
 gem "rails", rails_constraint
 gem "rspec-rails"
 
+gem "minitest", "< 6"
 gem "puma"
 gem "standard", "~> 1.12"
 gem "capybara-playwright-driver", require: "capybara/playwright"

README.md

@@ -60,6 +60,35 @@ 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
 
+## Active Support instrumentation
+
+Capybara Accessibility Audit integrates with [Active Support's
+instrumentation][] through publishing [ActiveSupport::Notifications][].
+
+### `audit.capybara_accessibility_audit` notification
+
+Subscribe to `audit.capybara_accessibility_audit` notifications emitted when an
+accessibility audit is automatically conducted. In addition to the
+metadata provided by default (like `name`, `duration`, and `allocations`, etc.),
+the `payload` includes additional information:
+
+| Payload       | Type                               | Description |
+| ------------- | ---------------------------------- | ----------- |
+| method        | Symbol                             | The Capybara method that triggered the audit
+| options       | [ActiveSupport::OrderedOptions][]  | The audit's configuration
+| test          | [ActionDispatch::SystemTestCase][] | The test case that triggered the audit
+
+> [!NOTE]
+> The `audit.capybara_accessibility_audit` notifications are only published when
+> an audit is conducted automatically. No `audit.capybara_accessibility_audit`
+> notifications will be published when `assert_no_accessibility_violations` is
+> invoked directly.
+
+[Active Support's instrumentation]: https://guides.rubyonrails.org/active_support_instrumentation.html
+[ActiveSupport::Notifications]: https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html
+[ActiveSupport::OrderedOptions]: https://api.rubyonrails.org/classes/ActiveSupport/OrderedOptions.html
+[ActionDispatch::SystemTestCase]: https://api.rubyonrails.org/classes/ActionDispatch/SystemTestCase.html
+
 ## Frequently Asked Questions
 
 My application already exists, automated accessibility audits are uncovering violations left and right. Do I have to fix them all at once?

lib/capybara_accessibility_audit/adapter.rb

@@ -8,7 +8,13 @@ def initialize(test)
 
     def audit!(method)
       if accessibility_audit_enabled && method.in?(accessibility_audit_after_methods) && javascript_enabled?
-        assert_no_accessibility_violations(**accessibility_audit_options)
+        ActiveSupport::Notifications.instrument "audit.capybara_accessibility_audit" do |payload|
+          payload[:method] = method
+          payload[:options] = accessibility_audit_options
+          payload[:test] = @test
+
+          assert_no_accessibility_violations(**accessibility_audit_options)
+        end
       end
     end
 

lib/capybara_accessibility_audit/audit_system_test_extensions.rb

@@ -87,7 +87,8 @@ def skip_accessibility_violations(value, &block)
       accessibility_audit_options.skipping = skipping
     end
 
-    def assert_no_accessibility_violations(auditor: @accessibility_audit_auditor, **options)
+    def assert_no_accessibility_violations(auditor: accessibility_audit_options.auditor, **options)
+      options = options.with_defaults(accessibility_audit_options.except(:auditor))
       options.assert_valid_keys(
         :according_to,
         :checking,

lib/capybara_accessibility_audit/engine.rb

@@ -24,7 +24,7 @@ class Engine < ::Rails::Engine
           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))
+          accessibility_audit_options.auditor = auditor_class.new(page, reporter_class.new(self))
         end
       end
     end
@@ -45,7 +45,7 @@ class Engine < ::Rails::Engine
             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))
+            accessibility_audit_options.auditor = auditor_class.new(page, reporter_class.new(self))
           end
 
           config.before(type: :system, &configure)

test/application_system_test_case.rb

@@ -3,7 +3,7 @@
 Capybara.javascript_driver = ENV.fetch("DRIVER", "selenium_chrome_headless").to_sym
 
 class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
-  driven_by Capybara.javascript_driver, screen_size: [1400, 1400], options: {js_errors: true}
+  driven_by Capybara.javascript_driver, screen_size: [1400, 1400], options: {js_errors: true, timeout: 10}
 
   def assert_rule_violation(rule = nil, with: rule, without: nil, &block)
     exception = assert_raises(Minitest::Assertion, &block)

test/support/active_support/testing/notification_assertions.rb

@@ -0,0 +1,40 @@
+module ActiveSupport::Testing
+  unless defined?(NotificationAssertions)
+    module NotificationAssertions
+      def assert_notification(pattern, payload = nil, &block)
+        notifications = capture_notifications(pattern, &block)
+        assert_not_empty(notifications, "No #{pattern} notifications were found")
+
+        return notifications.first if payload.nil?
+
+        notification = notifications.find { |notification| notification.payload.slice(*payload.keys) == payload }
+        assert_not_nil(notification, "No #{pattern} notification with payload #{payload} was found")
+
+        notification
+      end
+
+      def assert_notifications_count(pattern, count, &block)
+        actual_count = capture_notifications(pattern, &block).count
+        assert_equal(count, actual_count, "Expected #{count} instead of #{actual_count} notifications for #{pattern}")
+      end
+
+      def assert_no_notifications(pattern = nil, &block)
+        notifications = capture_notifications(pattern, &block)
+        error_message = if pattern
+          "Expected no notifications for #{pattern} but found #{notifications.size}"
+        else
+          "Expected no notifications but found #{notifications.size}"
+        end
+        assert_empty(notifications, error_message)
+      end
+
+      def capture_notifications(pattern = nil, &block)
+        notifications = []
+        ActiveSupport::Notifications.subscribed(->(n) { notifications << n }, pattern, &block)
+        notifications
+      end
+    end
+
+    ActiveSupport.on_load(:active_support_test_case) { include NotificationAssertions }
+  end
+end

test/system/audit_assertions_test.rb

@@ -80,6 +80,26 @@ class AuditAssertionsTest < ApplicationSystemTestCase
     accept_prompt("Hello?") { click_button "Open prompt" }
     dismiss_prompt("Hello?") { click_button "Open prompt" }
   end
+
+  test "publishes audit.capybara_accessibility_audit notifications" do
+    visit_audit, click_on_audit = capture_notifications "audit.capybara_accessibility_audit" do
+      visit violations_path
+
+      assert_rule_violation "label: Form elements must have labels" do
+        click_on "Violate rule: label"
+      end
+    end
+
+    assert_kind_of CapybaraAccessibilityAudit::AxeAuditor, visit_audit.payload.dig(:options, :auditor)
+    assert_equal self, click_on_audit.payload[:test]
+    assert_equal :visit, visit_audit.payload[:method]
+    assert_equal accessibility_audit_options, visit_audit.payload[:options]
+
+    assert_kind_of CapybaraAccessibilityAudit::AxeAuditor, click_on_audit.payload.dig(:options, :auditor)
+    assert_equal self, click_on_audit.payload[:test]
+    assert_equal :click_on, click_on_audit.payload[:method]
+    assert_equal accessibility_audit_options, click_on_audit.payload[:options]
+  end
 end
 
 class DisablingAuditAssertionsTest < ApplicationSystemTestCase

test/test_helper.rb

@@ -3,3 +3,5 @@
 
 require_relative "../test/dummy/config/environment"
 require "rails/test_help"
+
+Rails.root.glob("../../test/support/**/*.rb").each { |file| require file }