test: overhaul browser fixture architecture and test suite structure

- replace monolithic communication specs with a shared contract runner
  used by iframe, worker, port, and backward-compatibility tests
- split connection-management specs into focused suites
  (origins, reconnect, lifecycle, channels, targets)
- extract shared fixture method factories for page/worker/service/shared
  workers
  to remove duplication and reduce fixture coupling
- add async test utilities for message-wait/timeouts and improve
  reconnect probes
- add Vitest node unit suite with dedicated config and scripts
- expand type tests with additional method/options coverage
- scope service-worker cleanup to relevant tests instead of global
  teardown
- fix injected-content worker fixtures for shared script imports
- remove leftover screenshot artifacts and ignore test screenshot output
- update lint/config/docs to match new test topology and scripts

Author: Aaron Hardy

.gitignore

@@ -2,4 +2,5 @@ node_modules
 dist
 lib
 cjs
-.eslintcache
+.eslintcache
+test/__screenshots__/

CONTRIBUTING.md

@@ -14,11 +14,13 @@ Thanks for contributing to Penpal.
 Penpal uses Vitest Browser Mode with Playwright for browser-based tests.
 
 - Browser suites live in `test/**/*.spec.ts`.
+- Unit suites live in `test/unit/**/*.spec.ts`.
 - File-protocol tests live in `test/fileProtocol` and are run via `scripts/testFileProtocol.js`.
 - Type tests live in `test/types` and run via `tsc --noEmit`.
 
-By default, `npm test` runs Chromium coverage (`test:chromium`), which includes both:
+By default, `npm test` runs unit tests and Chromium coverage, which includes:
 
+- the unit suite
 - the main browser suite
 - the file-protocol test
 
@@ -45,7 +47,7 @@ All scripts below are defined in `package.json`.
 - `npm run format`
   - Runs Prettier on JSON, TS, JS, CJS, Markdown, and HTML files.
 - `npm test`
-  - Alias for `npm run test:chromium`.
+  - Runs unit tests, then Chromium browser + file-protocol tests.
 - `npm run test:watch`
   - Alias for `npm run test:watch:chromium`.
 - `npm run prepublishOnly`
@@ -82,6 +84,8 @@ All scripts below are defined in `package.json`.
   - Runs WebKit browser suite and WebKit file-protocol tests.
 - `npm run test:all-browsers`
   - Runs Chromium, Firefox, Edge, and WebKit full test commands.
+- `npm run test:unit`
+  - Runs fast Node-based unit tests in `test/unit`.
 - `npm run test:types`
   - Runs TypeScript type tests with `tsconfig.typesTest.json`.
 - `npm run test:legacy:vendor -- <6.x.x-version>`

eslint.config.js

@@ -44,7 +44,11 @@ export default tseslint.config(
     },
   },
   {
-    files: ['scripts/**/*', 'vitest.browser.config.ts'],
+    files: [
+      'scripts/**/*',
+      'vitest.browser.config.ts',
+      'vitest.unit.config.ts',
+    ],
     languageOptions: {
       ecmaVersion: ECMA_VERSION,
       globals: globals.node,
@@ -60,19 +64,31 @@ export default tseslint.config(
         ...globals.worker,
         ...globals.serviceworker,
         Penpal: 'readonly',
+        PenpalGeneralFixtureMethods: 'readonly',
       },
     },
     rules: {
       '@typescript-eslint/no-empty-function': 'off',
     },
   },
+  {
+    files: ['test/childFixtures/shared/**/*.js'],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.worker,
+        ...globals.serviceworker,
+      },
+    },
+  },
   {
     files: ['test/childFixtures/pages/**/*.js'],
     languageOptions: {
       globals: {
         ...globals.browser,
         Penpal: 'readonly',
         PenpalFixture: 'readonly',
+        PenpalGeneralFixtureMethods: 'readonly',
         PenpalLegacyFixture: 'readonly',
       },
     },

package.json

@@ -48,7 +48,7 @@
     "build:analysis": "node scripts/filesize.js dist/penpal.min.js",
     "lint": "eslint --cache --fix",
     "format": "prettier --write \"**/*.{json,ts,js,cjs,md,html}\"",
-    "test": "npm run test:chromium",
+    "test": "npm-run-all test:unit test:chromium",
     "test:watch": "npm run test:watch:chromium",
     "prepublishOnly": "npm-run-all format lint test test:types build",
     "prepare": "husky install",
@@ -67,6 +67,7 @@
     "test:edge": "npm-run-all test:edge:browser test:file:edge",
     "test:webkit": "npm-run-all test:webkit:browser test:file:webkit",
     "test:all-browsers": "npm-run-all test:chromium test:firefox test:edge test:webkit",
+    "test:unit": "vitest run --config vitest.unit.config.ts",
     "test:types": "tsc --noEmit -p tsconfig.typesTest.json",
     "test:legacy:vendor": "node scripts/updateLegacyPenpal.js"
   },

