@owlmeans/test-ui 0.1.7 → 0.1.9

package/README.md

@@ -49,3 +49,20 @@ bunx playwright install chromium
 ```
 
 This downloads the Chromium binary used by the `playwright` library. CI installs it as a workflow step.
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/instructions/testing-ui.instructions.md

@@ -0,0 +1,21 @@
+---
+applyTo: "**/*.test.ts, **/*.spec.ts, **/*.ts"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Category D — Component Acceptance Tests (bun test + Playwright as a library)
+
+- Tests in `<your-package>/tests/*.spec.ts`. Use `bun:test` (`describe`, `test`, `expect`) — same as categories A/B/C.
+- Playwright is consumed as a **library**: `import { launchBrowser, closeBrowser, mountComponent } from '@owlmeans/test-ui'`. Never `import` from `@playwright/test`.
+- Mount one component at a time via `mountComponent({ url, component?, props? })`. Tests are component-level acceptance — not end-to-end.
+- Always `await close()` the returned context and call `closeBrowser()` from `afterAll` — leaked contexts hang `bun test`.
+- Use `bun:test`'s `expect` against awaited Playwright DOM queries: `expect(await page.locator('h1').textContent()).toBe('Sign in')`.
+- Per-package harness (`tests/harness/index.html` + `mount.tsx`) is served by a Vite dev server booted once in `tests/context.ts`. For smoke-only specs a `data:text/html,...` URL is fine.
+- **shadcn + Tailwind packages**: add `@tailwindcss/vite` plugin and `resolve.alias: { '@': resolve(here, '../src/@') }` to the Vite config so mounted components resolve primitives; import `src/@/globals.css` in `mount.tsx`. Assert via `getByRole`/text as usual; check computed styles via `page.evaluate` for visual assertions.
+- One-time per machine: `bunx playwright install chromium`.
+- No mocks. Render the real component with real client-context wiring. For network calls use `page.route(...)` to a static fixture — never a live backend.
+- Cover `.github/instructions/<pkg>.instructions.md` and `README.md` cases first.
+- Max 3-4 tests per component: render, primary interaction, one edge case.
+- Per-package `package.json` script: `"test": "bun test ./tests"` — same line as categories A/B/C.
+
+See `.claude/skills/testing-ui/SKILL.md` for the full pattern.

package/agent-meta/manifest.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/test-ui",
+  "version": "0.1.9",
+  "generatedAt": "2026-06-14T13:34:06.126Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "testing-ui",
+      "category": "package-specific",
+      "file": "skills/testing-ui/SKILL.md",
+      "canonicalPath": ".claude/skills/testing-ui/SKILL.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "testing-ui",
+      "category": "package-specific",
+      "file": "instructions/testing-ui.instructions.md",
+      "canonicalPath": ".github/instructions/testing-ui.instructions.md"
+    }
+  ]
+}

package/agent-meta/skills/testing-ui/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: testing-ui
+description: Category-D component-level acceptance tests for OwlMeans Common UI packages (web-panel, web-client, client-panel, client-wl, web-flow, web-wl, client, client-i18n) and new shadcn UI + Tailwind v4 packages. Run under bun test, drive a real chromium via Playwright as a library — not the Playwright runner. Auto-invoked when writing tests in those packages.
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# UI Acceptance Tests — Category D (bun test + Playwright as a library)
+
+Category D applies to packages that ship rendered React UI: `client`, `client-i18n`, `client-panel`, `client-wl`, `web-client`, `web-flow`, `web-panel`, `web-wl`. Tests are **component-level acceptance** — they mount one component in a real browser and assert against rendered DOM. They are **not** end-to-end tests (no router-deep navigation, no live backend).
+
+The runner is **`bun test`** — same as categories A/B/C — kept consistent so contributors only learn one harness. Playwright is consumed as a **library** (`playwright` package, not `@playwright/test`). The `playwright` library exposes `chromium`, `firefox`, `webkit` browser launchers; specs drive them directly from inside `bun:test` blocks.
+
+Service-only "client-*" packages (`client-flow`, `client-socket`, `web-router`, `web-db`) belong to category A — they have no rendered UI.
+
+Auth-related UI packages (`web-oidc-rp`, `web-oidc-provider`, `client-auth`, `client-payment`) belong to category B and use `bun test` + `@owlmeans/test-auth`, not the chromium harness.
+
+## Layout
+
+```
+<your-package>/
+├── src/...
+└── tests/
+    ├── harness/              # per-package: components registry + mount config
+    │   ├── index.html        # copy of @owlmeans/test-ui/harness/index.html
+    │   └── mount.tsx         # registers components, reads ?component= and ?props=
+    ├── context.ts            # one place that boots the harness server, exports HARNESS_URL
+    └── <area>.spec.ts        # *.spec.ts only
+```
+
+## One-time setup (per developer machine)
+
+```sh
+bunx playwright install chromium
+```
+
+Downloads the chromium binary the `playwright` library drives. CI installs it in a workflow step.
+
+## Helpers from `@owlmeans/test-ui`
+
+| Helper | Purpose |
+|---|---|
+| `launchBrowser(opts?)` | Return the shared chromium for this `bun test` process. Idempotent. |
+| `closeBrowser()` | Tear it down. Call from `afterAll`. |
+| `withPage(fn)` | Lease a fresh context+page for the duration of `fn`, dispose context on completion. |
+| `mountComponent({ url, component?, props? })` | Open a fresh context, navigate to the harness URL with `?component=` and `?props=` set, return `{ page, close }`. |
+| Re-exports: `Browser`, `BrowserContext`, `Page`, `Locator` | Playwright types — no direct `playwright` import needed. |
+
+## Spec shape
+
+```ts
+import { afterAll, describe, expect, test } from 'bun:test'
+import { closeBrowser, mountComponent } from '@owlmeans/test-ui'
+import { HARNESS_URL } from './context.js'
+
+afterAll(async () => { await closeBrowser() })
+
+describe('<package> — <component>', () => {
+  test('renders the SKILL.md happy-path example', async () => {
+    const { page, close } = await mountComponent({
+      url: HARNESS_URL,
+      component: 'LoginForm',
+      props: { redirect: '/' },
+    })
+    try {
+      expect(await page.locator('h1').textContent()).toBe('Sign in')
+      expect(await page.getByRole('button', { name: /sign in/i }).isVisible()).toBe(true)
+    } finally {
+      await close()
+    }
+  })
+})
+```
+
+Use `bun:test`'s `expect` against awaited Playwright DOM queries (`textContent()`, `isVisible()`, `getAttribute()`). Don't import `expect` from `@playwright/test` — that would pull in the full runner and create two parallel test toolchains.
+
+## Per-package `tests/context.ts`
+
+The harness needs a real HTTP server because module-style React components can't run from a `data:` URL. Boot it once per `bun test` process:
+
+```ts
+import { createServer } from 'vite'
+import react from '@vitejs/plugin-react'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+let url: string | null = null
+
+export const getHarnessUrl = async (): Promise<string> => {
+  if (url != null) return url
+  const server = await createServer({
+    configFile: false,
+    root: resolve(here, './harness'),
+    plugins: [react()],
+    server: { port: 0 },
+  })
+  await server.listen()
+  const local = server.resolvedUrls?.local?.[0]
+  if (local == null) throw new Error('vite did not expose a local URL')
+  url = local
+  return url
+}
+
+export const HARNESS_URL = await getHarnessUrl()
+```
+
+The per-package `tests/harness/mount.tsx` reads `?component=<name>` and `?props=<json>`, dynamic-imports the component from the consumer's `src/`, and renders it via `react-dom/client` inside `<div id="root">`. Each consuming UI package wires its own providers (MUI theme for legacy packages, or Tailwind CSS + `@` alias for shadcn packages; plus i18n, router) the way the real app does — that's why mount.tsx is per-package, not in `@owlmeans/test-ui`.
+
+## Smoke-only baseline
+
+For a package that only needs to prove the bun-test + chromium pipeline works (e.g. `web-panel`'s pilot), skip the Vite harness and serve a `data:text/html` URL inline:
+
+```ts
+import { afterAll, describe, expect, test } from 'bun:test'
+import { closeBrowser, mountComponent } from '@owlmeans/test-ui'
+
+const harness = `data:text/html,${encodeURIComponent('<h1 id="t">hello</h1>')}`
+
+afterAll(async () => { await closeBrowser() })
+
+describe('chromium smoke', () => {
+  test('reads a heading from a data: URL', async () => {
+    const { page, close } = await mountComponent({ url: harness })
+    try { expect(await page.locator('#t').textContent()).toBe('hello') }
+    finally { await close() }
+  })
+})
+```
+
+## Wiring `bun test`
+
+Per-package `package.json`:
+
+```json
+"scripts": {
+  "test": "bun test ./tests"
+}
+```
+
+Same line as categories A/B/C. No `playwright.config.ts`, no `bun x playwright test`.
+
+## Tailwind + shadcn packages
+
+For shadcn-based OwlMeans packages the `tests/context.ts` Vite config needs two additions beyond the standard setup:
+
+```ts
+import tailwindcss from '@tailwindcss/vite'
+import { resolve } from 'node:path'
+
+const server = await createServer({
+  configFile: false,
+  root: resolve(here, './harness'),
+  plugins: [react(), tailwindcss()],               // add Tailwind v4 Vite plugin
+  resolve: {
+    alias: { '@': resolve(here, '../src/@') },     // resolve @/ to the package's local copy
+  },
+  server: { port: 0 },
+})
+```
+
+`tests/harness/mount.tsx` imports the package CSS so components render with Tailwind styles:
+
+```tsx
+import '../../src/@/globals.css'
+// ... dynamic component mounting ...
+```
+
+Shadcn components are plain React — no theme provider needed. Assert via `getByRole` / text as usual. To verify that Tailwind classes took visual effect, read computed styles:
+
+```ts
+const bg = await page.locator('button').evaluate(el =>
+  window.getComputedStyle(el).backgroundColor
+)
+expect(bg).not.toBe('')
+```
+
+See `[[shadcn-web]]` for the full `@` alias contract and `tests/context.ts` pattern.
+
+## Rules
+
+- **No mocks.** Render the real component with real client-context wiring (state, i18n, router) the way the app does. For network calls, use Playwright's `page.route(...)` to a static fixture — never point at a live backend.
+- **Cover SKILL.md and README.md cases first.** Each component the package documents gets at least one acceptance spec for its happy path.
+- **Max 3-4 tests per component**: render, primary interaction, one edge case.
+- **Always `close()` the page and `closeBrowser()` in `afterAll`.** A leaked context blocks the bun process from exiting.
+- **Chromium only by default.** Add `firefox` or `webkit` per package only when the feature has documented cross-browser concerns — call `chromium.launch` / `firefox.launch` explicitly in that case.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/test-ui",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,7 +22,7 @@
     "./harness": "./harness/index.html"
   },
   "dependencies": {
-    "@owlmeans/test": "^0.1.7",
+    "@owlmeans/test": "^0.1.9",
     "playwright": "^1.49.0"
   },
   "peerDependencies": {
@@ -38,7 +38,7 @@
     }
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "^0.1.7",
+    "@owlmeans/dep-config": "^0.1.9",
     "@types/bun": "^1.3.0",
     "@types/react": "^19.2.7",
     "nodemon": "^3.1.11",