@zerotal/testing 1.7.4 → 1.8.0

package/api-surface.md

@@ -302,8 +302,12 @@ class BrowserPage = {
   connection: () => Promise<string | null>
   count: (selector: string) => Promise<number>
   evaluate: <T = unknown>(expression: string) => Promise<T>
+  horizontalOverflow: () => Promise<number>
   html: (selector: string) => Promise<string | null>
+  overflowTrace: (selector: string) => Promise<string[]>
+  overflowingElements: (limit?: number) => Promise<string[]>
   press: (key: string) => Promise<BrowserPage>
+  resize: (width: number, height: number) => Promise<BrowserPage>
   socketUpgraded: () => boolean
   text: (selector: string) => Promise<string | null>
   transport: () => TransportReport

package/package.json

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

package/src/browser/FlowBrowser.ts

@@ -1,6 +1,7 @@
 import { createTestApp, type TestApp } from "../TestApp.ts";
 import { backendOption, browserAvailability } from "./chrome.ts";
 import type { Application } from "@zerotal/core";
+import { Router } from "@zerotal/core";
 
 /**
  * Read a CDP event's params.
@@ -88,6 +89,96 @@ export class BrowserPage {
     return this._view.evaluate<T>(expression);
   }
 
+  /**
+   * Resize the viewport, for the failures that only exist at a particular width.
+   *
+   * Horizontal overflow is the obvious one: a page can be flawless at 1280 and
+   * scroll sideways at 375 because one element inside a `not-prose` block has no
+   * width constraint. Nothing server-side can see it, and neither can a browser
+   * test that never leaves the default window size.
+   */
+  async resize(width: number, height: number): Promise<this> {
+    this._assertOpen();
+    await this._view.resize(width, height);
+    return this;
+  }
+
+  /**
+   * How far the document can scroll sideways beyond the viewport, in pixels.
+   *
+   * `0` is the only healthy answer. `documentElement.scrollWidth` rather than
+   * `body`'s, because an overflowing child can push the scrollable area wider
+   * than the body box without the body itself ever being wide.
+   */
+  async horizontalOverflow(): Promise<number> {
+    return this.evaluate<number>(
+      "Math.max(0, document.documentElement.scrollWidth - window.innerWidth)",
+    );
+  }
+
+  /**
+   * The elements sticking out past the right edge, widest first.
+   *
+   * A number alone says a page overflows by 204 pixels and leaves whoever reads
+   * the failure to work out by what — which on a page of six thousand nodes is
+   * the whole of the job. This names them.
+   */
+  async overflowingElements(limit = 5): Promise<string[]> {
+    return this.evaluate<string[]>(
+      "(() => {" +
+        "const edge = window.innerWidth; const out = [];" +
+        'for (const el of document.querySelectorAll("body *")) {' +
+        "const r = el.getBoundingClientRect();" +
+        "if (r.right <= edge + 1 || r.width === 0) continue;" +
+        'const id = el.id ? "#" + el.id : "";' +
+        'const cls = typeof el.className === "string" && el.className' +
+        ' ? "." + el.className.trim().split(" ").filter(Boolean).slice(0, 3).join(".") : "";' +
+        "out.push({ s: el.tagName.toLowerCase() + id + cls, o: Math.round(r.right - edge) });" +
+        "}" +
+        "return out.sort((a, b) => b.o - a.o).slice(0, " +
+        limit +
+        ")" +
+        '.map((e) => e.s + " (+" + e.o + "px)");' +
+        "})()",
+    );
+  }
+
+  /**
+   * Why an element overflows: its ancestors, and which of them fails to contain it.
+   *
+   * An element inside an `overflow-x: auto` box is *allowed* to measure wider than
+   * the viewport — the box scrolls and the page does not. So "this element sticks
+   * out" is not yet a bug report; the question is which ancestor was supposed to
+   * clip it and did not, which is what this walks up and answers.
+   */
+  async overflowTrace(selector: string): Promise<string[]> {
+    return this.evaluate<string[]>(
+      "(() => {" +
+        "let el = document.querySelector(" +
+        quote(selector) +
+        ");" +
+        'if (!el) return ["not found: " + ' +
+        quote(selector) +
+        "];" +
+        "const out = [];" +
+        "while (el && el !== document.documentElement) {" +
+        "const cs = getComputedStyle(el);" +
+        "out.push(" +
+        "el.tagName.toLowerCase() +" +
+        '(el.id ? "#" + el.id : "") +' +
+        '" client=" + el.clientWidth +' +
+        '" scroll=" + el.scrollWidth +' +
+        '" overflowX=" + cs.overflowX +' +
+        '" minWidth=" + cs.minWidth +' +
+        '" display=" + cs.display' +
+        ");" +
+        "el = el.parentElement;" +
+        "}" +
+        "return out;" +
+        "})()",
+    );
+  }
+
   /** `textContent` of the first match, trimmed. `null` when nothing matches. */
   async text(selector: string): Promise<string | null> {
     return this.evaluate<string | null>(
@@ -323,12 +414,35 @@ export class FlowBrowser {
     // `boot()`, inside `start()`. So a `setup` that calls `Router.flow(...)`
     // would find it undefined. `boot()` is idempotent and `start()` skips it
     // when already booted, so pulling it forward changes only the ordering.
-    const app = await createTestApp(async () => {
-      const application = await bootstrap();
-      application.adoptAsCurrent();
-      await application.boot();
-      return application;
-    }, options.setup);
+    const app = await createTestApp(
+      async () => {
+        const application = await bootstrap();
+        application.adoptAsCurrent();
+        await application.boot();
+        return application;
+      },
+      () => {
+        // Serve `public/`, which the framework mounts only for the `web`
+        // environment — and a test app is not one.
+        //
+        // Without this a browser suite drives an unstyled site: the stylesheet is
+        // built and present on disk and simply never served, so every `<pre>`
+        // loses its `overflow-x: auto` and the pages scroll sideways. A layout
+        // assertion then measures a page no user will ever see. It cost four CI
+        // round trips to find, because `zt serve` runs as `web` and every local
+        // reproduction served the file correctly.
+        //
+        // Registered before the caller's own `setup`, so a suite can still
+        // override the mount if it means to.
+        // `process.cwd()`, matching what the framework's own `_bootConventions`
+        // does — which means a suite invoked from the repo root rather than from
+        // the app directory mounts a `public/` that is not there, and every page
+        // arrives unstyled. It fails as a layout assertion rather than as a
+        // missing file, so it is worth knowing before spending an hour on it.
+        Router.static("/", `${process.cwd()}/public`);
+        options.setup?.();
+      },
+    );
     return new FlowBrowser(app, options.timeout ?? DEFAULT_TIMEOUT);
   }