@owlmeans/test-ui 0.1.3

package/README.md

@@ -0,0 +1,51 @@
+# @owlmeans/test-ui
+
+Playwright-as-a-library helpers for **bun-test**-driven component acceptance tests of OwlMeans UI packages (`web-panel`, `web-client`, `client-panel`, `client-wl`, `web-flow`, `web-wl`, `client`, `client-i18n`).
+
+These are **not** end-to-end UI tests — they exercise individual components in a real browser, the same way unit tests in other categories exercise individual services. The runner is `bun test` (not `bun x playwright test`), keeping the test toolchain consistent across all four categories.
+
+## Exports
+
+- `launchBrowser(opts?)` — return the shared chromium instance for this `bun test` process. Idempotent.
+- `closeBrowser()` — tear it down. Call from `afterAll`.
+- `withPage(fn)` — convenience: lease a fresh context+page for the duration of `fn`, then dispose the context.
+- `mountComponent({ url, component?, props? })` — opens a fresh context, navigates to a harness URL with the component / props encoded, returns `{ page, close }` so the spec can assert against `page.locator(...)` and dispose the context when done.
+- `Browser`, `BrowserContext`, `Page`, `Locator` — re-exports of the Playwright types so consumers don't need a direct `playwright` import.
+
+## Spec shape
+
+```ts
+import { afterAll, describe, expect, test } from 'bun:test'
+import { closeBrowser, mountComponent } from '@owlmeans/test-ui'
+
+afterAll(async () => { await closeBrowser() })
+
+describe('LoginForm — acceptance', () => {
+  test('renders the heading from the SKILL example', async () => {
+    const { page, close } = await mountComponent({
+      url: 'http://localhost:5173/',
+      component: 'LoginForm',
+      props: { redirect: '/' },
+    })
+    try {
+      expect(await page.locator('h1').textContent()).toBe('Sign in')
+    } finally {
+      await close()
+    }
+  })
+})
+```
+
+## Component harness
+
+`harness/index.html` is a starter page (`<div id="root"></div>` + a `<script type="module" src="/mount.tsx"></script>`). Each consuming UI package serves it via Vite (or any bundler) inside a `beforeAll` hook, registers the components under test from a per-package `mount.tsx` that reads `?component=` and `?props=` from the URL, then mounts via `createRoot(...).render(...)`.
+
+The wiring is per-package because the React/MUI/router providers each package needs differ; see the `testing-ui` skill for the recommended layout.
+
+## One-time setup
+
+```sh
+bunx playwright install chromium
+```
+
+This downloads the Chromium binary used by the `playwright` library. CI installs it as a workflow step.

package/build/browser.d.ts

@@ -0,0 +1,19 @@
+import type { Browser, LaunchOptions } from 'playwright';
+/**
+ * Launch (or return) a single shared chromium instance for the current
+ * `bun test` process. UI specs hold a fixture page off this browser; the
+ * suite calls `closeBrowser()` from `afterAll` to tear it down once.
+ */
+export declare const launchBrowser: (opts?: LaunchOptions) => Promise<Browser>;
+/**
+ * Tear down the shared browser. Idempotent — safe to call from multiple
+ * `afterAll` hooks.
+ */
+export declare const closeBrowser: () => Promise<void>;
+/**
+ * Convenience that launches the browser, runs a callback with a fresh
+ * context + page, and closes the context on completion. The browser
+ * itself stays alive across calls so multiple specs share it cheaply.
+ */
+export declare const withPage: <T>(fn: (page: import("playwright").Page) => Promise<T>) => Promise<T>;
+//# sourceMappingURL=browser.d.ts.map

package/build/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAKxD;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAU,OAAM,aAAkB,KAAG,OAAO,CAAC,OAAO,CAO7E,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAa,OAAO,CAAC,IAAI,CAOjD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,EAC9B,IAAI,CAAC,IAAI,EAAE,OAAO,YAAY,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAClD,OAAO,CAAC,CAAC,CASX,CAAA"}

package/build/browser.js

