(HACK WEEK 2025) a11y desktop test helper (#2938)

* chore: 🤖 run ember-a11y-testing conditionally in desktop

* chore: 🤖 control launched testem chrome theme via COLOR_THEME

* chore: 🤖 add package.json scripts for desktop a11y tests

* chore: 🤖 gitignore a11y report

* chore: 🤖 update desktop package.json test command

Explicitly call test and finalize separately, previously "concurrently"
would pick up the finalize task

* chore: 🤖 remove unneeded console.logs

ui/desktop/.gitignore

@@ -21,3 +21,6 @@
 
 # broccoli-debug
 /DEBUG/
+
+# a11y audit
+/ember-a11y-report/

ui/desktop/config/environment.js

@@ -7,6 +7,7 @@
 
 const APP_NAME = process.env.APP_NAME || 'Boundary';
 const locationType = process.env.EMBER_CLI_ELECTRON ? 'hash' : 'history';
+const ENABLE_A11Y_AUDIT = process.env.ENABLE_A11Y_AUDIT || false;
 
 module.exports = function (environment) {
   const ENV = {
@@ -80,6 +81,8 @@ module.exports = function (environment) {
     ENV['ember-cli-mirage'].enabled = process.env.ENABLE_MIRAGE
       ? JSON.parse(process.env.ENABLE_MIRAGE)
       : true;
+
+    ENV.ENABLE_A11Y_AUDIT = ENABLE_A11Y_AUDIT;
   }
 
   if (environment === 'test') {
@@ -107,7 +110,7 @@ module.exports = function (environment) {
       memory: true,
     };
 
-    // Enable tests for development features
+    ENV.ENABLE_A11Y_AUDIT = ENABLE_A11Y_AUDIT;
   }
 
   if (environment === 'production') {

ui/desktop/package.json

@@ -32,8 +32,10 @@
     "init:desktop": "pnpm --dir electron-app build:all",
     "start:desktop": "pnpm init:desktop && ember electron",
     "clean:coverage": "rm -rf coverage_* || true",
-    "test": "pnpm clean:coverage && concurrently \"npm:test:*\" --names \"test:\" && pnpm test:finalize",
+    "test": "pnpm clean:coverage && pnpm test:ember && pnpm test:finalize",
     "test:ember": "cross-env COVERAGE=true ember exam --test-port 0 --split=4 --parallel=1 --random",
+    "test-a11y": "ENABLE_A11Y_AUDIT=true ember test",
+    "test-a11y:dark": "COLOR_THEME=dark pnpm test-a11y",
     "postinstall": "pnpm --dir electron-app install",
     "test:finalize": "ember coverage-merge && pnpm clean:coverage"
   },

ui/desktop/testem.js

@@ -5,6 +5,14 @@
 
 'use strict';
 
+const COLOR_THEME = process.env.COLOR_THEME ?? 'light';
+
+if (!['dark', 'light'].includes(COLOR_THEME)) {
+  throw new Error(
+    `Only values of "dark" and "light" are allowed for environment variable COLOR_THEME`,
+  );
+}
+
 module.exports = {
   test_page: 'tests/index.html?hidepassed',
   disable_watching: true,
@@ -14,8 +22,10 @@ module.exports = {
   browser_args: {
     Chrome: {
       all: [
-        process.env.DARK_MODE ? '--enable-features=WebContentsForceDark' : null,
+        COLOR_THEME === 'dark'
-        process.env.DARK_MODE ? '--force-dark-mode' : null,
+          ? '--enable-features=WebContentsForceDark'
+          : null,
+        COLOR_THEME === 'dark' ? '--force-dark-mode' : '--force-light-mode',
       ].filter(Boolean),
       ci: [
         // --no-sandbox is needed when running Chrome inside a container

ui/desktop/tests/test-helper.js

@@ -9,9 +9,63 @@ import * as QUnit from 'qunit';
 import { setApplication } from '@ember/test-helpers';
 import { setup } from 'qunit-dom';
 import start from 'ember-exam/test-support/start';
+import {
+  DEFAULT_A11Y_TEST_HELPER_NAMES,
+  setRunOptions,
+  setupGlobalA11yHooks,
+  setupQUnitA11yAuditToggle,
+  shouldForceAudit,
+  setEnableA11yAudit,
+  useMiddlewareReporter,
+  setupMiddlewareReporter,
+} from 'ember-a11y-testing/test-support';
 
 setApplication(Application.create(config.APP));
 
+setupGlobalA11yHooks(() => true, {
+  helpers: [
+    ...DEFAULT_A11Y_TEST_HELPER_NAMES,
+    'fillIn',
+    'render',
+    'tab',
+    'focus',
+    'select',
+  ],
+});
+
+setupQUnitA11yAuditToggle(QUnit);
+
+setRunOptions({
+  runOnly: {
+    type: 'tag',
+    values: [
+      'wcag2a',
+      'wcag2aa',
+      'wcag21a',
+      'wcag21aa',
+      'wcag22aa',
+      'best-practice',
+    ],
+  },
+  include: [['#ember-testing-container']],
+  exclude: [['.flight-sprite-container']],
+});
+
+// This will be used by developers to run the tests locally
+// Either with the `enableA11yAudit` as a query param in the URL
+// or `pnpm test-a11y` in the CLI
+// Note: if you want to filter what test is run from the start, use the --filter flag: `pnpm test-a11y --filter="alert"`
+// Docs: https://guides.emberjs.com/release/testing/#toc_how-to-filter-tests
+if (shouldForceAudit()) {
+  setEnableA11yAudit(true);
+}
+
+// Note, as a convenience, useMiddlewareReporter automatically forces audits, thus explicitly specifying the enableA11yAudit query param or the ENABLE_A11Y_AUDIT environment variable is unnecessary.
+if (useMiddlewareReporter()) {
+  // Only runs if `enableA11yMiddlewareReporter` is set in URL
+  setupMiddlewareReporter();
+}
+
 setup(QUnit.assert);
 
 start();