@zerotal/testing 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -8,6 +8,26 @@ 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

package/api-surface.md

@@ -197,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/testing",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -32,14 +32,14 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.10.0",
-    "@zerotal/orm": "1.10.0",
-    "@zerotal/queue": "1.10.0",
-    "@zerotal/notifications": "1.10.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.10.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,22 +179,74 @@ 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 {
-    if (this._res.status < 300 || this._res.status > 399) {
+    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 a redirect but got HTTP ${this._res.status}.`, { body: true }),
+        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.)`
+              : ""),
+        ),
       );
     }
-    const location = this._res.headers.get("Location") ?? "";
-    if (!location.includes(url)) {
+    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 to "${url}" but Location was "${location}".`),
+        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 }),
+      );
+    }
+    return this._res.headers.get("Location") ?? "";
+  }
+
   /**
    * Assert the response is a redirect a browser running Inertia will actually follow.
    *
@@ -1006,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;
+  }
+}