@@ -0,0 +1,47 @@
+import { chromium } from 'playwright';
+let shared;
+let inflight;
+/**
+ * Launch (or return) a single shared chromium instance for the current
+ * `bun test` process. UI specs hold a fixture page off this browser; the
+ * suite calls `closeBrowser()` from `afterAll` to tear it down once.
+ */
+export const launchBrowser = async (opts = {}) => {
+    if (shared != null)
+        return shared;
+    if (inflight != null)
+        return inflight;
+    inflight = chromium.launch({ headless: true, ...opts });
+    shared = await inflight;
+    inflight = undefined;
+    return shared;
+};
+/**
+ * Tear down the shared browser. Idempotent — safe to call from multiple
+ * `afterAll` hooks.
+ */
+export const closeBrowser = async () => {
+    const b = shared;
+    shared = undefined;
+    inflight = undefined;
+    if (b != null) {
+        await b.close();
+    }
+};
+/**
+ * Convenience that launches the browser, runs a callback with a fresh
+ * context + page, and closes the context on completion. The browser
+ * itself stays alive across calls so multiple specs share it cheaply.
+ */
+export const withPage = async (fn) => {
+    const browser = await launchBrowser();
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    try {
+        return await fn(page);
+    }
+    finally {
+        await context.close();
+    }
+};
+//# sourceMappingURL=browser.js.map

package/build/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAGrC,IAAI,MAA2B,CAAA;AAC/B,IAAI,QAAsC,CAAA;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,OAAsB,EAAE,EAAoB,EAAE;IAChF,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,MAAM,CAAA;IACjC,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,QAAQ,CAAA;IACrC,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,CAAA;IACvD,MAAM,GAAG,MAAM,QAAQ,CAAA;IACvB,QAAQ,GAAG,SAAS,CAAA;IACpB,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,IAAmB,EAAE;IACpD,MAAM,CAAC,GAAG,MAAM,CAAA;IAChB,MAAM,GAAG,SAAS,CAAA;IAClB,QAAQ,GAAG,SAAS,CAAA;IACpB,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QACd,MAAM,CAAC,CAAC,KAAK,EAAE,CAAA;IACjB,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAC3B,EAAmD,EACvC,EAAE;IACd,MAAM,OAAO,GAAG,MAAM,aAAa,EAAE,CAAA;IACrC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAA;IAC1C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAA;IACpC,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,IAAI,CAAC,CAAA;IACvB,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAA;IACvB,CAAC;AACH,CAAC,CAAA"}

package/build/config.d.ts

@@ -0,0 +1,15 @@
+import type { PlaywrightTestConfig } from '@playwright/test';
+/**
+ * Wrap `defineConfig` from `@playwright/test` with OwlMeans-wide defaults
+ * for category-D acceptance tests:
+ *
+ * - `testDir: './tests'`
+ * - chromium-only (override `projects` to add WebKit/Firefox)
+ * - retries `0` locally, `1` in CI
+ * - 10s navigation timeout
+ *
+ * Pass overrides such as `webServer`, `baseURL`, or additional `projects`
+ * directly through. Anything you set wins over the defaults.
+ */
+export declare const defineUiConfig: (overrides?: PlaywrightTestConfig) => PlaywrightTestConfig;
+//# sourceMappingURL=config.d.ts.map

package/build/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAI5D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GAAI,YAAW,oBAAyB,KAAG,oBAelE,CAAA"}

package/build/config.js

