(HACK WEEK 2025) docs: ✏️ add a11y testing info to READMEs (#2945)

* docs: ✏️ add a11y testing info to READMEs

* chore: 🤖 remove light theme setup for acceptance tests in admin

* docs: ✏️ add link to test-helper.js in README

* chore: 🤖 update PR template for a11y-tests

* test: 💍 fix color theme switching tests

.github/pull_request_template.md

@@ -12,12 +12,17 @@
 ## Checklist
 <!-- strikethrough the checklist item that is not relevant to your change -->
 
+<!-- If you are merging a long lived branch, major feature, or UI altering changes,
+please add the a11y-tests label. Other cases, like a dependency change or
+translation update likely does not need an a11y audit -->
+
 - [ ] I have added before and after screenshots for UI changes
 - [ ] I have added JSON response output for API changes
 - [ ] I have added steps to reproduce and test for bug fixes in the description
 - [ ] I have commented on my code, particularly in hard-to-understand areas
 - [ ] My changes generate no new warnings
 - [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] I have added `a11y-tests` label to run a11y audit tests if needed
 
 ## PCI review checklist
 

ui/admin/README.md

@@ -14,6 +14,8 @@ The Admin UI for Boundary.
     - [Building for Production](#building-for-production)
       - [Environment Variables](#environment-variables)
     - [Running Tests](#running-tests)
+      - [Light vs Dark Mode A11y Tests](#light-vs-dark-mode-a11y-tests)
+      - [Explicit a11yAudit usage](#explicit-a11yaudit-usage)
     - [Deploying](#deploying)
   - [Further Reading / Useful Links](#further-reading--useful-links)
 
@@ -96,6 +98,44 @@ of testing".  Use test coverage as a guide to help you identify untested
 high-value code.
 
 We rely on `ember-a11y-testing` to validate accessibility in acceptance tests.
+Write acceptance tests like normal. Our a11y testing strategy will automatically
+run `a11yAudit()` after [specific helper actions](tests/test-helper.js#L26), like visit, click, and fillIn.
+Our a11y tests have their own pnpm commands:
+
+* `pnpm test-ally` runs a11y tests for light and dark mode
+* `pnpm test-ally:light` runs a11y tests just for light mode
+* `pnpm test-ally:dark` runs a11y tests just for dark mode
+
+#### Light vs Dark Mode A11y Tests
+
+When running a11y tests in light mode, we audit against multiple WCAG standards.
+However, dark mode will only tests against the `color-contrast` rule. Unless fixing
+a specific test, please use `pnpm test-a11y` for full a11y testing coverage.
+
+#### Explicit a11yAudit usage
+
+We no longer need to call `a11yAudit()` directly but there any be times we need to.
+An example would be when an action is taken in our tests that alters the UI but
+does not trigger an audit via our default helpers. In the below example, we use
+a dispatch to insert text into a code editor. This will not trigger an audit and
+inserting an `a11yAudit()` right after would be acceptable. Wrap the audit with
+`shouldForceAudit` so the audit is only run when testing a11y.
+
+```javascript
+import { shouldForceAudit } from 'ember-a11y-testing/test-support';
+
+const editorElement = find(commonSelectors.CODE_EDITOR_CODE);
+const editorView = editorElement.editor;
+editorView.dispatch({
+  changes: {
+    from: editorView.state.selection.main.from,
+    insert: '{"test": "value"}',
+  },
+});
+if (shouldForceAudit()) {
+  await a11yAudit();
+}
+```
 
 ### Deploying
 

ui/admin/tests/acceptance/authentication-test.js

@@ -361,6 +361,7 @@ module('Acceptance | authentication', function (hooks) {
     await authenticateSession({
       scope: { id: globalScope.id, type: globalScope.type },
     });
+    currentSession().set('data.theme', 'light');
     await visit(orgsURL);
 
     // light mode

ui/admin/tests/helpers/index.js

@@ -8,10 +8,7 @@ import {
   setupRenderingTest as upstreamSetupRenderingTest,
   setupTest as upstreamSetupTest,
 } from 'ember-qunit';
-import {
-  currentSession,
-  authenticateSession,
-} from 'ember-simple-auth/test-support';
+import { authenticateSession } from 'ember-simple-auth/test-support';
 
 // This file exists to provide wrappers around ember-qunit's
 // test setup functions. This way, you can easily extend the setup that is
@@ -27,7 +24,6 @@ function setupApplicationTest(hooks, options) {
   //
   hooks.beforeEach(async function () {
     await authenticateSession();
-    currentSession().set('data.theme', 'light');
   });
   //
   // This is also a good place to call test setup functions coming

ui/desktop/README.md

@@ -16,6 +16,8 @@ The desktop client UI for Boundary.
     - [Building for Production](#building-for-production)
       - [Environment Variables (PROD)](#environment-variables-prod)
     - [Running Tests](#running-tests)
+      - [Light vs Dark Mode A11y Tests](#light-vs-dark-mode-a11y-tests)
+      - [Explicit a11yAudit usage](#explicit-a11yaudit-usage)
     - [Running end to end Tests](#running-end-to-end-tests)
     - [Troubleshooting](#troubleshooting)
       - [Blank screen and/or hang browser tab when running as web app](#blank-screen-andor-hang-browser-tab-when-running-as-web-app)
@@ -148,6 +150,44 @@ of testing".  Use test coverage as a guide to help you identify untested
 high-value code.
 
 We rely on `ember-a11y-testing` to validate accessibility in acceptance tests.
+Write acceptance tests like normal. Our a11y testing strategy will automatically
+run `a11yAudit()` after [specific helper actions](tests/test-helper.js#L26), like visit, click, and fillIn.
+Our a11y tests have their own pnpm commands:
+
+* `pnpm test-ally` runs a11y tests for light and dark mode
+* `pnpm test-ally:light` runs a11y tests just for light mode
+* `pnpm test-ally:dark` runs a11y tests just for dark mode
+
+#### Light vs Dark Mode A11y Tests
+
+When running a11y tests in light mode, we audit against multiple WCAG standards.
+However, dark mode will only tests against the `color-contrast` rule. Unless fixing
+a specific test, please use `pnpm test-a11y` for full a11y testing coverage.
+
+#### Explicit a11yAudit usage
+
+We no longer need to call `a11yAudit()` directly but there any be times we need to.
+An example would be when an action is taken in our tests that alters the UI but
+does not trigger an audit via our default helpers. In the below example, we use
+a dispatch to insert text into a code editor. This will not trigger an audit and
+inserting an `a11yAudit()` right after would be acceptable. Wrap the audit with
+`shouldForceAudit` so the audit is only run when testing a11y.
+
+```javascript
+import { shouldForceAudit } from 'ember-a11y-testing/test-support';
+
+const editorElement = find(commonSelectors.CODE_EDITOR_CODE);
+const editorView = editorElement.editor;
+editorView.dispatch({
+  changes: {
+    from: editorView.state.selection.main.from,
+    insert: '{"test": "value"}',
+  },
+});
+if (shouldForceAudit()) {
+  await a11yAudit();
+}
+```
 
 ### Running end to end Tests