Separate AXE specs

README.md

@@ -58,13 +58,32 @@ The app tests are written with [rspec-rails] and you can run them with:
 bundle exec rspec
 ```
 
+This includes the [axe-core] accessibility checks within the feature specs by default (as does CI), though they are slow to run. To skip them locally, add a gitignored `config/settings/test.local.yml` with:
+
+```yaml
+skip_axe_tests: true
+```
+
+or override it per-run:
+
+```bash
+SETTINGS__SKIP_AXE_TESTS=true bundle exec rspec
+```
+
+`bundle exec rake test` (which also runs the frontend test suite) honours the same setting. To run just the feature specs with accessibility checks, without the rest of the suite, use:
+
+```bash
+bundle exec rake test:axe
+```
+
 There are also unit tests for JavaScript code (look for files named `*.test.js`), written with [Vitest]. You can run those with:
 
 ```bash
 npm run test
 ```
 
 [rspec-rails]: https://github.com/rspec/rspec-rails
+[axe-core]: https://github.com/dequelabs/axe-core-gems
 [Vitest]: https://vitest.dev/
 
 ### Running the RSpec tests in parallel

config/settings.yml

@@ -53,6 +53,11 @@ govuk_notify:
 # When set to true, any capybara tests will run chrome normally rather than in headless mode.
 show_browser_during_tests: false
 
+# Axe checks make feature specs significantly slower, so they can be skipped, e.g. for a
+# faster local test run. Set to true in config/settings/test.local.yml or via the
+# SETTINGS__SKIP_AXE_TESTS environment variable. Runs by default everywhere else, e.g. in CI.
+skip_axe_tests: false
+
 maintenance_mode:
   # When set to true, All pages will render 'Maintenance mode' message
   enabled: false

lib/tasks/test.rake

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
-desc "Run tests"
+desc "Run tests, including accessibility (axe) checks unless Settings.skip_axe_tests is set"
 task test: :environment do
   sh "bundle exec rspec"
   sh "npm run test"
 end
+
+namespace :test do
+  desc "Run only the accessibility (axe) checks within the feature specs"
+  task axe: :environment do
+    sh({ "SETTINGS__SKIP_AXE_TESTS" => "false" }, "bundle exec rspec spec/features")
+  end
+end

spec/support/axe_feature_helpers.rb

@@ -1,11 +1,23 @@
 module AxeFeatureHelpers
   def expect_page_to_have_no_axe_errors(page)
+    return if skip_axe_tests?
+
     expect(page).to be_axe_clean.according_to(:wcag2a, :wcag2aa, :wcag21a, :wcag21aa)
   end
 
   def expect_component_to_have_no_axe_errors(page)
+    return if skip_axe_tests?
+
     expect(page).to be_axe_clean.within("#main-content").according_to(:wcag2a, :wcag2aa, :wcag21a, :wcag21aa)
   end
+
+private
+
+  # Axe checks make feature specs significantly slower, so they can be skipped, e.g. for a
+  # faster local test run. See Settings.skip_axe_tests in config/settings.yml.
+  def skip_axe_tests?
+    Settings.skip_axe_tests
+  end
 end
 
 RSpec.configure do |config|