@ultimat3/testing - npm Package Compare versions

Comparing version 13.0.0 to 14.0.0

CLAUDE.md

@@ -34,4 +34,7 @@ # @ultimat3/testing — boundary
 | Fixtures | the preload registers the whole framework bag — an app registers only what the framework cannot know (`seed`, `actorFor`) |
-| e2e without a driver | `e2eTest` becomes `test.skip`, and the gate reports the step GREEN over it — `bun test` exits 0 on a skip and the exit code is the only channel between the step and the child that registers the driver. `hasE2eDriver()` is what a harness asks instead of reading an all-skipped run as a pass. Zero drivers are registered `As of 2026-08` |
+| e2e without a driver | `e2eTest` becomes `test.skip`, and the gate reports the step GREEN over it — `bun test` exits 0 on a skip and the exit code is the only channel between the step and the child that registers the driver. `hasE2eDriver()` is what a harness asks instead of reading an all-skipped run as a pass. Zero drivers are registered BY DEFAULT and that is the design, not a gap: `@ultimat3/cli`'s `installE2eDriver()` is the one that exists (`packages/cli/src/e2e-driver.ts`), an app's test preload is what calls it, and CI has no browser |
+| The seam has an inverse, `As of 2026-08-25` | `resetE2eDriver()`. `useE2eDriver` writes MODULE scope and `bun test` is one process, so a file that installed a browser handed every later file in the run an `e2eTest` that opened a page nobody asked for — `test-types.test.ts` was itself doing it, at module scope, with nothing to undo it. Same shape and same reason as `@ultimat3/scraping`'s `resetScrapeDriver()` |
 | Built vs declared | `clock` `mail` `network` `runJobs` `statements` `subscribe` are built in-process; `page` `budget` `signIn` `deploy` are declared and wait for a driver (`X_TEST_FIXTURE_UNAVAILABLE`). The four left all need a browser or a second build — things the framework genuinely cannot bundle |
+| `page` HAS a driver now, and the other three still do not, `As of 2026-08-25` | `installE2eDriver({ page, baseUrl })` registers `page` over its declaration and leaves `budget`, `signIn` and `deploy` refusing, on purpose: byte counts come off a built `dist/`, a sign-in route is the APP's, and a new build id is a fact about the SERVER — a page port can answer for none of the three, and a fixture that silently no-opped would make the assertion after it read as proof |
+| `network` is THIS process's fetch, and an e2e page is not in this process | `sealed-network.ts` patches `globalThis.fetch` here; a browser's requests never pass through it. So `network.offline()` in a test that also destructures `page` is a **no-op on the browser** — the app's online page passing an offline test. `E2eFixtures.offline()` is the browser-side spelling and the CDP driver REFUSES it (`X_TEST_FIXTURE_UNAVAILABLE`), because `CdpPageLike` declares no `setOfflineMode`. Two words, two mechanisms, and only one of them can put a browser offline |
 | `subscribe` is a whole `sync` node | `live-node.ts` assembles what `x dev --role sync` assembles minus the listener — real `LiveQueryRegistry`, real `liveQueryDefinition` bridge, real per-subscriber gate, real cursor — over a socket that is two objects handing each other the JSON a WebSocket would. `live-replicator.ts` feeds it from `@ultimat3/entity`'s `setRowObserver`, which is the change SOURCE a test process never had: PGlite has no walsender and the memory driver no log, so `InMemoryChangeFeed` had nothing upstream of it. The WAL decoder is the only thing substituted; everything downstream of it is production code |
