@zerotal/testing 1.8.1 → 1.10.0

package/CHANGELOG.md

@@ -8,6 +8,40 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.10.0] — 2026-08-30
+
+### Added
+
+- **`res.assertInertiaRedirect(url)`** — the assertion that pins what actually breaks.
+  A redirect with the right status and the right `Location` and no `X-Inertia: true`
+  is ignored by the Inertia client: the request succeeds, the row is written, and the
+  form sits there with its fields still filled in. `assertRedirect` checks the two
+  headers that were never wrong, so an app can write three tests for this and have
+  them pass whether or not its own workaround middleware is installed — which is how
+  a workaround becomes permanent. This checks the redirect status (303 by default,
+  because that is what a form submit must get), the `Location`, and the marker.
+
+- **`@zerotal/testing/preload` warns when the runtime is below the project's
+  `engines.bun`.** `startZerotal()` refuses on the same condition, which covers every
+  `zt` command — but not `bun test` typed straight into a shell, and that is the case
+  worth catching: the shell's Bun and the project's can differ, and the difference
+  arrives as a handful of `Intl` assertions going red with nothing naming a binary.
+  A parent-process check cannot see this; only an assertion from inside the process
+  the tests run in can, which is what a preload is.
+
+  A warning rather than a refusal, because a preload that throws takes down the whole
+  run and a suite that is merely _suspect_ should still produce its results.
+
+## [1.9.0] — 2026-08-29
+
+### Documented
+
+- **Every promised export is documented.** The `docs-coverage` gate reads `maturity: stable` as a
+  promise about a package's exports, and measures how much of that promise is written down. It
+  was 798 gaps across the suite; it is now zero. This package's share is covered on its own
+  pages — types named, options shapes described, and the decisions behind them recorded where
+  somebody looking for them will find them.
+
 ## [1.5.0] — 2026-08-15
 
 ### Added

package/api-surface.md

