Implement minimal accessibility snapshots

.changeset/thick-singers-roll.md

@@ -0,0 +1,5 @@
+---
+'pleasantest': minor
+---
+
+Add experimental accessibility snapshots feature

babel.config.cjs

@@ -10,7 +10,7 @@ module.exports = (api) => {
           loose: true,
         },
       ],
-      '@babel/preset-typescript',
+      ['@babel/preset-typescript', { optimizeConstEnums: true }],
     ],
     plugins: isRollup ? ['babel-plugin-un-cjs'] : [],
   };

examples/menu/index.test.ts

@@ -1,5 +1,10 @@
 import type { PleasantestUtils } from 'pleasantest';
-import { withBrowser, devices } from 'pleasantest';
+import {
+  experimentalGetAccessibilityTree,
+  withBrowser,
+  devices,
+} from 'pleasantest';
+
 import { Liquid } from 'liquidjs';
 import * as path from 'path';
 const iPhone = devices['iPhone 11'];
@@ -75,23 +80,46 @@ test(
     await expect(await screen.getByText(aboutText)).not.toBeVisible();
 
     // Before JS initializes the menus should be links
-    let aboutBtn = await screen.getByRole('link', { name: /about/i });
-    await expect(aboutBtn).toHaveAttribute('href');
-    await expect(
-      await screen.queryByRole('button', { name: /about/i }),
-    ).not.toBeInTheDocument();
+    expect(
+      await experimentalGetAccessibilityTree(
+        await screen.getByRole('navigation'),
+      ),
+    ).toMatchInlineSnapshot(`
+        navigation
+          heading "Company"
+            link "Company"
+          list
+            listitem
+              link "Products"
+            listitem
+              link "About"
+            listitem
+              link "Log In"
+      `);
 
     await utils.runJS(`
       import { init } from '.'
       init()
     `);
 
-    // The menus should be upgraded to buttons
-    aboutBtn = await screen.getByRole('button', { name: /about/i });
-    await expect(
-      await screen.queryByRole('link', { name: /about/i }),
-    ).not.toBeInTheDocument();
-
+    // The menus should be upgraded to buttons,
+    const aboutBtn = await screen.getByRole('button', { name: /about/i });
+    expect(
+      await experimentalGetAccessibilityTree(
+        await screen.getByRole('navigation'),
+      ),
+    ).toMatchInlineSnapshot(`
+        navigation
+          heading "Company"
+            link "Company"
+          list
+            listitem
+              button "Products"
+            listitem
+              button "About"
+            listitem
+              link "Log In"
+      `);
     // Login should still be a link, since it does not trigger a menu to open
     const loginBtn = await screen.getByRole('link', { name: /log in/i });
     await expect(loginBtn).toHaveAttribute('href');
@@ -110,6 +138,7 @@ test(
     const productsBtn = await screen.getByRole('button', { name: /products/i });
     // First click: opens about menu
     await user.click(aboutBtn);
+
     await expect(await screen.getByText(aboutText)).toBeVisible();
     // Second click: closes about menu
     await user.click(aboutBtn);

package.json

@@ -29,6 +29,7 @@
     "ansi-regex": "6.0.0",
     "aria-query": "*",
     "babel-plugin-un-cjs": "2.5.0",
+    "dom-accessibility-api": "0.5.7",
     "errorstacks": "2.3.2",
     "esbuild-jest": "0.5.0",
     "eslint": "7.32.0",
@@ -53,7 +54,7 @@
     "sass": "1.38.2",
     "simple-code-frame": "1.1.1",
     "smoldash": "0.11.0",
-    "typescript": "4.3.5",
+    "typescript": "4.4.2",
     "vue": "3.2.6"
   },
   "dependencies": {

rollup.config.js

@@ -1,6 +1,7 @@
 import jestDomConfig from './src/jest-dom/rollup.config';
 import pptrTestingLibraryConfig from './src/pptr-testing-library-client/rollup.config';
 import userUtilsConfig from './src/user-util/rollup.config';
+import accessibilityConfig from './src/accessibility/rollup.config';
 
 import dts from 'rollup-plugin-dts';
 import babel from '@rollup/plugin-babel';
@@ -61,6 +62,7 @@ const typesConfig = {
 export default [
   mainConfig,
   userUtilsConfig,
+  accessibilityConfig,
   jestDomConfig,
   pptrTestingLibraryConfig,
   typesConfig,

src/accessibility/browser.ts

@@ -0,0 +1,77 @@
+import {
+  getRole,
+  computeAccessibleName,
+  computeAccessibleDescription,
+} from 'dom-accessibility-api';
+import type { AccessibilityTreeOptions } from '.';
+
+const indent = (text: string, indenter = '  ') =>
+  indenter + text.split('\n').join(`\n${indenter}`);
+
+const enum AccessibilityState {
+  /** This element is accessible and its descendents could be accessible */
+  Accessible,
+  /** This element is innaccessible, but its descendents could be accessible */
+  InaccessibleSelf,
+  /** Both this element and its descendents are inaccessible */
+  InaccessibleSelfAndDescendents,
+}
+
+// TODO in PR: what about role="presentation" or role="none"? Should they be excluded?
+// The spec says "it depends on the implementation" basically I think
+const getAccessibilityState = (element: Element): AccessibilityState => {
+  const computedStyle = getComputedStyle(element);
+  if (
+    (element as HTMLElement).hidden ||
+    element.getAttribute('aria-hidden') === 'true' ||
+    computedStyle.display === 'none'
+  )
+    return AccessibilityState.InaccessibleSelfAndDescendents;
+
+  // An element can have visibility: 'hidden' but its descendents can override visibility
+  if (computedStyle.visibility === 'hidden')
+    return AccessibilityState.InaccessibleSelf;
+
+  return AccessibilityState.Accessible;
+};
+
+export const getAccessibilityTree = (
+  element: Element,
+  opts: AccessibilityTreeOptions,
+): string => {
+  const accessibilityState = getAccessibilityState(element);
+  if (accessibilityState === AccessibilityState.InaccessibleSelfAndDescendents)
+    return '';
+  const { includeDescriptions = true, includeText = false } = opts;
+  const role = getRole(element);
+  const printSelf =
+    role && accessibilityState === AccessibilityState.Accessible;
+  let text = (printSelf && role) || '';
+  if (printSelf) {
+    const name = computeAccessibleName(element);
+    if (name) text += ` "${name}"`;
+    if (includeDescriptions) {
+      const description = computeAccessibleDescription(element);
+      if (description) text += `\n  ↳ description: "${description}"`;
+    }
+  }
+  const printedChildren = [];
+  for (const node of element.childNodes) {
+    let printedChild;
+    if (node instanceof Element) {
+      printedChild = getAccessibilityTree(node, opts);
+    } else if (includeText) {
+      const trimmedText = node.nodeValue?.trim();
+      if (!trimmedText) continue;
+      printedChild = `text "${trimmedText}"`;
+    }
+    if (printedChild) printedChildren.push(printedChild);
+  }
+  if (printedChildren.length > 0) {
+    if (text.length > 0) text += '\n';
+    text += printSelf
+      ? indent(printedChildren.join('\n'))
+      : printedChildren.join('\n');
+  }
+  return text;
+};

src/accessibility/index.ts

@@ -0,0 +1,57 @@
+import type { ElementHandle } from 'puppeteer';
+import { createClientRuntimeServer } from '../module-server/client-runtime-server';
+import { assertElementHandle } from '../utils';
+
+const accessibilityTreeSymbol: unique symbol = Symbol('PT Accessibility Tree');
+
+export interface AccessibilityTreeOptions {
+  /**
+   * Whether the accessibile description of elements should be included in the tree.
+   * https://www.w3.org/TR/wai-aria-1.2/#dfn-accessible-description
+   * (default: true)
+   */
+  includeDescriptions?: boolean;
+  /**
+   * Whether to include text that is not part of an element's accessible name/description
+   * (default: false)
+   */
+  includeText?: boolean;
+}
+
+export const getAccessibilityTree = async (
+  element: ElementHandle,
+  options: AccessibilityTreeOptions = {},
+) => {
+  const serverPromise = createClientRuntimeServer();
+  assertElementHandle(element, getAccessibilityTree);
+
+  const { port } = await serverPromise;
+
+  const result: string = await element.evaluate(
+    // Using new Function to avoid babel transpiling the import
+    // @ts-expect-error pptr's types don't like new Function
+    new Function(
+      'element',
+      'options',
+      `return import("http://localhost:${port}/@pleasantest/accessibility")
+        .then(accessibility => accessibility.getAccessibilityTree(element, options))`,
+    ),
+    options,
+  );
+
+  return {
+    [accessibilityTreeSymbol]: result,
+    toString: () => result,
+  };
+};
+
+expect.addSnapshotSerializer({
+  serialize: (val, config, indentation, depth, refs, printer) => {
+    const v = val[accessibilityTreeSymbol];
+    return typeof v === 'string'
+      ? v
+      : printer(v, config, indentation, depth, refs);
+  },
+  test: (val) =>
+    val && typeof val === 'object' && accessibilityTreeSymbol in val,
+});

src/accessibility/rollup.config.js

@@ -0,0 +1,20 @@
+import babel from '@rollup/plugin-babel';
+import nodeResolve from '@rollup/plugin-node-resolve';
+import { terser } from 'rollup-plugin-terser';
+import { rollupPluginDomAccessibilityApi } from '../rollup-plugin-dom-accessibility-api';
+
+const extensions = ['.js', '.jsx', '.es6', '.es', '.mjs', '.ts', '.tsx'];
+
+/** @type {import('rollup').RollupOptions} */
+const config = {
+  input: ['src/accessibility/browser.ts'],
+  plugins: [
+    babel({ babelHelpers: 'bundled', extensions }),
+    nodeResolve({ extensions }),
+    rollupPluginDomAccessibilityApi(),
+    terser({ ecma: 2019 }),
+  ],
+  output: { file: 'dist/accessibility.js' },
+};
+
+export default config;

src/index.ts

@@ -450,3 +450,5 @@ export const devices = puppeteer.devices;
 afterAll(async () => {
   await cleanupClientRuntimeServer();
 });
+
+export { getAccessibilityTree as experimentalGetAccessibilityTree } from './accessibility';

src/jest-dom/rollup.config.js

@@ -1,6 +1,7 @@
 import babel from '@rollup/plugin-babel';
 import nodeResolve from '@rollup/plugin-node-resolve';
 import { terser } from 'rollup-plugin-terser';
+import { rollupPluginDomAccessibilityApi } from '../rollup-plugin-dom-accessibility-api';
 
 const extensions = ['.js', '.jsx', '.es6', '.es', '.mjs', '.ts', '.tsx'];
 
@@ -73,6 +74,7 @@ const config = {
     babel({ babelHelpers: 'bundled', extensions }),
     nodeResolve({ extensions }),
     removeCloneNodePlugin,
+    rollupPluginDomAccessibilityApi(),
     terser({
       ecma: 2019,
       // Jest-dom uses function names for error messages

src/module-server/client-runtime-server.ts

@@ -31,6 +31,8 @@ const clientRuntimeMiddleware =
         ? 'jest-dom.js'
         : req.path === '/@pleasantest/user-util'
         ? 'user-util.js'
+        : req.path === '/@pleasantest/accessibility'
+        ? 'accessibility.js'
         : 'pptr-testing-library-client.js',
     );
     const text = await fs.readFile(filePath, 'utf8');