Skip to content

Connect, collaborate, and grow with a community of TypeScript developers

1369 mdwiltfong a11y reporting (#1379)

Michael Wiltfongebb991af5371
diff --git a/LOCAL.md b/LOCAL.md
index df5502ed..6cb06b20 100644
--- a/LOCAL.md
+++ b/LOCAL.md
@@ -184,6 +184,12 @@ In the event you need to troubleshoot the end-to-end tests, you can run Playwrig
In addition you can use [Playwright Inspector](https://playwright.dev/docs/debug#playwright-inspector) to debug tests, which is a debugger that Playwright maintains. It automatically stops at each test suite, as well as each test case within them. As a result, you can debug a specific test suite by running `pnpm test:e2e:inspector -- {testName}`
+### Troubleshooting A11y
+
+In the event the end-to-end tests find an A11y violation, the playwright report will contain more information. Such as the description of the violation, a link to Deque University that will explain the violation as well as some ways to fix it, and finally the HTML that is causing the violation.
+
+You can access the playwright report by first running `pnpm test:e2e`. After it has completed, you can run `pnpm exec playwright show-report` to see the HTML report, or simply open the `index.html` file under `apps/web/playwright-report`.
+
## FAQ
<details>
diff --git a/apps/web/playwright/utils/a11yLogger.ts b/apps/web/playwright/utils/a11yLogger.ts
new file mode 100644
index 00000000..bde2b7c3
--- /dev/null
+++ b/apps/web/playwright/utils/a11yLogger.ts
@@ -0,0 +1,25 @@
+import type axe from '@axe-core/playwright/node_modules/axe-core/axe';
+
+export default class A11yError extends Error {
+ violations: typeof axe.AxeResults.violations = [];
+ constructor(violations: typeof axe.AxeResults.violations) {
+ super();
+ this.violations = violations;
+ this.message = `
+ ==================================================
+ Axe Violations:
+ ==================================================
+ ${violations.map((violation) => {
+ return `
+ Description: ${violation.description}
+ Impact: ${violation.impact}
+ Help: ${violation.help}
+ Help URL: ${violation.helpUrl}
+ Failure Summary: ${violation.nodes[0]?.failureSummary}
+ HTML: ${violation.nodes[0]?.html}
+ ==================================================
+ `;
+ })}
+ `;
+ }
+}
diff --git a/apps/web/tests/e2e/unauthenticated/home.test.ts b/apps/web/tests/e2e/unauthenticated/home.test.ts
index 6b4e2b24..2c088618 100644
--- a/apps/web/tests/e2e/unauthenticated/home.test.ts
+++ b/apps/web/tests/e2e/unauthenticated/home.test.ts
@@ -1,6 +1,7 @@
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
import { A11YTAGS } from '../constant';
+import A11yError from 'playwright/utils/a11yLogger';
test.use({ storageState: 'playwright/.auth/unauthenticated.json' });
@@ -20,7 +21,9 @@ test.describe('homepage a11y', () => {
// TODO: fix this type error
// @ts-expect-error
const a11yScanResults = await new AxeBuilder({ page }).withTags(A11YTAGS).analyze();
-
+ if (a11yScanResults.violations.length > 0) {
+ throw new A11yError(a11yScanResults.violations);
+ }
expect(a11yScanResults.violations).toEqual([]);
});
@@ -37,6 +40,9 @@ test.describe('homepage a11y', () => {
// @ts-expect-error
const a11yScanResults = await new AxeBuilder({ page }).withTags(A11YTAGS).analyze();
+ if (a11yScanResults.violations.length > 0) {
+ throw new A11yError(a11yScanResults.violations);
+ }
expect(a11yScanResults.violations).toEqual([]);
});
});