test(ui-library): #565 automate a11y tests

package.json

@@ -11,7 +11,8 @@
     "build:ui-library": "yarn tokens:generate && yarn compile:icons && yarn workspace @boiler/ui-library build && yarn workspace @boiler/ui-library compile",
     "lint": "yarn workspace @boiler/ui-library lint",
     "format": "yarn workspace @boiler/ui-library format:eslint && yarn workspace @boiler/ui-library format:prettier",
-    "test": "yarn build:ui-library && yarn workspace @boiler/ui-library test",
+    "test:ui-library": "yarn build:ui-library && yarn workspace @boiler/ui-library test",
+    "test:ui-library:a11y": "yarn build:ui-library && yarn workspace @boiler/ui-library test:a11y",
     "doc:install": "deven-documentation-skeleton install",
     "doc:check": "deven-documentation-skeleton check",
     "doc:update": "deven-documentation-skeleton update",

packages/ui-library/package.json

@@ -24,13 +24,15 @@
     "format:eslint": "eslint 'src/**' --ext .ts,.tsx --fix",
     "lint:prettier": "prettier \"**/*.{ts,tsx,cjs,mjs,js}\" --check",
     "format:prettier": "prettier \"**/*.{ts,tsx,cjs,mjs,js}\" --write",
-    "test": "wtr --config web-test-runner.config.mjs"
+    "test": "wtr --config web-test-runner.config.mjs",
+    "test:a11y": "wtr --config web-test-runner-a11y.config.mjs"
   },
   "author": "",
   "license": "MIT",
   "devDependencies": {
     "@boiler/eslint-config-boiler": "1.0.0",
     "@boiler/figma-design-tokens": "0.0.1",
+    "@faker-js/faker": "^8.4.1",
     "@storybook/addon-designs": "^7.0.7"
   },
   "dependencies": {

packages/ui-library/src/components/counter/index.test.a11y.ts

@@ -0,0 +1,22 @@
+import '@boiler/ui-library';
+
+import { BlrCounterRenderFunction } from './renderFunction';
+import type { BlrCounterType } from '.';
+
+import { combineProperties } from '../../utils/test/combine-properties';
+import { runA11yCombinationTests } from '../../utils/test/run-combination-test';
+
+const propertyCombinations = combineProperties<BlrCounterType>({
+  maxValue: [0, 100],
+  sizeVariant: ['sm', 'md', 'lg', undefined],
+  theme: ['Dark', 'Light'],
+  value: [0, 50, 100],
+  variant: ['error', 'neutral', 'warn'],
+});
+
+describe('blr-counter', () => {
+  runA11yCombinationTests({
+    combinationsList: propertyCombinations,
+    componentRenderer: BlrCounterRenderFunction,
+  });
+});

packages/ui-library/src/utils/test/combine-properties.ts

@@ -0,0 +1,57 @@
+/**
+ * Generates a flat list of possible property combinations for the provided record of input values.
+ *
+ * **Does not act deeply.**
+ *
+ * @example
+ * ```typescript
+ * combineProperties({
+ *  color: [undefined, 'red'],
+ *  sizeVariant: ['md', 'lg'],
+ * })
+ * ```
+ *
+ * yields:
+ *
+ * ```typescript
+ * [{
+ *   color: undefined,
+ *   sizeVariant: 'md',
+ * }, {
+ *   color: 'red',
+ *   sizeVariant: 'md',
+ * }, {
+ *   color: undefined,
+ *   sizeVariant: 'lg',
+ * }, {
+ *   color: 'red',
+ *   sizeVariant: 'lg',
+ * }]
+ * ```
+ *
+ * @param valuesRecord The record of possible values a property can take.
+ * @returns A flat list of possible property combinations in shape of the {@linkcode valuesRecord}.
+ *
+ * - Search terms: combinations, permutations, combine
+ */
+export function combineProperties<TObject extends Record<string | number | symbol, unknown>>(
+  valuesRecord: ValuesRecord<TObject>
+): TObject[] {
+  let combos: TObject[] = [];
+  for (const key in valuesRecord) {
+    const values = valuesRecord[key];
+    const all = [];
+    for (let i = 0; i < values.length; i++) {
+      for (let j = 0; j < (combos.length || 1); j++) {
+        const newCombo = { ...combos[j], [key]: values[i] };
+        all.push(newCombo);
+      }
+    }
+    combos = all;
+  }
+  return combos;
+}
+
+export type ValuesRecord<TObject extends Record<string | number | symbol, unknown>> = {
+  [PropertyName in keyof TObject]-?: TObject[PropertyName][];
+};

packages/ui-library/src/utils/test/run-combination-test.ts

@@ -0,0 +1,37 @@
+import { fixture, expect } from '@open-wc/testing';
+import type { TaggedComponentRenderFunction } from '../typesafe-generic-component-renderer.js';
+
+export type RunCombinationTestsOptions<T> = {
+  combinationList: T[];
+  subject: string;
+  test: (parameters: T) => Mocha.Func | Mocha.AsyncFunc;
+};
+
+export function runCombinationTests<TObject extends Record<string | number | symbol, unknown>>(
+  options: RunCombinationTestsOptions<TObject>
+): void {
+  options.combinationList.forEach((parameters) => {
+    it(
+      `passes ${options.subject} test for property combination:\n\n${JSON.stringify(parameters, undefined, 2)}\n`,
+      options.test(parameters)
+    );
+  });
+}
+
+export type RunA11yCombinationTestsOptions<T extends Record<string | number | symbol, unknown>> = {
+  combinationsList: T[];
+  componentRenderer: TaggedComponentRenderFunction<T>;
+};
+
+export function runA11yCombinationTests<TObject extends Record<string | number | symbol, unknown>>(
+  options: RunA11yCombinationTestsOptions<TObject>
+): void {
+  runCombinationTests({
+    combinationList: options.combinationsList,
+    subject: 'a11y',
+    test: (parameters) => async () => {
+      const el = await fixture(options.componentRenderer(parameters));
+      await expect(el).to.be.accessible();
+    },
+  });
+}

packages/ui-library/src/utils/typesafe-generic-component-renderer.ts

@@ -1,6 +1,12 @@
 import { TemplateResult, html, nothing } from 'lit';
 import { camelCaseToKebabCase } from './lit/decorators.js';
 
+export type TaggedComponentRenderFunction<TComponentType extends Record<string | number | symbol, unknown>> = (
+  props: Parameters<typeof genericBlrComponentRenderer<TComponentType>>[1],
+  children?: Parameters<typeof genericBlrComponentRenderer<TComponentType>>[2],
+  htmlAttributes?: Parameters<typeof genericBlrComponentRenderer<TComponentType>>[3]
+) => ReturnType<typeof genericBlrComponentRenderer<TComponentType>>;
+
 export const genericBlrComponentRenderer = <ComponentType extends { [s: string]: unknown } | ArrayLike<unknown>>(
   tagName: string,
   props: ComponentType,

packages/ui-library/tsconfig.json

@@ -27,5 +27,5 @@
     ]
   },
   "include": ["src"],