@@ -69,2 +72,3 @@ | What `subscribe` does NOT hold | a client store, an offline queue or a rebase log — so `feed.local()` answers `undefined` rather than the server row. A twin reported as applied whether or not a mutator ran is coverage that reads as proof, which is worse than none. That half is `useMutation` / `useMutationQueue` and an e2e |
 | An island needs a BUILDER, not an import | `buildIslands` is `@ultimat3/cli`'s and both packages are tier 5; the one declared edge is `cli → testing`, so the reverse is a `bun run boundaries` failure. `mountIsland({ build, root, file })` takes the function as a parameter and declares only the two fields it reads — `IslandChunkLike` is `{ file, code }`, so a CSS artifact, a source map or a dev/production flag the bundler grows is invisible here. Moving the bundler down a tier was the alternative and it drags `@babel/core` and `babel-preset-solid` with it, into a package whose whole point is being importable from tier 0 |
+| `mountIsland` AWAITS `mount` | `IslandEntry['mount']` returns `unknown`, not `void`, and the call is awaited — the shipped runtime chains `import(e).then((m) => m.mount(el, props))` (`packages/render/src/hydrate.ts`) and only marks the element mounted when that settles, so an `async` mount is an ordinary island and `like.island.tsx` already is one. Typed `=> void` and called bare, the fixture returned before an island that opens a queue or a socket had rendered anything, so every assertion after it read an empty wrapper — and worse, the mount RESUMED after `restore()` had taken the fake `document` back out, failing with `document is not defined` inside whichever later test happened to be running. Not a breaking change: `IslandEntry` is module-private and an island module is matched structurally off an `unknown` import, so nothing implements it. |
 | The micro-DOM is the fixture's, once **for islands** | `island-dom.ts`. **"Once" is scoped to this job, and said so only from 2026-08-23**: `packages/ui/src/fake-dom.ts` is a second micro-DOM (201 lines, test-only, off that package's barrel) for a different one — focus, `activeElement`, `contains` and a `:not()` selector grammar for keyboard code, none of which parses a `<template>`. It is not a copy to collapse: `ui` is tier 4 and this package is tier 5, so `ui -> testing` is an upward import the boundary check refuses, and the merge would need the shared half moved down to a tier neither grammar belongs in. `bun test` has no DOM and no DOM library may be added; `generate: 'dom'` builds every element from `_$template("<label …>")`, so a stub without a parsed `<template>` cannot run one line of a compiled island. It lived twice, ~200 lines each, in `packages/cli/src/island-bundle.test.ts` and the reference app's island test |
@@ -71,0 +75,0 @@ | `style` and `classList` RECORD, `As of 2026-08` | `FakeStyle` is one declaration map behind all four spellings compiled Solid uses on one element: a STATIC entry baked into the template's `style=` attribute, a dynamic one through `setStyleProperty` → `style.setProperty`, a whole-object or string prop through `style()` → `cssText`, and a cleared one through `removeAttribute`. It was `style = {}` until 2026-08-21 — `<Form>`, `<Stack>`, `<Grid>` and `<Container>` each set a CSS custom property, so every one of them died inside `mount` with `e.style.setProperty is not a function`, and `x g resource` emitted a plain `<form>` rather than the design system's. A design-system component kept out of generated code by the limits of a TEST DOUBLE. A no-op `setProperty` would have stopped the crash and left "the component set `--form-gap`" unassertable, which is the same hole one layer down |

package.json

 {
   "name": "@ultimat3/testing",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
@@ -36,14 +36,14 @@ "license": "MIT",
   "dependencies": {
-    "@ultimat3/cache": "13.0.0",
-    "@ultimat3/core": "13.0.0",
-    "@ultimat3/db": "13.0.0",
-    "@ultimat3/entity": "13.0.0",
-    "@ultimat3/i18n": "13.0.0",
-    "@ultimat3/jobs": "13.0.0",
-    "@ultimat3/mail": "13.0.0",
-    "@ultimat3/policy": "13.0.0",
-    "@ultimat3/query": "13.0.0",
-    "@ultimat3/realtime": "13.0.0",
-    "@ultimat3/time": "13.0.0"
+    "@ultimat3/cache": "14.0.0",
+    "@ultimat3/core": "14.0.0",
+    "@ultimat3/db": "14.0.0",
+    "@ultimat3/entity": "14.0.0",
+    "@ultimat3/i18n": "14.0.0",
+    "@ultimat3/jobs": "14.0.0",
+    "@ultimat3/mail": "14.0.0",
+    "@ultimat3/policy": "14.0.0",
+    "@ultimat3/query": "14.0.0",
+    "@ultimat3/realtime": "14.0.0",
+    "@ultimat3/time": "14.0.0"
   }
 }

