fix: export usage in different environments

.github/workflows/test.yml

@@ -16,6 +16,11 @@ jobs:
           node-version: 18
       - run: yarn install --frozen-lockfile
       - run: yarn ci
+      # TypeScript Example
+      - run: yarn install --frozen-lockfile
+        working-directory: ./examples/typescript
+      - run: yarn test
+        working-directory: ./examples/typescript
 
   test-node-20:
     runs-on: ubuntu-latest
@@ -26,3 +31,8 @@ jobs:
           node-version: 20
       - run: yarn install --frozen-lockfile
       - run: yarn ci
+      # TypeScript Example
+      - run: yarn install --frozen-lockfile
+        working-directory: ./examples/typescript
+      - run: yarn test
+        working-directory: ./examples/typescript

examples/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+This directory contains a series of self-contained examples that you can use as
+starting points for your setup, or as snippets to pull into your existing
+projects:
+
+| Example                    | Description                                                               |
+| -------------------------- | ------------------------------------------------------------------------- |
+| [TypeScript](./typescript) | A basic TypeScript example using the Virtual Screen Reader Jest Matchers. |

examples/typescript/README.md

@@ -0,0 +1,20 @@
+# TypeScript Example
+
+A basic TypeScript example using the Virtual Screen Reader Jest Matchers.
+
+Run this example with:
+
+```bash
+# Install and build core package
+yarn install --frozen-lockfile
+
+# Navigate to example, install, and test
+cd examples/typescript
+yarn install --frozen-lockfile
+yarn test
+```
+
+> [!IMPORTANT]
+> This example serves to demonstrate how you can use the Virtual Screen Reader Jest Matchers. The components themselves may not be using best accessibility practices.
+>
+> Always evaluate your own components for accessibility and test with real users.

examples/typescript/jest.config.js

@@ -0,0 +1,17 @@
+// eslint-disable-next-line no-undef
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "jsdom",
+  roots: ["src"],
+  collectCoverageFrom: ["**/*.ts"],
+  coveragePathIgnorePatterns: [],
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100,
+    },
+  },
+  setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"],
+};

examples/typescript/jest.setup.ts

@@ -0,0 +1,3 @@
+import "@guidepup/jest";
+
+jest.setTimeout(10000);

examples/typescript/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@guidepup/jest-typescript-example",
+  "version": "1.0.0",
+  "description": "Virtual Screen Reader Jest Matchers TypeScript Example",
+  "author": "Craig Morten <[email protected]>",
+  "license": "MIT",
+  "scripts": {
+    "test": "jest",
+    "test:coverage": "yarn test --coverage"
+  },
+  "devDependencies": {
+    "@guidepup/jest": "file:../../",
+    "@guidepup/virtual-screen-reader": "^0.25.0",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.8",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "ts-jest": "^29.1.5",
+    "typescript": "^5.5.2"
+  }
+}

examples/typescript/src/__snapshots__/index.test.ts.snap

@@ -0,0 +1,69 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`matchers snapshot matchers handles parallel assertions: toMatchScreenReaderSnapshot 1`] = `
+[
+  "region",
+  "heading, Second Section Heading, level 1",
+  "paragraph",
+  "Second Section Text",
+  "end of paragraph",
+  "end of region",
+]
+`;
+
+exports[`matchers toMatchScreenReaderSnapshot on a hidden node: toMatchScreenReaderSnapshot 1`] = `[]`;
+
+exports[`matchers toMatchScreenReaderSnapshot on a null node: toMatchScreenReaderSnapshot 1`] = `[]`;
+
+exports[`matchers toMatchScreenReaderSnapshot on a text node: toMatchScreenReaderSnapshot 1`] = `
+[
+  "Nav Text",
+]
+`;
+
+exports[`matchers toMatchScreenReaderSnapshot on an element: toMatchScreenReaderSnapshot 1`] = `
+[
+  "region",
+  "heading, Second Section Heading, level 1",
+  "paragraph",
+  "Second Section Text",
+  "end of paragraph",
+  "end of region",
+]
+`;
+
+exports[`matchers toMatchScreenReaderSnapshot on the whole body: toMatchScreenReaderSnapshot 1`] = `
+[
+  "document",
+  "navigation",
+  "Nav Text",
+  "end of navigation",
+  "region",
+  "heading, First Section Heading, level 1",
+  "paragraph",
+  "First Section Text",
+  "end of paragraph",
+  "article",
+  "banner",
+  "heading, Article Header Heading, level 1",
+  "paragraph",
+  "Article Header Text",
+  "end of paragraph",
+  "end of banner",
+  "paragraph",
+  "Article Text",
+  "end of paragraph",
+  "end of article",
+  "end of region",
+  "region",
+  "heading, Second Section Heading, level 1",
+  "paragraph",
+  "Second Section Text",
+  "end of paragraph",
+  "end of region",
+  "contentinfo",
+  "Footer",
+  "end of contentinfo",
+  "end of document",
+]
+`;

