From f202d0f533e907ef52d54197e6fee51b798876f3 Mon Sep 17 00:00:00 2001 From: Cameron Perera Date: Mon, 28 Jul 2025 15:35:03 -0500 Subject: [PATCH] =?UTF-8?q?(HACK=20WEEK=202025)=20docs:=20=E2=9C=8F?= =?UTF-8?q?=EF=B8=8F=20add=20a11y=20testing=20info=20to=20READMEs=20(#2945?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 | 5 +++ ui/admin/README.md | 40 +++++++++++++++++++ .../tests/acceptance/authentication-test.js | 1 + ui/admin/tests/helpers/index.js | 6 +-- ui/desktop/README.md | 40 +++++++++++++++++++ 5 files changed, 87 insertions(+), 5 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 76dd1dd8c..53463d0a4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -12,12 +12,17 @@ ## Checklist + + - [ ] 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 diff --git a/ui/admin/README.md b/ui/admin/README.md index 827a3bd48..cbc708ee0 100644 --- a/ui/admin/README.md +++ b/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 diff --git a/ui/admin/tests/acceptance/authentication-test.js b/ui/admin/tests/acceptance/authentication-test.js index 856e52393..d4dff1270 100644 --- a/ui/admin/tests/acceptance/authentication-test.js +++ b/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 diff --git a/ui/admin/tests/helpers/index.js b/ui/admin/tests/helpers/index.js index 09279d80e..2d6c53909 100644 --- a/ui/admin/tests/helpers/index.js +++ b/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 diff --git a/ui/desktop/README.md b/ui/desktop/README.md index 89cb8c174..20f5862c5 100644 --- a/ui/desktop/README.md +++ b/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