@@ -187,6 +187,7 @@ class TestResponse = {
   assertHeaderMissing: (name: string) => TestResponse
   assertInertia: (component?: string, props?: Record<string, unknown>) => TestResponse
   assertInertiaProp: (key: string, value?: unknown) => TestResponse
+  assertInertiaRedirect: (url: string, status?: number) => TestResponse
   assertInvalid: (fields?: string | string[] | Record<string, string>) => TestResponse
   assertJson: (expected: Record<string, unknown>) => TestResponse
   assertJsonCount: (count: number, key?: string) => TestResponse
@@ -261,16 +262,16 @@ interface InertiaPage = {
 }
 
 interface MigrateDatabaseOptions = {
-  connection?: SQLInstance
-  path?: string
-  table?: string
+  connection?: SQLInstance | undefined
+  path?: string | undefined
+  table?: string | undefined
 }
 
 interface RefreshDatabaseOptions = {
-  connection?: SQLInstance
-  migrate?: string | boolean
-  setup?: (db: SQLInstance) => void | Promise<void>
-  teardown?: (db: SQLInstance) => void | Promise<void>
+  connection?: SQLInstance | undefined
+  migrate?: string | boolean | undefined
+  setup?: ((db: SQLInstance) => void | Promise<void>) | undefined
+  teardown?: ((db: SQLInstance) => void | Promise<void>) | undefined
 }
 
 interface TestFileInput = {
@@ -342,8 +343,8 @@ interface BrowserAvailability = {
 }
 
 interface FlowBrowserOptions = {
-  setup?: () => void
-  timeout?: number
+  setup?: (() => void) | undefined
+  timeout?: number | undefined
 }
 
 interface ObservedFrame = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/testing",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -32,14 +32,14 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.8.1",
-    "@zerotal/orm": "1.8.1",
-    "@zerotal/queue": "1.8.1",
-    "@zerotal/notifications": "1.8.1"
+    "@zerotal/core": "1.10.0",
+    "@zerotal/orm": "1.10.0",
+    "@zerotal/queue": "1.10.0",
+    "@zerotal/notifications": "1.10.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/session": "1.8.1"
+    "@zerotal/session": "1.10.0"
   },
   "description": "Testing utilities for Zerotal — an in-process test app, HTTP helpers, and database refresh.",
   "keywords": [

package/src/TestResponse.ts

@@ -195,6 +195,61 @@ export class TestResponse {
     return this;
   }
 
+  /**
+   * Assert the response is a redirect a browser running Inertia will actually follow.
+   *
+   * Three things have to be true together, and `assertRedirect` checks one of them.
+   * A redirect that is correct on status and `Location` but unmarked is the failure
+   * this exists for: the request succeeds, the row is written, and the form sits
+   * there with the fields still filled in — because the Inertia client did not
+   * recognise the response as its own and never navigated. Nothing about that looks
+   * like an error from either end, which is why it is worth an assertion of its own.
+   *
+   * - **A redirect status.** After a POST/PUT/DELETE it must be `303`, not `302`:
+   *   only See Other makes the browser follow with `GET` instead of repeating the
+   *   method against the target.
+   * - **`Location`**, as `assertRedirect` checks it.
+   * - **`X-Inertia: true`**, which is the part a status-and-location assertion
+   *   cannot see and the part that was missing.
+   *
+   * Send the request with the `X-Inertia` header for this to mean anything — a
+   * redirect to a browser that is not running Inertia is just a redirect.
+   *
+   * @param url - Expected `Location` (matched as a substring, like {@link assertRedirect}).
+   * @param status - Expected status. Defaults to `303`, which is what a form submit gets.
+   *
+   * @example
+   * ```ts
+   * const res = await app.post("/orders", data, { headers: { "X-Inertia": "true" } });
+   * res.assertInertiaRedirect("/orders/1");
+   * ```
+   */
+  assertInertiaRedirect(url: string, status = 303): this {
+    this.assertRedirect(url);
+    if (this._res.status !== status) {
+      throw new Error(
+        this._decorate(
+          `Expected an Inertia redirect with HTTP ${status} but got ${this._res.status}. ` +
+            (status === 303 && this._res.status === 302
+              ? "A 302 after a non-GET makes the browser repeat the method against the target."
+              : ""),
+          { headers: true },
+        ),
+      );
+    }
+    if (this._res.headers.get("X-Inertia") !== "true") {
+      throw new Error(
+        this._decorate(
+          `Expected the redirect to carry X-Inertia: true, but it did not. The Inertia ` +
+            `client ignores a redirect it does not recognise as its own — the request ` +
+            `succeeds and the page never moves.`,
+          { headers: true },
+        ),
+      );
+    }
+    return this;
+  }
+
   // ── Header assertions ─────────────────────────────────────────────────
 
   /**

package/src/browser/FlowBrowser.ts

@@ -39,7 +39,7 @@ export interface TransportReport {
 /** Options for {@link FlowBrowser.serve}. */
 export interface FlowBrowserOptions {
   /** Milliseconds any `waitFor*` will wait before giving up. */
-  timeout?: number;
+  timeout?: number | undefined;
   /**
    * Register routes, before the server starts.
    *
@@ -48,7 +48,7 @@ export interface FlowBrowserOptions {
    * needs a fixture page — one deliberately built to reproduce a bug — registers
    * it here instead of adding it to the application under test.
    */
-  setup?: () => void;
+  setup?: (() => void) | undefined;
 }
 
 const DEFAULT_TIMEOUT = 5_000;

package/src/migrateDatabase.ts

@@ -13,11 +13,11 @@ export interface MigrateDatabaseOptions {
    * Connection to migrate. Defaults to the active model connection, which is
    * what `createTestApp()` and `refreshDatabase({ connection })` install.
    */
-  connection?: SQLInstance;
+  connection?: SQLInstance | undefined;
   /** Directory holding the migration files. Defaults to `database/migrations`. */
-  path?: string;
+  path?: string | undefined;
   /** Tracking-table name. Defaults to `migrations`. */
-  table?: string;
+  table?: string | undefined;
 }
 
 /**

package/src/preload.ts

@@ -1,5 +1,6 @@
 /**
- * @zerotal/testing/preload — auto-wires the DB connection for every test worker.
+ * @zerotal/testing/preload — auto-wires the DB connection for every test worker,
+ * and checks the runtime the tests are actually running on.
  *
  * Loaded via `bun test --preload @zerotal/testing/preload` when you run
  * `bun zt test`. Reads ZT_DB_URL from the environment (set by
@@ -8,10 +9,30 @@
  *
  * Each Bun test worker runs its own copy of this module, so connections are
  * isolated per file — no cross-file leakage.
+ *
+ * ## Why the runtime check is here and not only in `zt test`
+ *
+ * `startZerotal()` refuses to run below the project's `engines.bun`, which covers
+ * every `zt` command. It does not cover `bun test` typed straight into a shell,
+ * and that is the case worth catching: the shell's `bun` and the project's can
+ * differ, and the difference shows up as a handful of `Intl` assertions going red
+ * with nothing in the failure naming a binary. A parent-process check cannot see
+ * this — only an assertion from inside the process the tests run in can, which is
+ * what a preload is.
  */
 
 import { SQL } from "bun";
 import { _setBaseModelConnection, _setBaseModelDialect, _setDbConnection } from "@zerotal/orm";
+import { runtimeBelowFloor, runtimeBelowFloorMessage } from "@zerotal/core/runtime";
+
+// A warning rather than a refusal: a preload that throws takes down the whole run,
+// and a suite that is merely *suspect* should still produce its results — the point
+// is that the version is named at the top of the output instead of being the last
+// thing anyone thinks to check.
+const _floor = runtimeBelowFloor();
+if (_floor) {
+  console.warn(`\n⚠  ${runtimeBelowFloorMessage(_floor)}\n`);
+}
 
 const url = Bun.env["ZT_DB_URL"];
 

package/src/refreshDatabase.ts

@@ -18,16 +18,16 @@ function _hooks(): TestHooks {
 }
 
 export interface RefreshDatabaseOptions {
-  connection?: SQLInstance;
+  connection?: SQLInstance | undefined;
   /**
    * Build the schema by running the project's migrations before the suite.
    * `true` uses `database/migrations`; pass a string for a different directory.
    *
    * Prefer this over hand-written DDL in `setup` — see {@link migrateDatabase}.
    */
-  migrate?: boolean | string;
-  setup?: (db: SQLInstance) => void | Promise<void>;
-  teardown?: (db: SQLInstance) => void | Promise<void>;
+  migrate?: boolean | string | undefined;
+  setup?: ((db: SQLInstance) => void | Promise<void>) | undefined;
+  teardown?: ((db: SQLInstance) => void | Promise<void>) | undefined;
 }
 
 export function refreshDatabase(options: RefreshDatabaseOptions = {}): void {