@brendanbank/atrium-test-utils 0.15.0

package/LICENCE.md

@@ -0,0 +1,25 @@
+# BSD 2-Clause License
+
+Copyright (c) 2026, Brendan Bank
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,153 @@
+# `@brendanbank/atrium-test-utils`
+
+Vitest helpers for unit-testing [atrium](https://github.com/brendanbank/atrium)
+host bundles. Replaces hand-rolled mocks of `window.__ATRIUM_REGISTRY__`
++ `window.React` + `useMe()` so a host can render permission-gated
+components and fire synthetic SSE events without spinning up the SPA.
+
+## Why
+
+Before this package, casa-style host tests had to wire mocks like:
+
+```ts
+beforeEach(() => {
+  (window as any).__ATRIUM_REGISTRY__ = {
+    registerHomeWidget: vi.fn(),
+    /* …seven more vi.fn()s… */
+    subscribeEvent: vi.fn(),
+  };
+  (window as any).React = require('react');
+});
+```
+
+…and stub `useMe`'s underlying fetch separately. The seam is the same
+in every host, so most teams skipped the unit tests and relied on
+Playwright. This package gives them back.
+
+## Installation
+
+```
+pnpm add -D @brendanbank/atrium-test-utils
+```
+
+The package is published on **GitHub Packages**, same scope as the
+other atrium SDK packages — see the host-bundle-utils
+[`README`](../host-bundle-utils/README.md) for the `.npmrc` setup.
+
+`vitest`, `@testing-library/react`, `react`, `react-dom`, and
+`@tanstack/react-query` are peer deps — install them once in your
+host's `frontend/package.json`; this package will not bundle a
+second copy.
+
+## Usage
+
+```tsx
+import {
+  fireAtriumEvent,
+  mockAtriumRegistry,
+  renderWithAtrium,
+  type MockAtriumHandles,
+  type UserContext,
+} from '@brendanbank/atrium-test-utils';
+
+const ALICE: UserContext = {
+  id: 1, email: 'alice@example.com', full_name: 'Alice',
+  is_active: true,
+  roles: ['owner'],
+  permissions: ['commission.view.all'],
+  impersonating_from: null,
+};
+
+let handles: MockAtriumHandles;
+
+beforeEach(() => {
+  handles = mockAtriumRegistry({ me: ALICE });
+});
+
+afterEach(() => {
+  handles.cleanup();
+});
+
+test('owners see the per-agent picker, not the self view', () => {
+  const { getByLabelText } = renderWithAtrium(<CommissionsPage />);
+  expect(getByLabelText('Agent')).toBeInTheDocument();
+});
+
+test('the host bundle registers a home widget on import', async () => {
+  await import('../src/main');
+  expect(handles.homeWidgets).toHaveLength(1);
+  expect(handles.homeWidgets[0].key).toBe('commission-card');
+});
+
+test('refetches bookings on booking.created', async () => {
+  renderWithAtrium(<BookingsPage />);
+  fireAtriumEvent('booking.created', { booking_id: 42 });
+  // …assert refetch fired
+});
+```
+
+## API
+
+### `mockAtriumRegistry(options?)`
+
+Installs a recording fake on `window.__ATRIUM_REGISTRY__`, exposes
+React via `window.React`, and stubs `window.__atrium_i18n__` with
+the bundled `common.*` keys. Returns handles:
+
+| Field                  | Type                          | Description                                           |
+| ---------------------- | ----------------------------- | ----------------------------------------------------- |
+| `registry`             | `AtriumRegistry`              | The fake (also at `window.__ATRIUM_REGISTRY__`).      |
+| `homeWidgets`          | `HomeWidget[]`                | Recorded `registerHomeWidget` calls in order.         |
+| `routes`               | `RouteEntry[]`                | Recorded `registerRoute` calls.                       |
+| `navItems`             | `NavItem[]`                   | Recorded `registerNavItem` calls.                     |
+| `adminTabs`            | `AdminTab[]`                  | Recorded `registerAdminTab` calls.                    |
+| `profileItems`         | `ProfileItem[]`               | Recorded `registerProfileItem` calls.                 |
+| `notificationKinds`    | `NotificationKindRenderer[]`  | Recorded `registerNotificationKind` calls.            |
+| `localeOverlays`       | `LocaleOverlay[]`             | Recorded `registerLocale` calls.                      |
+| `reset()`              | `() => void`                  | Drop registrations + subscribers, keep window mocks.  |
+| `cleanup()`            | `() => void`                  | Restore pre-mock window state. Call in `afterEach`.   |
+
+Options:
+
+| Option              | Description                                                                  |
+| ------------------- | ---------------------------------------------------------------------------- |
+| `me`                | What `useMe()` resolves to. Pass `null` for signed-out. Default `null`.      |
+| `i18n.resources`    | Locale → flat dot-path → string. Default: bundled English `common.*`.        |
+| `i18n.language`     | Active locale. Default `'en'`.                                               |
+
+### `renderWithAtrium(ui, options?)`
+
+`@testing-library/react`'s `render` pre-wired with a fresh
+`QueryClient` and `<AtriumProvider>` pointed at the configured `me`.
+Returns the standard `RenderResult` so existing assertions
+(`getByRole`, `rerender`, `unmount`) work unchanged.
+
+Options extend the standard `RenderOptions` with:
+
+| Option        | Description                                                              |
+| ------------- | ------------------------------------------------------------------------ |
+| `me`          | Override `me` for this render. Falls back to the registry default.       |
+| `queryClient` | Share a client across renders so cache assertions survive remounts.      |
+| `wrap`        | Additional wrapper component (e.g. `MantineProvider`, `RouterProvider`). |
+
+### `fireAtriumEvent(kind, payload)`
+
+Dispatches a synthetic SSE-style event to every handler the host
+registered via the fake registry's `subscribeEvent`. No-op when
+called outside a `mockAtriumRegistry` scope, so a forgotten setup
+shows as an empty assertion rather than a crash.
+
+## Versioning
+
+Tracks `@brendanbank/atrium-host-bundle-utils`'s public API. When a
+new registry slot lands in host-bundle-utils, the matching mock
+shows up here in the next minor.
+
+## See also
+
+- [`@brendanbank/atrium-host-bundle-utils`](../host-bundle-utils/) — the
+  runtime helpers + hooks this package mocks.
+- [`@brendanbank/atrium-host-types`](../host-types/) — typed registry
+  shapes.
+- [`docs/published-images.md`](../../docs/published-images.md) — the
+  full host-extension contract.

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Vitest helpers for unit-testing atrium host bundles.
+ *
+ * Atrium loads a host bundle by setting ``window.__ATRIUM_REGISTRY__``
+ * and ``window.React`` and then ``await import()``-ing the bundle.
+ * Hosts that test components touching that surface have to fake the
+ * registry by hand — most casa tests today reach for Playwright
+ * instead, which is much slower and more brittle.
+ *
+ * This package installs the fakes once per test:
+ *
+ *  - ``mockAtriumRegistry({ me })`` — installs a recording fake on
+ *    ``window.__ATRIUM_REGISTRY__``, mirrors atrium's
+ *    ``subscribeEvent`` semantics with an in-memory bus, exposes
+ *    React via ``window.React`` (re-using the host's copy — atrium
+ *    uses a single shared React in production), and stubs
+ *    ``window.__atrium_i18n__`` so ``__atrium_t__`` calls resolve
+ *    against an English fallback bundle. Returns handles so the test
+ *    can assert against what the import-time side-effects registered.
+ *  - ``renderWithAtrium(ui)`` — wraps ``@testing-library/react``'s
+ *    ``render`` with a fresh ``QueryClient`` + ``<AtriumProvider>``
+ *    pre-wired to return the configured ``me``. Returns the standard
+ *    ``RenderResult`` so existing assertions work unchanged.
+ *  - ``fireAtriumEvent(kind, payload)`` — dispatches a synthetic
+ *    event the same way atrium's SSE stream would. Subscribers
+ *    registered via the fake registry's ``subscribeEvent`` see it.
+ *
+ * Peer deps only — vitest, @testing-library/react, react,
+ * @tanstack/react-query are the host's, not bundled. The package
+ * provides the seam, not the framework.
+ */
+import { type ComponentType, type ReactElement, type ReactNode } from 'react';
+import { QueryClient } from '@tanstack/react-query';
+import { type RenderOptions, type RenderResult } from '@testing-library/react';
+import { type UserContext } from '@brendanbank/atrium-host-bundle-utils/react';
+import type { AdminTab, AtriumEvent, AtriumEventHandler, AtriumRegistry, HomeWidget, LocaleOverlay, NavItem, NotificationKindRenderer, ProfileItem, RouteEntry } from '@brendanbank/atrium-host-types';
+export type { AdminTab, AtriumEvent, AtriumEventHandler, AtriumRegistry, HomeWidget, LocaleOverlay, NavItem, NotificationKindRenderer, ProfileItem, RouteEntry, UserContext, };
+/** Dispatch an atrium SSE-style event to every handler the host
+ *  subscribed via the fake registry. No-op when called outside a
+ *  ``mockAtriumRegistry`` scope so a test that forgets to call
+ *  ``mockAtriumRegistry`` first surfaces as an empty assertion rather
+ *  than a TypeError. */
+export declare function fireAtriumEvent(kind: string, payload: Record<string, unknown>): void;
+/** Recorded registrations + reset/cleanup hooks returned by
+ *  ``mockAtriumRegistry``. Tests assert against the array fields and
+ *  call ``cleanup()`` from ``afterEach`` to drop the
+ *  window globals back to their pre-mock state. */
+export interface MockAtriumHandles {
+    /** The fake registry installed on ``window.__ATRIUM_REGISTRY__``.
+     *  Test bodies that want to call register methods directly (instead
+     *  of through a host bundle's import-time side-effects) reach for
+     *  this. */
+    registry: AtriumRegistry;
+    homeWidgets: HomeWidget[];
+    routes: RouteEntry[];
+    navItems: NavItem[];
+    adminTabs: AdminTab[];
+    profileItems: ProfileItem[];
+    notificationKinds: NotificationKindRenderer[];
+    localeOverlays: LocaleOverlay[];
+    /** Drop every recorded registration + every event subscriber.
+     *  Useful between tests inside the same ``describe`` that want to
+     *  share the rest of the mock context. */
+    reset(): void;
+    /** Restore the pre-mock window state. Call from ``afterEach`` so
+     *  the next test's ``mockAtriumRegistry`` starts from a clean
+     *  baseline. */
+    cleanup(): void;
+}
+export interface MockAtriumOptions {
+    /** What ``useMe()`` resolves to. Pass ``null`` to simulate a
+     *  signed-out user (atrium responded 401/403). Defaults to
+     *  ``null``. */
+    me?: UserContext | null;
+    /** Locale resources the fake ``__atrium_t__`` resolves against.
+     *  Keys are flat dot-paths (``'common.save'``); the outer key is
+     *  the locale code. Defaults to a minimal English bundle covering
+     *  the keys atrium ships in ``common.*``. Pass an empty object to
+     *  exercise the missing-key fallback. */
+    i18n?: {
+        resources?: Record<string, Record<string, string>>;
+        language?: string;
+    };
+}
+/** Install a recording fake registry on ``window`` for the duration of
+ *  a test. The handles returned record every register* call so tests
+ *  can assert that a host bundle wired up the slots it claims to.
+ *
+ *  ```ts
+ *  let handles: MockAtriumHandles;
+ *  beforeEach(() => {
+ *    handles = mockAtriumRegistry({
+ *      me: {
+ *        id: 1, email: 'alice@example.com', full_name: 'Alice',
+ *        is_active: true, roles: ['admin'],
+ *        permissions: ['hello.toggle'], impersonating_from: null,
+ *      },
+ *    });
+ *  });
+ *  afterEach(() => handles.cleanup());
+ *
+ *  test('host bundle registers a home widget', async () => {
+ *    await import('../src/main');
+ *    expect(handles.homeWidgets).toHaveLength(1);
+ *    expect(handles.homeWidgets[0].key).toBe('hello-world');
+ *  });
+ *  ```
+ *
+ *  Side effects:
+ *   - ``window.__ATRIUM_REGISTRY__`` is replaced with the fake.
+ *   - ``window.React`` is set to the package's React copy so
+ *     ``makeWrapperElement(...)`` calls resolve. Tests that need a
+ *     specific React identity can override after the call.
+ *   - ``window.__atrium_i18n__`` is set to a fake i18n with the
+ *     bundled English ``common.*`` strings (override via the
+ *     ``i18n`` option). */
+export declare function mockAtriumRegistry(options?: MockAtriumOptions): MockAtriumHandles;
+export interface RenderWithAtriumOptions extends RenderOptions {
+    /** Override ``me`` for this single render. Useful for
+     *  parameterised tests that vary the signed-in user without
+     *  re-installing the registry. Falls back to the value from
+     *  ``mockAtriumRegistry({ me })``. */
+    me?: UserContext | null;
+    /** Provide your own QueryClient — useful if the test asserts
+     *  against cached data or invalidations. Defaults to a fresh client
+     *  with retries disabled so a 401 surfaces immediately. */
+    queryClient?: QueryClient;
+    /** Wrap children in additional providers (MantineProvider,
+     *  RouterProvider, etc.). Default: identity. */
+    wrap?: ComponentType<{
+        children: ReactNode;
+    }>;
+}
+/** ``@testing-library/react``'s ``render`` pre-wired with a fresh
+ *  QueryClient and ``<AtriumProvider>`` pointed at the configured
+ *  ``me``. Returns the standard ``RenderResult`` so existing
+ *  assertions (``getByRole``, ``rerender``, ``unmount``) work
+ *  unchanged.
+ *
+ *  ```tsx
+ *  test('owners see the per-agent picker', () => {
+ *    const { getByLabelText } = renderWithAtrium(<CommissionsPage />);
+ *    expect(getByLabelText('Agent')).toBeInTheDocument();
+ *  });
+ *  ```
+ *
+ *  Pass ``me`` to override the value from ``mockAtriumRegistry`` for
+ *  a single render — handy in parameterised tests. Pass
+ *  ``queryClient`` to share a client across renders so cache
+ *  assertions survive the second mount. */
+export declare function renderWithAtrium(ui: ReactElement, options?: RenderWithAtriumOptions): RenderResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,EACL,WAAW,EAEZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAU,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEvF,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,6CAA6C,CAAC;AACrD,OAAO,KAAK,EACV,QAAQ,EACR,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,aAAa,EACb,OAAO,EACP,wBAAwB,EACxB,WAAW,EACX,UAAU,EACX,MAAM,gCAAgC,CAAC;AAExC,YAAY,EACV,QAAQ,EACR,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,aAAa,EACb,OAAO,EACP,wBAAwB,EACxB,WAAW,EACX,UAAU,EACV,WAAW,GACZ,CAAC;AAsDF;;;;wBAIwB;AACxB,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAWN;AAMD;;;mDAGmD;AACnD,MAAM,WAAW,iBAAiB;IAChC;;;gBAGY;IACZ,QAAQ,EAAE,cAAc,CAAC;IACzB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,iBAAiB,EAAE,wBAAwB,EAAE,CAAC;IAC9C,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC;;8CAE0C;IAC1C,KAAK,IAAI,IAAI,CAAC;IACd;;oBAEgB;IAChB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC;;oBAEgB;IAChB,EAAE,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACxB;;;;6CAIyC;IACzC,IAAI,CAAC,EAAE;QACL,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AA8DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BA+B2B;AAC3B,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,iBAAsB,GAC9B,iBAAiB,CAqEnB;AAQD,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D;;;0CAGsC;IACtC,EAAE,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACxB;;+DAE2D;IAC3D,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;oDACgD;IAChD,IAAI,CAAC,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;CAC/C;AAQD;;;;;;;;;;;;;;;;2CAgB2C;AAC3C,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,YAAY,EAChB,OAAO,GAAE,uBAA4B,GACpC,YAAY,CAgBd"}

package/dist/index.js

@@ -0,0 +1,265 @@
+// Copyright (c) 2026 Brendan Bank
+// SPDX-License-Identifier: BSD-2-Clause
+/**
+ * Vitest helpers for unit-testing atrium host bundles.
+ *
+ * Atrium loads a host bundle by setting ``window.__ATRIUM_REGISTRY__``
+ * and ``window.React`` and then ``await import()``-ing the bundle.
+ * Hosts that test components touching that surface have to fake the
+ * registry by hand — most casa tests today reach for Playwright
+ * instead, which is much slower and more brittle.
+ *
+ * This package installs the fakes once per test:
+ *
+ *  - ``mockAtriumRegistry({ me })`` — installs a recording fake on
+ *    ``window.__ATRIUM_REGISTRY__``, mirrors atrium's
+ *    ``subscribeEvent`` semantics with an in-memory bus, exposes
+ *    React via ``window.React`` (re-using the host's copy — atrium
+ *    uses a single shared React in production), and stubs
+ *    ``window.__atrium_i18n__`` so ``__atrium_t__`` calls resolve
+ *    against an English fallback bundle. Returns handles so the test
+ *    can assert against what the import-time side-effects registered.
+ *  - ``renderWithAtrium(ui)`` — wraps ``@testing-library/react``'s
+ *    ``render`` with a fresh ``QueryClient`` + ``<AtriumProvider>``
+ *    pre-wired to return the configured ``me``. Returns the standard
+ *    ``RenderResult`` so existing assertions work unchanged.
+ *  - ``fireAtriumEvent(kind, payload)`` — dispatches a synthetic
+ *    event the same way atrium's SSE stream would. Subscribers
+ *    registered via the fake registry's ``subscribeEvent`` see it.
+ *
+ * Peer deps only — vitest, @testing-library/react, react,
+ * @tanstack/react-query are the host's, not bundled. The package
+ * provides the seam, not the framework.
+ */
+import { createElement, } from 'react';
+import * as ReactNS from 'react';
+import { QueryClient, QueryClientProvider, } from '@tanstack/react-query';
+import { render } from '@testing-library/react';
+import { AtriumProvider, } from '@brendanbank/atrium-host-bundle-utils/react';
+function makeFakeI18n(resources, language) {
+    return {
+        language,
+        t(key, options) {
+            const langs = [language, 'en'];
+            for (const l of langs) {
+                const hit = resources[l]?.[key];
+                if (typeof hit === 'string') {
+                    return interpolate(hit, options);
+                }
+            }
+            const def = options?.defaultValue;
+            return typeof def === 'string' ? def : key;
+        },
+    };
+}
+function interpolate(s, vars) {
+    if (!vars)
+        return s;
+    return s.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+        if (key === 'defaultValue')
+            return match;
+        const v = vars[key];
+        return v == null ? match : String(v);
+    });
+}
+let activeSubscribers = null;
+/** Dispatch an atrium SSE-style event to every handler the host
+ *  subscribed via the fake registry. No-op when called outside a
+ *  ``mockAtriumRegistry`` scope so a test that forgets to call
+ *  ``mockAtriumRegistry`` first surfaces as an empty assertion rather
+ *  than a TypeError. */
+export function fireAtriumEvent(kind, payload) {
+    const subs = activeSubscribers;
+    if (!subs)
+        return;
+    const handlers = subs.get(kind);
+    if (!handlers || handlers.size === 0)
+        return;
+    const event = { kind, payload };
+    // Snapshot so a handler that unsubscribes mid-fire doesn't skip a
+    // sibling handler that's later in iteration order.
+    for (const handler of [...handlers]) {
+        handler(event);
+    }
+}
+const DEFAULT_I18N_EN = {
+    'common.save': 'Save',
+    'common.cancel': 'Cancel',
+    'common.delete': 'Delete',
+    'common.edit': 'Edit',
+    'common.new': 'New',
+    'common.close': 'Close',
+    'common.confirm': 'Confirm',
+    'common.back': 'Back',
+    'common.loading': 'Loading…',
+    'common.empty': 'Nothing here yet.',
+    'common.error': 'Something went wrong.',
+    'common.search': 'Search',
+    'common.required': 'Required',
+    'common.language': 'Language',
+};
+function buildFakeRegistry(handles, subs) {
+    return {
+        registerHomeWidget(widget) {
+            handles.homeWidgets.push(widget);
+        },
+        registerRoute(route) {
+            handles.routes.push(route);
+        },
+        registerNavItem(item) {
+            handles.navItems.push(item);
+        },
+        registerAdminTab(tab) {
+            handles.adminTabs.push(tab);
+        },
+        registerProfileItem(item) {
+            handles.profileItems.push(item);
+        },
+        registerNotificationKind(renderer) {
+            handles.notificationKinds.push(renderer);
+        },
+        registerLocale(overlay) {
+            handles.localeOverlays.push(overlay);
+        },
+        subscribeEvent(kind, handler) {
+            let set = subs.get(kind);
+            if (!set) {
+                set = new Set();
+                subs.set(kind, set);
+            }
+            set.add(handler);
+            return () => {
+                set?.delete(handler);
+            };
+        },
+    };
+}
+/** Install a recording fake registry on ``window`` for the duration of
+ *  a test. The handles returned record every register* call so tests
+ *  can assert that a host bundle wired up the slots it claims to.
+ *
+ *  ```ts
+ *  let handles: MockAtriumHandles;
+ *  beforeEach(() => {
+ *    handles = mockAtriumRegistry({
+ *      me: {
+ *        id: 1, email: 'alice@example.com', full_name: 'Alice',
+ *        is_active: true, roles: ['admin'],
+ *        permissions: ['hello.toggle'], impersonating_from: null,
+ *      },
+ *    });
+ *  });
+ *  afterEach(() => handles.cleanup());
+ *
+ *  test('host bundle registers a home widget', async () => {
+ *    await import('../src/main');
+ *    expect(handles.homeWidgets).toHaveLength(1);
+ *    expect(handles.homeWidgets[0].key).toBe('hello-world');
+ *  });
+ *  ```
+ *
+ *  Side effects:
+ *   - ``window.__ATRIUM_REGISTRY__`` is replaced with the fake.
+ *   - ``window.React`` is set to the package's React copy so
+ *     ``makeWrapperElement(...)`` calls resolve. Tests that need a
+ *     specific React identity can override after the call.
+ *   - ``window.__atrium_i18n__`` is set to a fake i18n with the
+ *     bundled English ``common.*`` strings (override via the
+ *     ``i18n`` option). */
+export function mockAtriumRegistry(options = {}) {
+    if (typeof window === 'undefined') {
+        throw new Error('[atrium-test-utils] mockAtriumRegistry requires a jsdom-style ' +
+            'window — set vitest.environment to "jsdom" in vitest.config.ts');
+    }
+    const w = window;
+    const saved = {
+        registry: w.__ATRIUM_REGISTRY__,
+        React: w.React,
+        i18n: w.__atrium_i18n__,
+    };
+    const subs = new Map();
+    const handles = {
+        registry: undefined,
+        homeWidgets: [],
+        routes: [],
+        navItems: [],
+        adminTabs: [],
+        profileItems: [],
+        notificationKinds: [],
+        localeOverlays: [],
+        reset() {
+            handles.homeWidgets.length = 0;
+            handles.routes.length = 0;
+            handles.navItems.length = 0;
+            handles.adminTabs.length = 0;
+            handles.profileItems.length = 0;
+            handles.notificationKinds.length = 0;
+            handles.localeOverlays.length = 0;
+            subs.clear();
+        },
+        cleanup() {
+            w.__ATRIUM_REGISTRY__ = saved.registry;
+            w.React = saved.React;
+            w.__atrium_i18n__ = saved.i18n;
+            if (activeSubscribers === subs) {
+                activeSubscribers = null;
+            }
+            subs.clear();
+        },
+    };
+    handles.registry = buildFakeRegistry(handles, subs);
+    w.__ATRIUM_REGISTRY__ = handles.registry;
+    w.React = ReactNS;
+    const i18nResources = options.i18n?.resources ?? { en: DEFAULT_I18N_EN };
+    const language = options.i18n?.language ?? 'en';
+    w.__atrium_i18n__ = makeFakeI18n(i18nResources, language);
+    // Stash the configured ``me`` on a module-level slot so
+    // ``renderWithAtrium`` can pass it through to AtriumProvider's
+    // ``fetchUserContext`` override without each call site re-passing
+    // it. Cleared by ``cleanup()`` via the activeSubscribers reset.
+    configuredMe = options.me ?? null;
+    activeSubscribers = subs;
+    return handles;
+}
+// ---------------------------------------------------------------------------
+// renderWithAtrium
+// ---------------------------------------------------------------------------
+let configuredMe = null;
+function makeTestQueryClient() {
+    return new QueryClient({
+        defaultOptions: { queries: { retry: false } },
+    });
+}
+/** ``@testing-library/react``'s ``render`` pre-wired with a fresh
+ *  QueryClient and ``<AtriumProvider>`` pointed at the configured
+ *  ``me``. Returns the standard ``RenderResult`` so existing
+ *  assertions (``getByRole``, ``rerender``, ``unmount``) work
+ *  unchanged.
+ *
+ *  ```tsx
+ *  test('owners see the per-agent picker', () => {
+ *    const { getByLabelText } = renderWithAtrium(<CommissionsPage />);
+ *    expect(getByLabelText('Agent')).toBeInTheDocument();
+ *  });
+ *  ```
+ *
+ *  Pass ``me`` to override the value from ``mockAtriumRegistry`` for
+ *  a single render — handy in parameterised tests. Pass
+ *  ``queryClient`` to share a client across renders so cache
+ *  assertions survive the second mount. */
+export function renderWithAtrium(ui, options = {}) {
+    const { me, queryClient, wrap, ...rest } = options;
+    const client = queryClient ?? makeTestQueryClient();
+    const meValue = me === undefined ? configuredMe : me;
+    const Wrap = wrap;
+    function Wrapper({ children }) {
+        const inner = createElement(AtriumProvider, {
+            fetchUserContext: async () => meValue,
+            children,
+        });
+        const wrapped = Wrap ? createElement(Wrap, { children: inner }) : inner;
+        return createElement(QueryClientProvider, { client, children: wrapped });
+    }
+    return render(ui, { wrapper: Wrapper, ...rest });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@brendanbank/atrium-test-utils",
+  "version": "0.15.0",
+  "description": "Vitest helpers for unit-testing atrium host bundles. Installs a fake __ATRIUM_REGISTRY__ + window.React, wires a working QueryClient, and exposes a synthetic event bus that mirrors atrium's subscribeEvent semantics — so a host can render permission-gated components and fire SSE events from a test without standing up the SPA.",
+  "license": "BSD-2-Clause",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@brendanbank/atrium-host-bundle-utils": "0.15.0",
+    "@brendanbank/atrium-host-types": "0.15.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "@testing-library/react": "^16.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "vitest": "^1.0.0 || ^2.0.0 || ^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.100.5",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^29.0.2",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brendanbank/atrium.git",
+    "directory": "packages/test-utils"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}