examples/typescript/src/index.test.ts

@@ -0,0 +1,151 @@
+function setupBasicPage() {
+  document.body.innerHTML = `
+  <nav>Nav Text</nav>
+  <section>
+    <h1>First Section Heading</h1>
+    <p>First Section Text</p>
+    <article>
+      <header>
+        <h1>Article Header Heading</h1>
+        <p>Article Header Text</p>
+      </header>
+      <p>Article Text</p>
+    </article> 
+  </section>
+  <section>
+    <h1>Second Section Heading</h1>
+    <p>Second Section Text</p>
+  </section>
+  <section aria-hidden="true">
+    <h1>Hidden Section Heading</h1>
+    <p>Hidden Section Text</p>
+  </section>
+  <footer>Footer</footer>
+  `;
+}
+
+describe("matchers", () => {
+  beforeEach(() => {
+    setupBasicPage();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = ``;
+  });
+
+  test("toMatchScreenReaderSnapshot on the whole body", async () => {
+    await expect(document.body).toMatchScreenReaderSnapshot();
+  });
+
+  test("toMatchScreenReaderInlineSnapshot on the whole body", async () => {
+    await expect(document.body).toMatchScreenReaderInlineSnapshot(`
+[
+  "document",
+  "navigation",
+  "Nav Text",
+  "end of navigation",
+  "region",
+  "heading, First Section Heading, level 1",
+  "paragraph",
+  "First Section Text",
+  "end of paragraph",
+  "article",
+  "banner",
+  "heading, Article Header Heading, level 1",
+  "paragraph",
+  "Article Header Text",
+  "end of paragraph",
+  "end of banner",
+  "paragraph",
+  "Article Text",
+  "end of paragraph",
+  "end of article",
+  "end of region",
+  "region",
+  "heading, Second Section Heading, level 1",
+  "paragraph",
+  "Second Section Text",
+  "end of paragraph",
+  "end of region",
+  "contentinfo",
+  "Footer",
+  "end of contentinfo",
+  "end of document",
+]
+`);
+  });
+
+  test("toMatchScreenReaderSnapshot on an element", async () => {
+    await expect(
+      document.getElementsByTagName("section")[1]
+    ).toMatchScreenReaderSnapshot();
+  });
+
+  test("toMatchScreenReaderInlineSnapshot on an element", async () => {
+    await expect(document.getElementsByTagName("section")[1]).
+toMatchScreenReaderInlineSnapshot(`
+[
+  "region",
+  "heading, Second Section Heading, level 1",
+  "paragraph",
+  "Second Section Text",
+  "end of paragraph",
+  "end of region",
+]
+`);
+  });
+
+  test("toMatchScreenReaderSnapshot on a text node", async () => {
+    await expect(
+      document.getElementsByTagName("nav")[0].firstChild
+    ).toMatchScreenReaderSnapshot();
+  });
+
+  test("toMatchScreenReaderInlineSnapshot on a text node", async () => {
+    await expect(document.getElementsByTagName("nav")[0].firstChild)
+      .toMatchScreenReaderInlineSnapshot(`
+[
+  "Nav Text",
+]
+`);
+  });
+
+  test("toMatchScreenReaderSnapshot on a hidden node", async () => {
+    await expect(
+      document.querySelector('[aria-hidden="true"]')
+    ).toMatchScreenReaderSnapshot();
+  });
+
+  test("toMatchScreenReaderInlineSnapshot on a hidden node", async () => {
+    await expect(
+      document.querySelector('[aria-hidden="true"]')
+    ).toMatchScreenReaderInlineSnapshot(`[]`);
+  });
+
+  test("toMatchScreenReaderSnapshot on a null node", async () => {
+    await expect(null).toMatchScreenReaderSnapshot();
+  });
+
+  test("toMatchScreenReaderInlineSnapshot on a null node", async () => {
+    await expect(null).toMatchScreenReaderInlineSnapshot(`[]`);
+  });
+
+  test("snapshot matchers handles parallel assertions", async () => {
+    await Promise.all([
+      expect(
+        document.getElementsByTagName("section")[1]
+      ).toMatchScreenReaderSnapshot(),
+      expect(document.getElementsByTagName("section")[1]).
+toMatchScreenReaderInlineSnapshot(`
+[
+  "region",
+  "heading, Second Section Heading, level 1",
+  "paragraph",
+  "Second Section Text",
+  "end of paragraph",
+  "end of region",
+]
+`),
+    ]);
+  });
+});

examples/typescript/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "target": "esnext",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "declaration": true,
+    "rootDir": "./",
+  },
+  "include": ["src/**/*.ts", "jest.setup.ts"],
+  "exclude": ["node_modules"]
+}