test/asyncUtils.ts

@@ -0,0 +1,62 @@
+type WaitForMessageOptions<TData = unknown> = {
+  source: Window | MessagePort;
+  predicate: (event: MessageEvent<TData>) => boolean;
+  timeoutMs?: number;
+  timeoutMessage?: string;
+};
+
+export const withTimeout = async <T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  timeoutMessage: string
+) => {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  const timeoutPromise = new Promise<T>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new Error(timeoutMessage));
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};
+
+export const waitForMessageFromSource = async <TData = unknown>({
+  source,
+  predicate,
+  timeoutMs = 5000,
+  timeoutMessage = 'Timed out waiting for message',
+}: WaitForMessageOptions<TData>) => {
+  let handleMessage: ((event: MessageEvent<TData>) => void) | undefined;
+
+  try {
+    return await withTimeout(
+      new Promise<MessageEvent<TData>>((resolve) => {
+        handleMessage = (event: MessageEvent<TData>) => {
+          if (event.source !== source) {
+            return;
+          }
+
+          if (!predicate(event)) {
+            return;
+          }
+
+          window.removeEventListener('message', handleMessage as EventListener);
+          resolve(event);
+        };
+
+        window.addEventListener('message', handleMessage as EventListener);
+      }),
+      timeoutMs,
+      timeoutMessage
+    );
+  } finally {
+    if (handleMessage) {
+      window.removeEventListener('message', handleMessage as EventListener);
+    }
+  }
+};

test/backwardCompatibility/communication.spec.ts

@@ -1,179 +1,17 @@
-import { CallOptions, PenpalError } from '../../src/index.js';
 import type { Methods } from '../../src/index.js';
 import FixtureMethods from '../childFixtures/types/FixtureMethods.js';
+import { runCommunicationContract } from '../contracts/communicationContract.js';
 import { createBackwardCompatibilityIframeAndConnection } from './utils.js';
 