-  "exclude": ["src/**/*.test.ts", "src/**/*.stories.ts"]
+  "exclude": ["src/**/*.test.*", "src/**/*.stories.ts"]
 }

packages/ui-library/web-test-runner-a11y.config.mjs

@@ -0,0 +1,10 @@
+import { esbuildPlugin } from '@web/dev-server-esbuild';
+
+/**
+ * @type {import('@web/dev-server').DevServerConfig}
+ */
+export default {
+  nodeResolve: true,
+  files: ['src/components/**/*.test.a11y.ts'],
+  plugins: [esbuildPlugin({ ts: true })],
+};

packages/ui-library/web-test-runner.config.mjs

@@ -1,5 +1,8 @@
 import { esbuildPlugin } from '@web/dev-server-esbuild';
 
+/**
+ * @type {import('@web/dev-server').DevServerConfig}
+ */
 export default {
   nodeResolve: true,
   files: ['src/components/**/*.test.ts'],

yarn.lock

@@ -1656,6 +1656,7 @@ __metadata:
     "@boiler/eslint-config-boiler": "npm:1.0.0"
     "@boiler/figma-design-tokens": "npm:0.0.1"
     "@boiler/icons": "npm:0.0.1"
+    "@faker-js/faker": "npm:^8.4.1"
     "@floating-ui/dom": "npm:^1.6.3"
     "@lit-labs/react": "npm:^1.1.1"
     "@storybook/addon-designs": "npm:^7.0.7"
@@ -2320,6 +2321,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@faker-js/faker@npm:^8.4.1":
+  version: 8.4.1
+  resolution: "@faker-js/faker@npm:8.4.1"
+  checksum: 10c0/4f2aecddcfdc2cc8b50b2d15d1e37302a7c7a5bbd184ae910a9d271bc11248533ca74dcdd4a9ccbe20410553e7af0f6a4d334c5b955635e09a32ddf4a64942d4
+  languageName: node
+  linkType: hard
+
 "@fal-works/esbuild-plugin-global-externals@npm:^2.1.2":
   version: 2.1.2
   resolution: "@fal-works/esbuild-plugin-global-externals@npm:2.1.2"