@specific.dev/spectest 0.128.0 → 0.129.0

package/README.md

@@ -24,6 +24,60 @@ work; do not replace readiness with sleeps or arbitrary `.first()` selections.
 SDK 0.123.0 uses native Playwright assertions while retaining Spectest's API and
 recording. Ambiguous single-element selectors fail immediately; make them unique.
 
+For terminal readiness, use `terminal.waitFor` directly. It retries the condition
+and throws on timeout, so neither an outer `ctx.wait` nor an extra assertion is
+needed to check that text appears:
+
+```ts
+await terminal.waitFor("Rack is initialized", /Current rack status:\s*Initialized/, {
+  timeoutMs: 35 * 60_000,
+  intervalMs: 5_000,
+  failOn: [
+    { description: "Setup was rejected", matcher: "Start Rack Setup Failed" },
+    { description: "Initialization failed", matcher: "Initialization Failed" },
+    { description: "Initialization panicked", matcher: "Initialization Panicked" },
+  ],
+});
+await terminal.press("Ctrl+C"); // Separate cleanup after the condition succeeds.
+```
+
+SDK 0.129.0 records the string/regex matcher (or identifies a custom predicate),
+timeout, and start/end positions for this wait. The dashboard shows its condition
+and outcome and replays up to the result. Later inputs belong to their own steps;
+the full terminal session can be opened separately. `ctx.wait` remains useful
+when a retry must repeat actions, rather than just observe terminal state.
+
+Terminal waits record matched, timed-out, failure-condition, predicate-error,
+process-exit and cancelled outcomes. `failOn` checks the rendered screen before
+checking success; string and regex conditions are recorded explicitly. For a
+custom predicate, provide `condition: "Expected sled has a valid bootstrap IPv6 address"`
+to explain the actual check separately from its step title. Async predicates are
+awaited, and their rejection is recorded. A final matching screen succeeds even
+if the process has exited; otherwise exit fails the wait after final output is
+drained. No `Promise.race` with `terminal.exited` is needed.
+
+Pass `signal: controller.signal` to cancel a wait without closing its terminal.
+Cancellation stops SDK polling; it cannot forcibly stop work started inside a
+custom predicate. `terminal.close({ timeoutMs: 10_000 })` cancels pending waits,
+sends EOF, escalates to a kill, and bounds cleanup including output drain. The
+default close deadline is 10 seconds; repeated calls share the same result or
+failure. `terminal.exited` records the exit when observed after completion, not
+when its promise is first read. A stalled output drain fails after 5 seconds
+instead of hanging indefinitely. Test code should preserve its original failure
+if diagnostic or cleanup operations also fail.
+
+Browser navigation accepts public Playwright-style options, without a backend
+cast or `pageOp` call:
+
+```ts
+await browser.goto(consoleUrl, { timeout: 120_000, waitUntil: "domcontentloaded" });
+await browser.reload({ timeout: 120_000 });
+```
+
+These options also apply to `goBack` and `goForward`. Navigation deadlines do not
+cancel a surrounding `ctx.poll`, and retrying a navigation after a visible error
+is a recovery action that should remain visible in the test results.
+
 Pub/Sub integrations are project-owned as of SDK 0.98.0. The former
 `pubsub`/`pubsubClient` exports and `/components/gcp` entry point are removed.
 Use a local service definition or `serviceGroup()` wrapper; the repository’s

package/dist/browser.d.ts

@@ -124,6 +124,11 @@ export interface Mouse {
     /** Wheel-scroll by a pixel delta. */
     wheel(dx: number, dy: number): Promise<void>;
 }
+export interface NavigationOptions {
+    /** Playwright navigation timeout in milliseconds; 0 disables the deadline. */
+    timeout?: number;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+}
 /**
  * Headless browser session — Playwright `Page`-shaped. Select elements with
  * the `getBy*`/`locator` roots (returning a {@link Locator}) and act on them;
@@ -136,14 +141,14 @@ export interface Browser {
     url(): string;
     /** Current page `<title>` (async, like Playwright's `page.title()`). */
     title(): Promise<string>;
-    /** Navigate to a URL; resolves when the main frame's load completes. */
-    goto(url: string): Promise<void>;
+    /** Navigate to a URL; waits for the main frame load unless waitUntil is supplied. */
+    goto(url: string, options?: NavigationOptions): Promise<void>;
     /** Navigate back in session history. */
-    goBack(): Promise<void>;
+    goBack(options?: NavigationOptions): Promise<void>;
     /** Navigate forward in session history. */
-    goForward(): Promise<void>;
+    goForward(options?: NavigationOptions): Promise<void>;
     /** Reload the current page. */
-    reload(): Promise<void>;
+    reload(options?: NavigationOptions): Promise<void>;
     readonly keyboard: Keyboard;
     readonly mouse: Mouse;
     /** Root CSS query. */