README.md

@@ -139,5 +139,15 @@ # @ultimat3/testing
 | `jobTest` | step sequence, retries, idempotency | `job` |
-| `e2eTest` | a browser driver incl. offline mode + SW update; with none registered it SKIPS, and the gate's `e2e` step passes over the skip — ask `hasE2eDriver()` rather than reading that as a pass | `e2e` |
+| `e2eTest` | a browser driver; with none registered it SKIPS, and the gate's `e2e` step passes over the skip — ask `hasE2eDriver()` rather than reading that as a pass | `e2e` |
 | `evalTest` | LLM output scoring against a threshold | `eval` |
 
+**Registering one, `As of 2026-08-25`.** `@ultimat3/cli`'s `installE2eDriver({ page, baseUrl })` is
+the driver that exists — a `PageLike` over `@ultimat3/scraping`'s browser — and an app's test preload
+is what calls it. It returns the undo, and `resetE2eDriver()` is the seam's inverse for anything that
+installs one by hand: `bun test` is one process, so a driver left registered reaches every later file.
+
+It registers `page` and nothing else. `budget`, `signIn` and `deploy` keep refusing with
+`X_TEST_FIXTURE_UNAVAILABLE`, and so do `E2eFixtures`' `offline()` / `online()` / `update()` — the
+browser's own network state and a second build id are not things a page port can answer for, and a
+fixture that silently no-opped would make the assertion after it read as proof.
+
 Each helper prefixes the test name with its type (`job · onboards an org`), which is what
@@ -285,2 +295,8 @@ `bun test --test-name-pattern "job · "` selects — the six lines of `x verify` come from the tests
 
+**An `async` mount is awaited**, as the shipped hydration runtime awaits it — an island that opens
+a queue or a socket before its first render (`like.island.tsx` does) needs no `settle()` helper in
+the test. Until `As of 2026-08-25` the call was bare, so the fixture answered before such an island
+had rendered anything and the mount later resumed against a `document` the teardown had already
+removed.
+
 **A mount installs process-global state**, so `MountedIsland` is `Disposable` — `using`, or
@@ -287,0 +303,0 @@ `island[Symbol.dispose]()` in an `afterAll`. Left installed it hands a fake `document` to every

src/fixture-island.ts

@@ -65,4 +65,12 @@ // Build one island, import the chunk the way the hydration runtime does, and run its `mount` over
 
+/**
+ * Module-private, and its `mount` returns `unknown` rather than `void` — the shipped hydration
+ * runtime chains `import(e).then((m) => m.mount(el, props))` (`packages/render/src/hydrate.ts`),
+ * so a browser AWAITS whatever `mount` answers before it marks the element mounted. An island that
+ * opens a queue or a socket first is therefore an ordinary island (`like.island.tsx` is `async`),
+ * and a fixture typed `=> void` could only ever call it and walk away. Widening, not narrowing: an
+ * island module is matched structurally off an `unknown` import, so nothing implements this type.
+ */
 interface IslandEntry {
-  readonly mount: (el: unknown, props: unknown) => void;
+  readonly mount: (el: unknown, props: unknown) => unknown;
 }
@@ -184,3 +192,7 @@
     }