@@ -0,0 +1,30 @@
+import { defineConfig, devices } from '@playwright/test';
+const isCi = process.env.CI === 'true' || process.env.CI === '1';
+/**
+ * Wrap `defineConfig` from `@playwright/test` with OwlMeans-wide defaults
+ * for category-D acceptance tests:
+ *
+ * - `testDir: './tests'`
+ * - chromium-only (override `projects` to add WebKit/Firefox)
+ * - retries `0` locally, `1` in CI
+ * - 10s navigation timeout
+ *
+ * Pass overrides such as `webServer`, `baseURL`, or additional `projects`
+ * directly through. Anything you set wins over the defaults.
+ */
+export const defineUiConfig = (overrides = {}) => defineConfig({
+    testDir: './tests',
+    fullyParallel: true,
+    forbidOnly: isCi,
+    retries: isCi ? 1 : 0,
+    reporter: isCi ? [['github'], ['list']] : 'list',
+    use: {
+        trace: 'on-first-retry',
+        ...overrides.use,
+    },
+    projects: overrides.projects ?? [
+        { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    ],
+    ...overrides,
+});
+//# sourceMappingURL=config.js.map

package/build/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAGxD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,CAAA;AAEhE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,YAAkC,EAAE,EAAwB,EAAE,CAC3F,YAAY,CAAC;IACX,OAAO,EAAE,SAAS;IAClB,aAAa,EAAE,IAAI;IACnB,UAAU,EAAE,IAAI;IAChB,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrB,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM;IAChD,GAAG,EAAE;QACH,KAAK,EAAE,gBAAgB;QACvB,GAAG,SAAS,CAAC,GAAG;KACjB;IACD,QAAQ,EAAE,SAAS,CAAC,QAAQ,IAAI;QAC9B,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,EAAE,EAAE;KAC5D;IACD,GAAG,SAAS;CACb,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,4 @@
+export * from './browser.js';
+export * from './mount.js';
+export type { Browser, BrowserContext, Locator, Page } from 'playwright';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA"}

package/build/index.js

@@ -0,0 +1,3 @@
+export * from './browser.js';
+export * from './mount.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/build/mount.d.ts

@@ -0,0 +1,40 @@
+import type { Page } from 'playwright';
+export interface MountOptions {
+    /**
+     * URL the harness is reachable at. The consuming package is in charge
+     * of producing it — typically a Vite dev server pointed at
+     * `node_modules/@owlmeans/test-ui/harness/` plus a per-package
+     * `mount.tsx` that registers the components under test, OR an
+     * inlined `data:text/html,...` URL for the simplest smoke tests.
+     */
+    url: string;
+    /**
+     * Component name registered in the harness. Appended as `?component=`.
+     * Omit when the harness mounts a single fixed root.
+     */
+    component?: string;
+    /**
+     * JSON-serialisable props passed to the component. Encoded into the
+     * URL as `?props=<json>` for the harness's `mount.tsx` to read.
+     */
+    props?: Record<string, unknown>;
+}
+export interface Mounted {
+    page: Page;
+    /** Closes the page's browser context — the shared browser stays alive. */
+    close: () => Promise<void>;
+}
+/**
+ * Open a fresh browser context, navigate to the harness URL with the
+ * `component` and `props` query parameters set, and return the `Page`
+ * along with a `close()` that disposes the context. Use from a `bun:test`
+ * spec to drive component-level acceptance assertions:
+ *
+ *     const { page, close } = await mountComponent({ url: HARNESS, component: 'LoginForm' })
+ *     try { expect(await page.locator('h1').textContent()).toBe('Sign in') }
+ *     finally { await close() }
+ *
+ * `closeBrowser()` from `afterAll` tears down the shared browser at the end of the suite.
+ */
+export declare const mountComponent: (opts: MountOptions) => Promise<Mounted>;
+//# sourceMappingURL=mount.d.ts.map

package/build/mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../src/mount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAGtC,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,IAAI,CAAA;IACV,0EAA0E;IAC1E,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAYD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GAAU,MAAM,YAAY,KAAG,OAAO,CAAC,OAAO,CASxE,CAAA"}

package/build/mount.js

@@ -0,0 +1,36 @@
+import { launchBrowser } from './browser.js';
+const buildUrl = (opts) => {
+    const params = new URLSearchParams();
+    if (opts.component != null)
+        params.set('component', opts.component);
+    if (opts.props != null)
+        params.set('props', JSON.stringify(opts.props));
+    const qs = params.toString();
+    if (qs === '')
+        return opts.url;
+    const sep = opts.url.includes('?') ? '&' : '?';
+    return `${opts.url}${sep}${qs}`;
+};
+/**
+ * Open a fresh browser context, navigate to the harness URL with the
+ * `component` and `props` query parameters set, and return the `Page`
+ * along with a `close()` that disposes the context. Use from a `bun:test`
+ * spec to drive component-level acceptance assertions:
+ *
+ *     const { page, close } = await mountComponent({ url: HARNESS, component: 'LoginForm' })
+ *     try { expect(await page.locator('h1').textContent()).toBe('Sign in') }
+ *     finally { await close() }
+ *
+ * `closeBrowser()` from `afterAll` tears down the shared browser at the end of the suite.
+ */
+export const mountComponent = async (opts) => {
+    const browser = await launchBrowser();
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    await page.goto(buildUrl(opts));
+    return {
+        page,
+        close: async () => { await context.close(); },
+    };
+};
+//# sourceMappingURL=mount.js.map

package/build/mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.js","sourceRoot":"","sources":["../src/mount.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AA6B5C,MAAM,QAAQ,GAAG,CAAC,IAAkB,EAAU,EAAE;IAC9C,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;IACpC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IACnE,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;IACvE,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;IAC5B,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,GAAG,CAAA;IAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAA;IAC9C,OAAO,GAAG,IAAI,CAAC,GAAG,GAAG,GAAG,GAAG,EAAE,EAAE,CAAA;AACjC,CAAC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EAAE,IAAkB,EAAoB,EAAE;IAC3E,MAAM,OAAO,GAAG,MAAM,aAAa,EAAE,CAAA;IACrC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAA;IAC1C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAA;IACpC,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;IAC/B,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,KAAK,IAAI,EAAE,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAA,CAAC,CAAC;KAC7C,CAAA;AACH,CAAC,CAAA"}

package/harness/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>@owlmeans/test-ui harness</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/mount.tsx"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@owlmeans/test-ui",
+  "version": "0.1.3",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    },
+    "./harness": "./harness/index.html"
+  },
+  "dependencies": {
+    "@owlmeans/test": "^0.1.3",
+    "playwright": "^1.49.0"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-dom": "*"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "react-dom": { "optional": true }
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "^0.1.3",
+    "@types/bun": "^1.3.0",
+    "@types/react": "^19.2.7",
+    "nodemon": "^3.1.11",
+    "typescript": "^6.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/browser.ts

@@ -0,0 +1,50 @@
+import { chromium } from 'playwright'
+import type { Browser, LaunchOptions } from 'playwright'
+
+let shared: Browser | undefined
+let inflight: Promise<Browser> | undefined
+
+/**
+ * Launch (or return) a single shared chromium instance for the current
+ * `bun test` process. UI specs hold a fixture page off this browser; the
+ * suite calls `closeBrowser()` from `afterAll` to tear it down once.
+ */
+export const launchBrowser = async (opts: LaunchOptions = {}): Promise<Browser> => {
+  if (shared != null) return shared
+  if (inflight != null) return inflight
+  inflight = chromium.launch({ headless: true, ...opts })
+  shared = await inflight
+  inflight = undefined
+  return shared
+}
+
+/**
+ * Tear down the shared browser. Idempotent — safe to call from multiple
+ * `afterAll` hooks.
+ */
+export const closeBrowser = async (): Promise<void> => {
+  const b = shared
+  shared = undefined
+  inflight = undefined
+  if (b != null) {
+    await b.close()
+  }
+}
+
+/**
+ * Convenience that launches the browser, runs a callback with a fresh
+ * context + page, and closes the context on completion. The browser
+ * itself stays alive across calls so multiple specs share it cheaply.
+ */
+export const withPage = async <T>(
+  fn: (page: import('playwright').Page) => Promise<T>
+): Promise<T> => {
+  const browser = await launchBrowser()
+  const context = await browser.newContext()
+  const page = await context.newPage()
+  try {
+    return await fn(page)
+  } finally {
+    await context.close()
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './browser.js'
+export * from './mount.js'
+export type { Browser, BrowserContext, Locator, Page } from 'playwright'

package/src/mount.ts

@@ -0,0 +1,62 @@
+import type { Page } from 'playwright'
+import { launchBrowser } from './browser.js'
+
+export interface MountOptions {
+  /**
+   * URL the harness is reachable at. The consuming package is in charge
+   * of producing it — typically a Vite dev server pointed at
+   * `node_modules/@owlmeans/test-ui/harness/` plus a per-package
+   * `mount.tsx` that registers the components under test, OR an
+   * inlined `data:text/html,...` URL for the simplest smoke tests.
+   */
+  url: string
+  /**
+   * Component name registered in the harness. Appended as `?component=`.
+   * Omit when the harness mounts a single fixed root.
+   */
+  component?: string
+  /**
+   * JSON-serialisable props passed to the component. Encoded into the
+   * URL as `?props=<json>` for the harness's `mount.tsx` to read.
+   */
+  props?: Record<string, unknown>
+}
+
+export interface Mounted {
+  page: Page
+  /** Closes the page's browser context — the shared browser stays alive. */
+  close: () => Promise<void>
+}
+
+const buildUrl = (opts: MountOptions): string => {
+  const params = new URLSearchParams()
+  if (opts.component != null) params.set('component', opts.component)
+  if (opts.props != null) params.set('props', JSON.stringify(opts.props))
+  const qs = params.toString()
+  if (qs === '') return opts.url
+  const sep = opts.url.includes('?') ? '&' : '?'
+  return `${opts.url}${sep}${qs}`
+}
+
+/**
+ * Open a fresh browser context, navigate to the harness URL with the
+ * `component` and `props` query parameters set, and return the `Page`
+ * along with a `close()` that disposes the context. Use from a `bun:test`
+ * spec to drive component-level acceptance assertions:
+ *
+ *     const { page, close } = await mountComponent({ url: HARNESS, component: 'LoginForm' })
+ *     try { expect(await page.locator('h1').textContent()).toBe('Sign in') }
+ *     finally { await close() }
+ *
+ * `closeBrowser()` from `afterAll` tears down the shared browser at the end of the suite.
+ */
+export const mountComponent = async (opts: MountOptions): Promise<Mounted> => {
+  const browser = await launchBrowser()
+  const context = await browser.newContext()
+  const page = await context.newPage()
+  await page.goto(buildUrl(opts))
+  return {
+    page,
+    close: async () => { await context.close() },
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.bun.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./harness/**/*",
+    "./*.ts"
+  ]
+}