Jest custom matchers 🦨

tools/jest-matchers/README.md

@@ -0,0 +1,19 @@
+# Jest Matchers
+
+![npm (scoped)](https://img.shields.io/npm/v/@leafygreen-ui/jest-matchers.svg)
+
+#### [View on MongoDB.design](https://www.mongodb.design/component/jest-matchers/example/)
+
+## Installation
+
+### Yarn
+
+```shell
+yarn add @leafygreen-ui/jest-matchers
+```
+
+### NPM
+
+```shell
+npm install @leafygreen-ui/jest-matchers
+```

tools/jest-matchers/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@lg-tools/jest-matchers",
+  "version": "0.0.1",
+  "description": "LeafyGreen UI Kit Jest Matchers",
+  "main": "./dist/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "lg-internal-build-package",
+    "tsc": "tsc --build tsconfig.json",
+    "create-matcher": "npx ts-node ./scripts/createNewMatcher.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "4.1.2",
+    "lodash": "^4.17.21"
+  },
+  "devDependencies": {
+    "@lg-tools/build": "0.3.0",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.1.1",
+    "jsdom": "^22.1.0"
+  },
+  "peerDependencies": {
+    "@testing-library/react": "^14.0.0",
+    "@types/jest": "^29.5.0",
+    "jest": "^29.6.0"
+  },
+  "homepage": "https://github.com/mongodb/leafygreen-ui/tree/main/packages/jest-matchers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mongodb/leafygreen-ui"
+  },
+  "bugs": {
+    "url": "https://jira.mongodb.org/projects/PD/summary"
+  }
+}

tools/jest-matchers/scripts/createNewMatcher.ts

@@ -0,0 +1,60 @@
+import chalk from 'chalk';
+import { Command } from 'commander';
+import fse from 'fs-extra';
+import { camelCase, lowerFirst } from 'lodash';
+import path from 'path';
+
+const cli = new Command();
+cli
+  .argument('<matcher-name>', 'The name of the new matcher')
+  .action(createNewMatcher)
+  .parse();
+
+function createNewMatcher(matcherName: string) {
+  matcherName = lowerFirst(camelCase(matcherName));
+
+  if (!matcherName.startsWith('to')) {
+    console.warn(
+      chalk.yellow(
+        `Matcher names should start with the word "to". Received \`${matcherName}\``,
+      ),
+    );
+  }
+
+  const matchersDir = path.resolve(__dirname, '../src/matchers');
+
+  /** Create the matcher file */
+  const matchersFilePath = path.resolve(matchersDir, matcherName + '.ts');
+  const matcherFileTemplate = `
+import { createMatcher } from '../utils/createMatcher';
+
+export const ${matcherName} = createMatcher(function _${matcherName}() {
+  return {
+    pass: true,
+    message: () => '',
+  };
+});
+`;
+  fse.writeFileSync(matchersFilePath, matcherFileTemplate);
+
+  /** Create the test file */
+
+  const testFilePath = path.resolve(
+    __dirname,
+    '../src/tests',
+    matcherName + '.spec.ts',
+  );
+
+  const testFileTemplate = `
+describe('tools/jest-matchers/.${matcherName}', () => {
+  test.todo('')
+})
+`;
+  fse.writeFileSync(testFilePath, testFileTemplate);
+
+  /** Update the matchers index file */
+  const indexFilePath = path.resolve(matchersDir, 'index.ts');
+  let indexContents = fse.readFileSync(indexFilePath, 'utf-8');
+  indexContents += `export { ${matcherName} } from './${matcherName}';\n`;
+  fse.writeFileSync(indexFilePath, indexContents);
+}

tools/jest-matchers/scripts/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "module": "CommonJS",
+    "noEmit": true,
+    "tsBuildInfoFile": "./tsconfig.tsbuildinfo",
+    "incremental": true,
+    "target": "ES5",
+    "jsx": "react",
+    "allowJs": true,
+    "pretty": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": false,
+    "esModuleInterop": true,
+    "strict": true,
+    "allowSyntheticDefaultImports": true,
+    "moduleResolution": "node",
+    "baseUrl": ".",
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+  }
+}

tools/jest-matchers/src/index.ts

@@ -0,0 +1,3 @@
+import * as matchers from './matchers';
+
+expect.extend(matchers);