-    entry.mount(el, options.props);
+    // AWAITED, because the runtime this fixture stands in for awaits it. Left unawaited, an async
+    // island's `mount` resumed AFTER the `restore()` below had taken the fake `document` back out
+    // — so it failed with `document is not defined` inside whichever later test happened to be
+    // running, with no thread back here.
+    await entry.mount(el, options.props);
     return {
@@ -187,0 +199,0 @@ code: chunk.code,

src/index.ts

@@ -255,2 +255,3 @@ export type {
   liveTest,
+  resetE2eDriver,
   SEPARATOR,
@@ -257,0 +258,0 @@ TEST_TYPES,

src/test-types.ts

@@ -115,2 +115,12 @@ // The six first-class test types. `x verify` selects a suite by FILENAME — `*.job.test.ts`, and
 
+/**
+ * Put the seam back. The counterpart `useE2eDriver` shipped without, and the module scope it
+ * writes to is process-global: `bun test` shares one process across files, so a file that installs
+ * a browser and does not undo it hands every later file an `e2eTest` that opens a page nobody
+ * asked for. Same shape and same reason as `@ultimat3/scraping`'s `resetScrapeDriver()`.
+ */
+export const resetE2eDriver = (): void => {
+  e2eDriver = undefined;
+};
+
 export const e2eTest = (name: string, body: E2eBody): void => {
@@ -117,0 +127,0 @@ if (e2eDriver === undefined) {

No alert changes

Improved metrics

Total package byte prevSize

318357

1.63%

Lines of code

5398

0.41%

Number of lines in readme file

445

3.73%

Dependency changes

• + Added

  @ultimat3/cache@14.0.0
  (transitive)

• + Added

  @ultimat3/core@14.0.0
  (transitive)

• + Added

  @ultimat3/db@14.0.0
  (transitive)

• + Added

  @ultimat3/entity@14.0.0
  (transitive)

• + Added

  @ultimat3/http@14.0.0
  (transitive)

• + Added

  @ultimat3/i18n@14.0.0
  (transitive)

• + Added

  @ultimat3/jobs@14.0.0
  (transitive)

• + Added

  @ultimat3/mail@14.0.0
  (transitive)

• + Added

  @ultimat3/policy@14.0.0
  (transitive)

• + Added

  @ultimat3/query@14.0.0
  (transitive)

• + Added

  @ultimat3/realtime@14.0.0
  (transitive)

• + Added

  @ultimat3/schema@14.0.0
  (transitive)

• + Added

  @ultimat3/time@14.0.0
  (transitive)

• - Removed

  @ultimat3/cache@13.0.0
  (transitive)

• - Removed

  @ultimat3/core@13.0.0
  (transitive)

• - Removed

  @ultimat3/db@13.0.0
  (transitive)

• - Removed

  @ultimat3/entity@13.0.0
  (transitive)

• - Removed

  @ultimat3/http@13.0.0
  (transitive)

• - Removed

  @ultimat3/i18n@13.0.0
  (transitive)

• - Removed

  @ultimat3/jobs@13.0.0
  (transitive)

• - Removed

  @ultimat3/mail@13.0.0
  (transitive)

• - Removed

  @ultimat3/policy@13.0.0
  (transitive)

• - Removed

  @ultimat3/query@13.0.0
  (transitive)

• - Removed

  @ultimat3/realtime@13.0.0
  (transitive)

• - Removed

  @ultimat3/schema@13.0.0
  (transitive)

• - Removed

  @ultimat3/time@13.0.0
  (transitive)

• Updated

  @ultimat3/cache@14.0.0

• Updated

  @ultimat3/core@14.0.0

• Updated

  @ultimat3/db@14.0.0

• Updated

  @ultimat3/entity@14.0.0

• Updated

  @ultimat3/i18n@14.0.0

• Updated

  @ultimat3/jobs@14.0.0

• Updated

  @ultimat3/mail@14.0.0

• Updated

  @ultimat3/policy@14.0.0

• Updated

  @ultimat3/query@14.0.0

• Updated

  @ultimat3/realtime@14.0.0

• Updated

  @ultimat3/time@14.0.0