@@ -363,6 +368,8 @@ export declare function acquirePersistentDesktop(endpoint: string, windowIndex:
     desktopChrome?: DesktopChrome;
 }>;
 export interface RecordableFields {
+    timeout: number;
+    waitUntil: NonNullable<NavigationOptions["waitUntil"]>;
     target: RecordedBrowserLocatorPart[];
     destinationTarget: RecordedBrowserLocatorPart[];
     url: string;

package/dist/browser.js

@@ -1491,11 +1491,11 @@ function buildBackend(holder, recorder, buildOpts) {
         keyboard,
         mouse,
         touchscreen,
-        goto(url) {
+        goto(url, options) {
             recorder?.noteNavigation?.(url);
-            return instrumented("goto", { url }, async () => {
+            return instrumented("goto", { url, ...options }, async () => {
                 try {
-                    await holder.page.goto(url, { waitUntil: "load" });
+                    await holder.page.goto(url, { waitUntil: "load", ...options });
                 }
                 catch (err) {
                     // Restored-renderer DNS bug (see `rebuildView`): only when the
@@ -1508,23 +1508,23 @@ function buildBackend(holder, recorder, buildOpts) {
                     if (!(await daemonResolves(url)))
                         throw err;
                     await rebuildView(holder);
-                    await holder.page.goto(url, { waitUntil: "load" });
+                    await holder.page.goto(url, { waitUntil: "load", ...options });
                 }
             });
         },
-        goBack() {
-            return instrumented("goBack", {}, async () => {
-                await holder.page.goBack();
+        goBack(options) {
+            return instrumented("goBack", { ...options }, async () => {
+                await holder.page.goBack(options);
             });
         },
-        goForward() {
-            return instrumented("goForward", {}, async () => {
-                await holder.page.goForward();
+        goForward(options) {
+            return instrumented("goForward", { ...options }, async () => {
+                await holder.page.goForward(options);
             });
         },
-        reload() {
-            return instrumented("reload", {}, async () => {
-                await holder.page.reload();
+        reload(options) {
+            return instrumented("reload", { ...options }, async () => {
+                await holder.page.reload(options);
             });
         },
         locator: (css) => makeLocator(backend, strategy, { steps: [{ m: "locator", args: [css] }] }),

package/dist/index.d.ts

@@ -18,7 +18,7 @@ import type { Annotated } from "./annotate.js";
 export { SQL, type SqlClient, type SqlOptions } from "./sql.js";
 export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js";
 export { S3Client, type S3ClientLike, type S3File, type S3ClientOptions } from "./s3.js";
-export type { Browser, BrowserOptions, Keyboard, Mouse, Touchscreen } from "./browser.js";
+export type { Browser, BrowserOptions, NavigationOptions, Keyboard, Mouse, Touchscreen } from "./browser.js";
 export type { MicrophoneFixture } from "./harness/microphone-fixture.js";
 export type { FakeWebSocket, FakeWebSocketHandlers } from "./fake-websocket.js";
 import type { FakeWebSocketHandlers } from "./fake-websocket.js";
@@ -34,7 +34,7 @@ export type { Mobile, MobileApp } from "./mobile.js";
 import type { Mobile, MobileApp } from "./mobile.js";
 export type { Desktop, DesktopApp, DesktopOptions } from "./desktop.js";
 import type { Desktop, DesktopApp, DesktopOptions } from "./desktop.js";
-export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
+export type { Terminal, TerminalOpts, TerminalResult, TerminalWaitOptions, TerminalFailureCondition, TerminalCloseOptions } from "./terminal.js";
 import type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 export { type CoverageAdapter, type CoverageCaptureContext, type CoverageConfigureInfo, type CoverageSourceOptions, type CoverageSourceContext, type CoverageLoadContext, type ServiceCoverage, } from "./coverage.js";
 import { type ServiceCoverage } from "./coverage.js";

package/dist/recorder.d.ts

@@ -407,6 +407,9 @@ export interface RecordedBrowserLocatorPart {
 }
 export interface BrowserEvent extends BaseEvent {
     kind: "browser";
+    /** Explicit navigation options, when supplied by the test. */
+    timeout?: number;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
     action: BrowserAction;
     target?: RecordedBrowserLocatorPart[];
     destinationTarget?: RecordedBrowserLocatorPart[];
@@ -534,6 +537,18 @@ export interface TerminalEvent extends BaseEvent {
 }
 /** Action taken on an open interactive terminal session. */
 export type TerminalStepAction = "send" | "sendLine" | "press" | "waitFor" | "exit" | "close";
+export type TerminalWaitMatcher = {
+    kind: "text";
+    value: string;
+} | {
+    kind: "regex";
+    value: string;
+    flags: string;
+} | {
+    kind: "custom";
+    description?: string;
+};
+export type TerminalWaitOutcome = "matched" | "timed_out" | "failure_matched" | "predicate_error" | "process_exited" | "cancelled";
 /**
  * One operation on an open interactive terminal — analogous to
  * `BrowserEvent`. The session's heavy asciicast frames live on the
@@ -557,9 +572,21 @@ export interface TerminalStepEvent extends BaseEvent {
     description?: string;
     /** How many polls `waitFor` made. */
     attempts?: number;
-    /** Whether `waitFor` matched (false means it timed out). */
+    /** Whether `waitFor` matched; see outcome for failure reasons. */
     matched?: boolean;
-    /** Exit code observed on `close`. */
+    /** The condition being observed, including an optional custom-predicate description. */
+    matcher?: TerminalWaitMatcher;
+    outcome?: TerminalWaitOutcome;
+    failureMatchers?: {
+        description: string;
+        matcher: TerminalWaitMatcher;
+    }[];
+    intervalMs?: number;
+    timeoutMs?: number;
+    /** Wait boundaries on the session clock, including time with no output. */
+    castStartTimeSec?: number;
+    castEndTimeSec?: number;
+    /** Exit code observed on exit, close, or a failed wait. */
     exitCode?: number;
     /** Rendered screen at the moment of the op (post-action), truncated. */
     screenPreview: string;

package/dist/terminal.d.ts

@@ -25,6 +25,25 @@ export interface TerminalOpts {
      */
     timeoutMs?: number;
 }
+/** A visible terminal failure that should stop a wait immediately. */
+export interface TerminalFailureCondition {
+    description: string;
+    matcher: string | RegExp;
+}
+export interface TerminalWaitOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+    /** Cancel this observation without closing the terminal. */
+    signal?: AbortSignal;
+    /** Describe a custom predicate's condition separately from the step title. */
+    condition?: string;
+    /** Checked against the rendered screen before the success matcher. */
+    failOn?: readonly TerminalFailureCondition[];
+}
+export interface TerminalCloseOptions {
+    /** Total deadline including graceful exit, kill and pipe drain. Default 10 s. */
+    timeoutMs?: number;
+}
 /** Result of the one-shot `ctx.terminal(...)` convenience. */
 export interface TerminalResult {
     /** Full decoded PTY output (raw bytes, ANSI escapes included). Capped. */
@@ -50,7 +69,8 @@ export interface Terminal {
     /**
      * Resolves when the underlying process ends — by `close()`, by the
      * inner command exiting, or by timeout — to a `TerminalResult` with
-     * the full captured `output` and `exitCode`. Never rejects.
+     * the full captured `output` and `exitCode`. Rejects if output cannot
+     * be drained after exit.
      *
      * The result is provenance-tagged against the `exit` step, so an
      * `expect((await term.exited).output).toContain(...)` /
@@ -91,29 +111,23 @@ export interface Terminal {
      * `description` is a short human label that shows up in the event
      * log so timelines don't fill with anonymous waits.
      *
-     * Defaults: 5 s total timeout, 100 ms between polls. Throws on
-     * timeout.
+     * Defaults: 10 s total timeout, 100 ms between polls. Throws on timeout,
+     * a failure condition, predicate error, cancellation, or process exit before
+     * a match. On exit the final drained screen is checked first. Async custom
+     * predicates are supported; cancellation stops polling but cannot forcibly
+     * cancel work started by the predicate itself.
      */
-    waitFor(description: string, matcher: string, opts?: {
-        timeoutMs?: number;
-        intervalMs?: number;
-    }): Promise<Wrapped<string>>;
-    waitFor(description: string, matcher: RegExp, opts?: {
-        timeoutMs?: number;
-        intervalMs?: number;
-    }): Promise<Wrapped<RegExpMatchArray>>;
-    waitFor<T = unknown>(description: string, matcher: (screen: string, output: string) => T, opts?: {
-        timeoutMs?: number;
-        intervalMs?: number;
-    }): Promise<Wrapped<NonNullable<Awaited<T>>>>;
+    waitFor(description: string, matcher: string, opts?: TerminalWaitOptions): Promise<Wrapped<string>>;
+    waitFor(description: string, matcher: RegExp, opts?: TerminalWaitOptions): Promise<Wrapped<RegExpMatchArray>>;
+    waitFor<T = unknown>(description: string, matcher: (screen: string, output: string) => T, opts?: TerminalWaitOptions): Promise<Wrapped<NonNullable<Awaited<T>>>>;
     /**
      * Tear down. Writes Ctrl-D to stdin to nudge the shell out, then
      * SIGKILLs after a grace period. Idempotent. Resolves to a
      * `TerminalResult` (tagged against the `close` step) so you can assert
      * on the transcript of a session that doesn't self-terminate. Optional
-     * — terminals are not auto-closed when a test ends.
+     * — terminals are not auto-closed when a test ends. Rejects on cleanup timeout.
      */
-    close(): Promise<Wrapped<TerminalResult>>;
+    close(opts?: TerminalCloseOptions): Promise<Wrapped<TerminalResult>>;
 }
 /**
  * The concrete handle `openTerminal` returns. Extends the public