@zerotal/testing 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -8,6 +8,50 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.11.0] — 2026-08-31
+
+### Changed
+
+- **`assertRedirect` compares the path exactly**, where it used to use `includes()`.
+  The loose form made the assertion mean less than it looks like it means:
+  `assertRedirect("/login")` was satisfied by `/login-as-someone-else` and by
+  `/admin?next=/login` — the two cases a test about a login redirect exists to rule
+  out. An absolute `Location` still matches a relative expectation, and naming a query
+  string compares that too. `assertRedirectContains()` is the old behaviour, for the
+  cases that want it (a signed URL with an unpredictable token).
+
+### Documented
+
+- **How to authenticate a test when identity is not a row.** `withSession()` already
+  did it, and an app with no users table — an IMAP login _is_ the identity — reached
+  past it to the session driver instead, guessing `driver.write()`. Reaching for the
+  driver is the wrong layer and does not work; the doc now says so and shows the form
+  that does.
+
+## [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

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
@@ -196,6 +197,7 @@ class TestResponse = {
   assertNotFound: () => TestResponse
   assertOk: () => TestResponse
   assertRedirect: (url: string) => TestResponse
+  assertRedirectContains: (fragment: string) => TestResponse
   assertSee: (needle: string) => TestResponse
   assertSeeText: (needle: string) => TestResponse
   assertServerError: () => TestResponse
@@ -261,16 +263,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 +344,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.9.0",
+  "version": "1.11.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -32,14 +32,14 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.9.0",
-    "@zerotal/orm": "1.9.0",
-    "@zerotal/queue": "1.9.0",
-    "@zerotal/notifications": "1.9.0"
+    "@zerotal/core": "1.11.0",
+    "@zerotal/orm": "1.11.0",
+    "@zerotal/queue": "1.11.0",
+    "@zerotal/notifications": "1.11.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/session": "1.9.0"
+    "@zerotal/session": "1.11.0"
   },
   "description": "Testing utilities for Zerotal — an in-process test app, HTTP helpers, and database refresh.",
   "keywords": [

package/src/TestResponse.ts

@@ -179,17 +179,124 @@ export class TestResponse {
     return this;
   }
 
-  /** Assert the response is a redirect to `url`. */
+  /**
+   * Assert the response is a redirect to `url`.
+   *
+   * The comparison is on the `Location` header's **path**, exactly. A substring
+   * match — which this used to do — makes the assertion mean less than it looks
+   * like it means: `assertRedirect("/login")` was satisfied by
+   * `/login-as-someone-else` and by `/admin?next=/login`, so a redirect to the
+   * wrong place passed a test written to catch exactly that.
+   *
+   * A `url` carrying a query string or a fragment is compared whole, so you can
+   * still pin one when it matters. For anything looser, use
+   * {@link assertRedirectContains}.
+   *
+   * @param url - Expected `Location`, or just its path.
+   */
   assertRedirect(url: string): this {
+    const location = this._assertIsRedirect();
+
+    // Compare paths unless the expectation names a query or a fragment — an
+    // absolute `Location` and a relative expectation are the same redirect.
+    const wantsMore = url.includes("?") || url.includes("#");
+    const actual = wantsMore ? _withoutOrigin(location) : _pathOf(location);
+    const expected = wantsMore ? _withoutOrigin(url) : _pathOf(url);
+
+    if (actual !== expected) {
+      throw new Error(
+        this._decorate(
+          `Expected redirect to "${url}" but Location was "${location}".` +
+            (location.includes(url)
+              ? `\n  (It contains the expected value but is not equal to it. ` +
+                `Use assertRedirectContains() if that is what you meant.)`
+              : ""),
+        ),
+      );
+    }
+    return this;
+  }
+
+  /**
+   * Assert the response is a redirect whose `Location` *contains* `fragment`.
+   *
+   * The old behaviour of {@link assertRedirect}, kept for the cases where it is
+   * genuinely what you want — a signed URL with an unpredictable token, say.
+   *
+   * @param fragment - Substring the `Location` must contain.
+   */
+  assertRedirectContains(fragment: string): this {
+    const location = this._assertIsRedirect();
+    if (!location.includes(fragment)) {
+      throw new Error(
+        this._decorate(
+          `Expected redirect containing "${fragment}" but Location was "${location}".`,
+        ),
+      );
+    }
+    return this;
+  }
+
+  /** The `Location` of a response that is a redirect, or a failure saying it is not. */
+  private _assertIsRedirect(): string {
     if (this._res.status < 300 || this._res.status > 399) {
       throw new Error(
         this._decorate(`Expected a redirect but got HTTP ${this._res.status}.`, { body: true }),
       );
     }
-    const location = this._res.headers.get("Location") ?? "";
-    if (!location.includes(url)) {
+    return this._res.headers.get("Location") ?? "";
+  }
+
+  /**
+   * 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 redirect to "${url}" but Location was "${location}".`),
+        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;
@@ -951,3 +1058,27 @@ function _indent(text: string): string {
     .map((line) => `    ${line}`)
     .join("\n");
 }
+
+/**
+ * A URL's path, so an absolute `Location` and a relative expectation compare equal.
+ *
+ * A redirect to `https://app.test/dashboard` and an expectation of `/dashboard` are
+ * the same redirect, and a test should not have to know which form the handler used.
+ */
+function _pathOf(url: string): string {
+  try {
+    return new URL(url, "http://localhost").pathname;
+  } catch {
+    return url;
+  }
+}
+
+/** A URL without its origin — path, query and fragment — for an exact comparison. */
+function _withoutOrigin(url: string): string {
+  try {
+    const parsed = new URL(url, "http://localhost");
+    return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  } catch {
+    return url;
+  }
+}

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 {