tools/jest-matchers/src/matchers/index.ts

@@ -0,0 +1,2 @@
+export { toBeLabelled } from './toBeLabelled';
+export { toSpreadRest } from './toSpreadRest';

tools/jest-matchers/src/matchers/toBeLabelled.ts

@@ -0,0 +1,57 @@
+import { isNull } from 'lodash';
+
+import { createMatcher } from '../utils/createMatcher';
+
+const isValidString = (str: any): str is string =>
+  str && typeof str === 'string' && str.length > 0;
+
+/**
+ * Returns whether the provided element has at least one of the following:
+ * - a `label` attribute
+ * - an `aria-label` attribute
+ * - an `aria-labelledby` attribute with a valid associated element
+ * - an associated element `<label>` element with the appropriate `for` attribute
+ */
+export const toBeLabelled = createMatcher(function _toBeLabelled(
+  element: Element,
+) {
+  const label = element.getAttribute('label');
+  const ariaLabel = element.getAttribute('aria-label');
+  const ariaLabelledBy = element.getAttribute('aria-labelledby');
+  const elementId = element.getAttribute('id');
+
+  // If at least one...
+  const hasStaticLabel = [label, ariaLabel].some(isValidString);
+
+  const hasLabelReference = isValidString(ariaLabelledBy);
+  const doesAriaLabelledByReferenceExist =
+    hasLabelReference && !isNull(document.querySelector(`#${ariaLabelledBy}`));
+  const hasLabelForId =
+    elementId && !isNull(document.querySelector(`label[for="${elementId}"]`));
+
+  const pass = Boolean(
+    hasStaticLabel || doesAriaLabelledByReferenceExist || hasLabelForId,
+  );
+
+  const message = () => {
+    if (!pass && hasLabelReference) {
+      return this.isNot
+        ? `Expected to not find element with id ${ariaLabelledBy}`
+        : `Could not find element referenced by \`aria-labelledby\`` +
+            document.body.innerHTML;
+    }
+
+    if (!pass && elementId) {
+      return this.isNot
+        ? `Expected not to find label for ${elementId}`
+        : `Could not find a label for the element with id ${elementId}`;
+    }
+
+    return `Expected the element ${this.isNot ? 'not ' : ''}to have a label`;
+  };
+
+  return {
+    pass,
+    message,
+  };
+});

tools/jest-matchers/src/matchers/toSpreadRest.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import chalk from 'chalk';
+
+import { createMatcher } from '../utils/createMatcher';
+
+/**
+ * Tests whether a Component
+ */
+export const toSpreadRest = createMatcher(function _toSpreadRest(
+  Component: React.ReactElement,
+) {
+  const rest = {
+    'data-rest': 'value',
+  };
+
+  // @ts-expect-error Type of Component props is unknown
+  const renderResult = render(<Component {...rest} />);
+  const componentElement = renderResult.container.firstElementChild;
+
+  const renderedAttributeKeys = componentElement?.getAttributeNames();
+
+  const areAllRestPropsRendered = Object.keys(rest).every(prop =>
+    renderedAttributeKeys?.includes(prop),
+  );
+
+  const areAllAttributeValuesCorrect =
+    areAllRestPropsRendered &&
+    Object.entries(rest).every(restProp => {
+      const attr = componentElement?.getAttribute(restProp[0]);
+      return attr === restProp[1];
+    });
+
+  const pass = areAllAttributeValuesCorrect;
+
+  return {
+    pass,
+    message: () =>
+      `Expected component to ${this.isNot ? 'not ' : ''}spread rest.\n` +
+      chalk.bold.green(
+        `Expected attributes:\n${Object.keys(rest).join(', ')}\n\n`,
+      ) +
+      chalk.bold.red(`Received props:\n${renderedAttributeKeys?.join(', ')}`),
+  };
+});

tools/jest-matchers/src/tests/toBeLabelled.spec.ts