-const createConnection = (methods?: Methods) => {
+const createConnection = (options?: { methods?: Methods }) => {
   return createBackwardCompatibilityIframeAndConnection<FixtureMethods>({
-    methods,
+    methods: options?.methods,
   }).connection;
 };
 
-describe(`BACKWARD COMPATIBILITY: communication between parent and child iframe`, () => {
-  it('calls a function on the child', async () => {
-    const connection = createConnection();
-    const child = await connection.promise;
-    const value = await child.multiply(2, 5);
-    expect(value).toEqual(10);
-    connection.destroy();
-  });
-
-  it('calls nested functions on the child', async () => {
-    const connection = createConnection();
-    const child = await connection.promise;
-    const oneLevel = await child.nested.oneLevel('pen');
-    expect(oneLevel).toEqual('pen');
-    const twoLevels = await child.nested.by.twoLevels('pal');
-    expect(twoLevels).toEqual('pal');
-    connection.destroy();
-  });
-
-  it('calls an asynchronous function on the child', async () => {
-    const connection = createConnection();
-    const child = await connection.promise;
-    const value = await child.multiplyAsync(2, 5);
-    expect(value).toEqual(10);
-    connection.destroy();
-  });
-
-  it('calls a function on the parent', async () => {
-    const connection = createConnection({
-      add: (num1: number, num2: number) => {
-        return num1 + num2;
-      },
-    });
-    const child = await connection.promise;
-    await child.addUsingParent();
-    const value = await child.getParentReturnValue();
-    expect(value).toEqual(9);
-    connection.destroy();
-  });
-
-  it('handles promises rejected with strings', async () => {
-    const connection = createConnection();
-    const child = await connection.promise;
-    await expect(child.getPromiseRejectedWithString()).rejects.toBe(
-      'test error string'
-    );
-    connection.destroy();
-  });
-
-  it('handles promises rejected with objects', async () => {
-    const connection = createConnection();
-    const child = await connection.promise;
-    let error;
-    try {
-      await child.getPromiseRejectedWithObject();
-    } catch (e) {
-      error = e;
-    }
-    expect(error).toEqual({ a: 'b' });
-    connection.destroy();
-  });
-
-  it('handles promises rejected with undefined', async () => {
-    const connection = createConnection();
-    const child = await connection.promise;
-    let catchCalled = false;
-    let error;
-    try {
-      await child.getPromiseRejectedWithUndefined();
-    } catch (e) {
-      catchCalled = true;
-      error = e;
-    }
-    expect(catchCalled).toBe(true);
-    expect(error).toBeUndefined();
-    connection.destroy();
-  });
-
-  it('handles promises rejected with error objects', async () => {
-    const connection = createConnection();
-    const child = await connection.promise;
-    let error;
-    try {
-      await child.getPromiseRejectedWithError();
-    } catch (e) {
-      error = e;
-    }
-    expect(error).toEqual(expect.any(Error));
-    expect((error as Error).name).toBe('TypeError');
-    expect((error as Error).message).toBe('test error object');
-    expect((error as Error).stack).toEqual(expect.any(String));
-    connection.destroy();
-  });
-
-  it('handles thrown errors', async () => {
-    const connection = createConnection();
-    const child = await connection.promise;
-    let error;
-    try {
-      await child.throwError();
-    } catch (e) {
-      error = e;
-    }
-    expect(error).toEqual(expect.any(Error));
-    expect((error as Error).message).toBe('Oh nos!');
-    connection.destroy();
-  });
-
-  it('handles unclonable values', async () => {
-    const connection = createConnection();
-    const child = await connection.promise;
-    let error;
-    try {
-      await child.getUnclonableValue();
-    } catch (e) {
-      error = e;
-    }
-    expect(error).toEqual(expect.any(Error));
-    expect((error as Error).name).toBe('DataCloneError');
-    connection.destroy();
-  });
-
-  it('rejects method call promise if method call timeout reached', async () => {
-    const connection = createConnection();
-    const child = await connection.promise;
-    const promise = child.neverResolve(
-      new CallOptions({
-        timeout: 0,
-      })
-    );
-
-    let error;
-    try {
-      await promise;
-    } catch (e) {
-      error = e;
-    }
-
-    expect(error).toEqual(expect.any(Error));
-    expect((error as Error).message).toBe(
-      'Method call neverResolve() timed out after 0ms'
-    );
-    expect((error as PenpalError).code).toBe('METHOD_CALL_TIMEOUT');
-    connection.destroy();
-  });
-
-  it('rejects method call promise if connection is destroyed before reply is received', async () => {
-    const connection = createConnection();
-    const child = await connection.promise;
-
-    let error: Error;
-
-    child.neverResolve().catch((e) => {
-      error = e;
-    });
-    connection.destroy();
-
-    // Wait for microtask queue to drain
-    await Promise.resolve();
-
-    expect(error!).toEqual(expect.any(Error));
-    expect(error!.message).toBe(
-      'Method call neverResolve() failed due to destroyed connection'
-    );
-    expect((error! as PenpalError).code).toBe('CONNECTION_DESTROYED');
-    connection.destroy();
-  });
+runCommunicationContract({
+  suiteName:
+    'BACKWARD COMPATIBILITY: communication between parent and child iframe',
+  createConnection,
+  includeAdvancedCases: false,
 });

test/backwardCompatibility/connectionLifecycle.spec.ts

@@ -0,0 +1,43 @@
+import { CHILD_SERVER } from '../constants.js';
+import type { PenpalError } from '../../src/index.js';
+import FixtureMethods from '../childFixtures/types/FixtureMethods.js';
+import { createBackwardCompatibilityIframeAndConnection } from './utils.js';
+
+describe('BACKWARD COMPATIBILITY: connection management lifecycle', () => {
+  it('rejects promise if connection timeout passes', async () => {
+    const { connection } = createBackwardCompatibilityIframeAndConnection<
+      FixtureMethods
+    >({
+      url: `${CHILD_SERVER}/never-respond`,
+      timeout: 0,
+    });
+
+    let error;
+    try {
+      await connection.promise;
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toEqual(expect.any(Error));
+    expect((error as Error).message).toBe('Connection timed out after 0ms');
+    expect((error as PenpalError).code).toBe('CONNECTION_TIMEOUT');
+    connection.destroy();
+  });
+
+  it("doesn't destroy connection if connection succeeds then timeout passes", async () => {
+    vi.useFakeTimers();
+    const {
+      iframe,
+      connection,
+    } = createBackwardCompatibilityIframeAndConnection<FixtureMethods>({
+      timeout: 100000,
+    });
+
+    await connection.promise;
+    vi.advanceTimersByTime(10000);
+
+    expect(iframe.parentNode).not.toBeNull();
+
+    connection.destroy();
+  });
+});