test: migrate to Vitest Browser Mode + Playwright and streamline test

suite`

- replace Karma/custom runner with Vitest Browser Mode + Playwright
  (chromium/firefox/edge/webkit)
- add Playwright file-protocol test runner and CI browser matrix
- clean up/rename test structure (`manual` -> `fileProtocol`,
  `types-test` -> `types`, script naming to camelCase)
- simplify fixtures and remove dead/legacy test artifacts
- centralize test cleanup in `test/setup.ts` and simplify `globalSetup`
  to single fixture port
- remove redundant invariant/property suite and tighten communication
  coverage
- modernize type tests (`expectTypeOf`, `assertType` from Vitest) and
  keep negative checks via `@ts-expect-error`
- add `CONTRIBUTING.md` with full script docs and keep README
  consumer-focused

Author: Aaron Hardy

.github/workflows/tests.yml

@@ -0,0 +1,62 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  browser:
+    name: Browser (${{ matrix.browser }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - browser: chromium
+            os: ubuntu-latest
+          - browser: firefox
+            os: ubuntu-latest
+          - browser: webkit
+            os: ubuntu-latest
+          - browser: edge
+            os: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers (Linux)
+        if: runner.os == 'Linux'
+        run: npx playwright install --with-deps chromium firefox webkit
+
+      - name: Run browser tests
+        run: npm run test:${{ matrix.browser }}
+
+  types:
+    name: Type Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run type tests
+        run: npm run test:types

.husky/pre-commit

@@ -3,3 +3,4 @@
 
 npx lint-staged
 npm run test
+npm run test:types

.prettierignore

@@ -2,3 +2,4 @@ dist
 lib
 cjs
 package-lock.json
+test/childFixtures/vendor/**

CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing to Penpal
+
+Thanks for contributing to Penpal.
+
+## Development Setup
+
+1. Install dependencies:
+   - `npm install`
+2. Run tests:
+   - `npm test`
+
+## Testing Overview
+
+Penpal uses Vitest Browser Mode with Playwright for browser-based tests.
+
+- Browser suites live in `test/**/*.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:
+
+- the main browser suite
+- the file-protocol test
+
+Additional browser runs:
+
+- `npm run test:firefox`
+- `npm run test:webkit`
+- `npm run test:edge` (requires Microsoft Edge installed locally)
+
+To run the full browser matrix:
+
+- `npm run test:all-browsers`
+
+## NPM Scripts
+
+All scripts below are defined in `package.json`.
+
+- `npm run build`
+  - Builds ESM, CJS, and IIFE bundles, then builds a minified IIFE bundle.
+- `npm run build:analysis`
+  - Prints minified bundle size analysis for `dist/penpal.min.js`.
+- `npm run lint`
+  - Runs ESLint with autofix and cache enabled.
+- `npm run format`
+  - Runs Prettier on JSON, TS, JS, CJS, Markdown, and HTML files.
+- `npm test`
+  - Alias for `npm run test:chromium`.
+- `npm run test:watch`
+  - Alias for `npm run test:watch:chromium`.
+- `npm run prepublishOnly`
+  - Runs formatting, linting, Chromium tests, type tests, and build before publish.
+- `npm run prepare`
+  - Installs Husky git hooks.
+- `npm run test:watch:chromium`
+  - Runs Vitest Browser Mode in watch mode using Chromium.
+- `npm run test:chromium:browser`
+  - Runs the main browser test suite in Chromium.
+- `npm run test:firefox:browser`
+  - Runs the main browser test suite in Firefox.
+- `npm run test:edge:browser`
+  - Runs the main browser test suite in Edge channel via Playwright.
+- `npm run test:webkit:browser`
+  - Runs the main browser test suite in WebKit.
+- `npm run test:file`
+  - Runs file-protocol tests using the browser selected by `BROWSER`.
+- `npm run test:file:chromium`
+  - Runs file-protocol tests in Chromium.
+- `npm run test:file:firefox`
+  - Runs file-protocol tests in Firefox.
+- `npm run test:file:edge`
+  - Runs file-protocol tests in Edge.
+- `npm run test:file:webkit`
+  - Runs file-protocol tests in WebKit.
+- `npm run test:chromium`
+  - Runs Chromium browser suite and Chromium file-protocol tests.
+- `npm run test:firefox`
+  - Runs Firefox browser suite and Firefox file-protocol tests.
+- `npm run test:edge`
+  - Runs Edge browser suite and Edge file-protocol tests.
+- `npm run test:webkit`
+  - 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:types`
+  - Runs TypeScript type tests with `tsconfig.typesTest.json`.
+- `npm run test:legacy:vendor -- <6.x.x-version>`
+  - Downloads and vendors a Penpal 6 build used by backward-compatibility fixtures.

README.md

@@ -872,3 +872,7 @@ This library is inspired by:
 ## License
 
 MIT
+
+## Contributing
+
+If you'd like to contribute or run the full local test/build workflows, see [CONTRIBUTING.md](./CONTRIBUTING.md).

eslint.config.js

@@ -26,7 +26,7 @@ export default tseslint.config(
     },
   },
   {
-    ignores: ['dist/', 'lib/', 'cjs/'],
+    ignores: ['dist/', 'lib/', 'cjs/', 'test/childFixtures/vendor/**'],
   },
   {
     files: ['*.cjs'],
@@ -38,17 +38,44 @@ export default tseslint.config(
     },
   },
   {
-    files: ['test/types-test/**/*'],
+    files: ['test/types/**/*'],
     rules: {
       '@typescript-eslint/no-unused-vars': 'off',
     },
   },
   {
-    files: ['scripts/**/*', 'karma.conf.cjs'],
+    files: ['scripts/**/*', 'vitest.browser.config.ts'],
     languageOptions: {
       ecmaVersion: ECMA_VERSION,
       globals: globals.node,
     },
+    rules: {
+      'import/extensions': 'off',
+    },
+  },
+  {
+    files: ['test/childFixtures/workers/**/*.js'],
+    languageOptions: {
+      globals: {
+        ...globals.worker,
+        ...globals.serviceworker,
+        Penpal: 'readonly',
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-empty-function': 'off',
+    },
+  },
+  {
+    files: ['test/childFixtures/pages/**/*.js'],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        Penpal: 'readonly',
+        PenpalFixture: 'readonly',
+        PenpalLegacyFixture: 'readonly',
+      },
+    },
   },
   // See https://www.npmjs.com/package/eslint-plugin-unused-imports
   {