@@ -0,0 +1,48 @@
+import { render } from './utils/testutils';
+
+describe('tools/jest-matchers/.toBeLabelled', () => {
+  test('unlabelled', () => {
+    const { queryByTestId } = render(`
+      <input type="text" data-testid="unlabelled" />
+    `);
+    expect(queryByTestId('unlabelled')).not.toBeLabelled();
+  });
+
+  test('`label` attribute', () => {
+    const { queryByTestId } = render(`
+      <input label="label" type="text" data-testid="labelled" />
+    `);
+
+    expect(queryByTestId('labelled')).toBeLabelled();
+  });
+
+  test('`aria-label` attribute', () => {
+    const { queryByTestId } = render(`
+      <input aria-label="label" type="text" data-testid="labelled" />
+    `);
+
+    expect(queryByTestId('labelled')).toBeLabelled();
+  });
+
+  test('`aria-labelledby` attribute', () => {
+    const { queryByTestId } = render(`
+      <label id="label-id">Text</label>
+      <input aria-labelledby="label-id" type="text" data-testid="labelled" />
+      <input aria-labelledby="invalid" type="text" data-testid="unlabelled" />
+    `);
+
+    expect(queryByTestId('labelled')).toBeLabelled();
+    expect(queryByTestId('unlabelled')).not.toBeLabelled();
+  });
+
+  test('`for` attribute', () => {
+    const { queryByTestId } = render(`
+      <label for="input-id">Text</label>
+      <input id="input-id" type="text" data-testid="labelled" />
+      <input id="invalid" type="text" data-testid="unlabelled" />
+    `);
+
+    expect(queryByTestId('labelled')).toBeLabelled();
+    expect(queryByTestId('unlabelled')).not.toBeLabelled();
+  });
+});

tools/jest-matchers/src/tests/toSpreadRest.spec.tsx

@@ -0,0 +1,23 @@
+import React from 'react';
+
+describe('tools/jest-matchers/.toSpreadRest', () => {
+  test('spreads rest', () => {
+    const Component = (props: React.ComponentProps<'div'>) => {
+      return (
+        <div id="some-id" {...props}>
+          Children
+        </div>
+      );
+    };
+
+    expect(Component).toSpreadRest();
+  });
+
+  test('does not spread rest', () => {
+    const Component = (props: React.ComponentProps<'div'>) => {
+      return <div id="some-id">Children</div>;
+    };
+
+    expect(Component).not.toSpreadRest();
+  });
+});

tools/jest-matchers/src/tests/utils/testutils.ts

@@ -0,0 +1,29 @@
+const document = (() => {
+  if (global.document) {
+    return global.document;
+  } else {
+    const { JSDOM } = require('jsdom');
+    const { window } = new JSDOM();
+
+    return window.document;
+  }
+})();
+
+function render(html: string) {
+  const container = document.createElement('div');
+  container.innerHTML = html;
+  const queryByTestId = (testId: string) =>
+    container.querySelector(`[data-testid="${testId}"]`);
+  // asFragment has been stolen from react-testing-library
+  const asFragment = () =>
+    document.createRange().createContextualFragment(container.innerHTML);
+
+  // Some tests need to look up global ids with document.getElementById()
+  // so we need to be inside an actual document.
+  document.body.innerHTML = '';
+  document.body.appendChild(container);
+
+  return { container, queryByTestId, asFragment };
+}
+
+export { render };

tools/jest-matchers/src/utils/createMatcher.ts

@@ -0,0 +1,5 @@
+export const createMatcher = (
+  matcher: jest.CustomMatcher,
+): jest.CustomMatcher => {
+  return matcher;
+};

tools/jest-matchers/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "@lg-tools/build/config/package.tsconfig.json",
+   "compilerOptions": {
+    "declarationDir": "dist",
+    "outDir": "dist",
+    "rootDir": "src",
+    "baseUrl": ".",
+    "noUnusedLocals": false
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": ["**/*.spec.*", "**/*.story.*", "src/tests"],
+}

tools/test/config/common.setup.js

@@ -1,4 +1,5 @@
 require('@testing-library/jest-dom');
+require('@lg-tools/jest-matchers');
 
 const { toHaveNoViolations } = require('jest-axe');
 expect.extend(toHaveNoViolations);

tools/test/package.json

@@ -18,6 +18,7 @@
     "@emotion/react": "11.11.1",
     "@emotion/server": "11.11.0",
     "@lg-tools/build": "0.3.1",
+    "@lg-tools/jest-matchers": "0.0.1",
     "@lg-tools/meta": "0.1.5",
     "@testing-library/dom": "9.3.1",
     "@testing-library/jest-dom": "5.17.0",