@specific.dev/spectest 0.128.0 → 0.130.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/components/s3-runtime/README.md

@@ -0,0 +1,33 @@
+# Native S3 component runtime
+
+GoFakeS3 is pinned by `go.mod`/`go.sum`. `s3.ts` embeds these assets into a constant
+multi-stage Dockerfile, builds for the worker's native architecture, and ships
+only the static binary and dependency licenses. The Go builder is pinned to a
+multi-architecture digest. No project files or options enter the image build.
+
+The entrypoint retains the component's port 9090, path-style addressing, no
+automatic buckets, no signature/date validation, and permissive browser CORS.
+The memory backend supports pagination and versioning. Full VM snapshots clone
+its buckets, versions and pending multipart uploads; restarting the process
+starts empty, matching S3Mock's default temporary store.
+
+`metadata.patch` preserves Cache-Control, Content-Language and Expires on object
+uploads, multipart initiation and copies. Upstream currently drops these headers
+in `metadataHeaders`. The patch applies to the vendored, checksum-verified module;
+a failed patch stops the build. Recheck it when changing the upstream pin.
+
+From `sdk`, run the real-image contract on a Linux Docker host:
+
+```
+SPECTEST_TEST_S3_DOCKER=1 bun test src/components/s3-docker.test.ts
+SPECTEST_TEST_S3_DOCKER=1 SPECTEST_TEST_S3_BASELINE=1 bun test src/components/s3-docker.test.ts
+bun test src/components/s3.test.ts src/components/internal-fetch.test.ts
+bun run build
+```
+
+The baseline uses S3Mock 5.1.0. The contract covers helpers and recording, setup,
+credentials, HTTPS with preserved Host, browser CORS, unsigned/stale signatures,
+metadata, copy/range requests, multipart, paginated listing, versioning, and
+fresh-process lifecycle. It does not prove every S3 API is interchangeable:
+GoFakeS3 lacks some S3Mock features, including tagging, lifecycle and retention.
+Java/Spring/S3Mock-specific environment settings are no longer interpreted.

package/dist/components/s3-runtime/go.mod

@@ -0,0 +1,11 @@
+module spectest-s3
+
+go 1.24
+
+require github.com/johannesboyne/gofakes3 v1.2.1-0.20261011201219-0016ef2bf153
+
+require (
+	github.com/ryszard/goskiplist v0.0.0-20150312221310-2dfbae5fcf46 // indirect
+	go.shabbyrobe.org/gocovmerge v0.0.0-20230507111327-fa4f82cfbf4d // indirect
+	golang.org/x/tools v0.8.0 // indirect
+)

package/dist/components/s3-runtime/go.sum

@@ -0,0 +1,54 @@
+github.com/aws/aws-sdk-go-v2 v1.41.5 h1:dj5kopbwUsVUVFgO4Fi5BIT3t4WyqIDjGKCangnV/yY=
+github.com/aws/aws-sdk-go-v2 v1.41.5/go.mod h1:mwsPRE8ceUUpiTgF7QmQIJ7lgsKUPQOUl3o72QBrE1o=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 h1:eBMB84YGghSocM7PsjmmPffTa+1FBUeNvGvFou6V/4o=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8/go.mod h1:lyw7GFp3qENLh7kwzf7iMzAxDn+NzjXEAGjKS2UOKqI=
+github.com/aws/aws-sdk-go-v2/credentials v1.17.67 h1:9KxtdcIA/5xPNQyZRgUSpYOE6j9Bc4+D7nZua0KGYOM=
+github.com/aws/aws-sdk-go-v2/credentials v1.17.67/go.mod h1:p3C44m+cfnbv763s52gCqrjaqyPikj9Sg47kUVaNZQQ=
+github.com/aws/aws-sdk-go-v2/feature/s3/manager v1.17.75 h1:S61/E3N01oral6B3y9hZ2E1iFDqCZPPOBoBQretCnBI=
+github.com/aws/aws-sdk-go-v2/feature/s3/manager v1.17.75/go.mod h1:bDMQbkI1vJbNjnvJYpPTSNYBkI/VIv18ngWb/K84tkk=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 h1:Rgg6wvjjtX8bNHcvi9OnXWwcE0a2vGpbwmtICOsvcf4=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21/go.mod h1:A/kJFst/nm//cyqonihbdpQZwiUhhzpqTsdbhDdRF9c=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 h1:PEgGVtPoB6NTpPrBgqSE5hE/o47Ij9qk/SEZFbUOe9A=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21/go.mod h1:p+hz+PRAYlY3zcpJhPwXlLC4C+kqn70WIHwnzAfs6ps=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.22 h1:rWyie/PxDRIdhNf4DzRk0lvjVOqFJuNnO8WwaIRVxzQ=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.22/go.mod h1:zd/JsJ4P7oGfUhXn1VyLqaRZwPmZwg44Jf2dS84Dm3Y=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 h1:5EniKhLZe4xzL7a+fU3C2tfUN4nWIqlLesfrjkuPFTY=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7/go.mod h1:x0nZssQ3qZSnIcePWLvcoFisRXJzcTVvYpAAdYX8+GI=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.13 h1:JRaIgADQS/U6uXDqlPiefP32yXTda7Kqfx+LgspooZM=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.13/go.mod h1:CEuVn5WqOMilYl+tbccq8+N2ieCy0gVn3OtRb0vBNNM=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 h1:c31//R3xgIJMSC8S6hEVq+38DcvUlgFY0FM6mSI5oto=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21/go.mod h1:r6+pf23ouCB718FUxaqzZdbpYFyDtehyZcmP5KL9FkA=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.21 h1:ZlvrNcHSFFWURB8avufQq9gFsheUgjVD9536obIknfM=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.21/go.mod h1:cv3TNhVrssKR0O/xxLJVRfd2oazSnZnkUeTf6ctUwfQ=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.97.3 h1:HwxWTbTrIHm5qY+CAEur0s/figc3qwvLWsNkF4RPToo=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.97.3/go.mod h1:uoA43SdFwacedBfSgfFSjjCvYe8aYBS7EnU5GZ/YKMM=
+github.com/aws/smithy-go v1.24.2 h1:FzA3bu/nt/vDvmnkg+R8Xl46gmzEDam6mZ1hzmwXFng=
+github.com/aws/smithy-go v1.24.2/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/cevatbarisyilmaz/ara v0.0.4 h1:SGH10hXpBJhhTlObuZzTuFn1rrdmjQImITXnZVPSodc=
+github.com/cevatbarisyilmaz/ara v0.0.4/go.mod h1:BfFOxnUd6Mj6xmcvRxHN3Sr21Z1T3U2MYkYOmoQe4Ts=
+github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/johannesboyne/gofakes3 v1.2.1-0.20261011201219-0016ef2bf153 h1:ZaLBZJfUnKBlrPu0AX0T/i1N9BNU54j8sl9mCLzmpI0=
+github.com/johannesboyne/gofakes3 v1.2.1-0.20261011201219-0016ef2bf153/go.mod h1:UHhRZRod9rENGFrUWTYnQHZqlNgSmjOq8DaD/ATQYRM=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/ryszard/goskiplist v0.0.0-20150312221310-2dfbae5fcf46 h1:GHRpF1pTW19a8tTFrMLUcfWwyC0pnifVo2ClaLq+hP8=
+github.com/ryszard/goskiplist v0.0.0-20150312221310-2dfbae5fcf46/go.mod h1:uAQ5PCi+MFsC7HjREoAz1BU+Mq60+05gifQSsHSDG/8=
+github.com/spf13/afero v1.2.1 h1:qgMbHoJbPbw579P+1zVY+6n4nIFuIchaIjzZ/I/Yq8M=
+github.com/spf13/afero v1.2.1/go.mod h1:9ZxEEn6pIJ8Rxe320qSDBk6AsU0r9pR7Q4OcevTdifk=
+github.com/stretchr/testify v1.5.1 h1:nOGnQDM7FYENwehXlg/kFVnos3rEvtKTjRvOWSzb6H4=
+github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
+go.etcd.io/bbolt v1.3.5 h1:XAzx9gjCb0Rxj7EoqcClPD1d5ZBxZJk0jbuoPHenBt0=
+go.etcd.io/bbolt v1.3.5/go.mod h1:G5EMThwa9y8QZGBClrRx5EY+Yw9kAhnjy3bSjsnlVTQ=
+go.shabbyrobe.org/gocovmerge v0.0.0-20230507111327-fa4f82cfbf4d h1:Ns9kd1Rwzw7t0BR8XMphenji4SmIoNZPn8zhYmaVKP8=
+go.shabbyrobe.org/gocovmerge v0.0.0-20230507111327-fa4f82cfbf4d/go.mod h1:92Uoe3l++MlthCm+koNi0tcUCX3anayogF0Pa/sp24k=
+golang.org/x/sys v0.7.0 h1:3jlCCIQZPdOYu1h8BkNvLz8Kgwtae2cagcG/VamtZRU=
+golang.org/x/sys v0.7.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/text v0.9.0 h1:2sjJmO8cDvYveuX97RDLsxlyUxLl+GHoLxBiRdHllBE=
+golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
+golang.org/x/tools v0.8.0 h1:vSDcovVPld282ceKgDimkRSC8kpaH1dgyc9UMzlt84Y=
+golang.org/x/tools v0.8.0/go.mod h1:JxBZ99ISMI5ViVkT1tr6tdNmXeTrcpVSD3vZ1RsRdN4=
+gopkg.in/mgo.v2 v2.0.0-20180705113604-9856a29383ce h1:xcEWjVhvbDy+nHP67nPDDpbYrY+ILlfndk4bRioVHaU=
+gopkg.in/mgo.v2 v2.0.0-20180705113604-9856a29383ce/go.mod h1:yeKp02qBN3iKW1OzL3MGk2IdtZzaj7SFntXj72NppTA=
+gopkg.in/yaml.v2 v2.2.8 h1:obN1ZagJSUGI0Ek/LBmuj4SNLPfIny3KsKFopxRdj10=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=

package/dist/components/s3-runtime/main.go

@@ -0,0 +1,77 @@
+// The component's native entrypoint. Keep its defaults compatible with S3Mock;
+// the upstream CLI enforces clock skew and has different browser CORS defaults.
+package main
+
+import (
+	"log"
+	"net/http"
+
+	"github.com/johannesboyne/gofakes3"
+	"github.com/johannesboyne/gofakes3/backend/s3mem"
+)
+
+func main() {
+	// VM snapshots include RAM: buckets, versions and in-flight multipart state
+	// fork together. A fresh process starts empty, as S3Mock did by default.
+	// Unlike the Bolt backend, s3mem also supports bucket versioning.
+	backend := s3mem.New()
+	server := gofakes3.New(backend,
+		gofakes3.WithTimeSkewLimit(0), // S3Mock accepts arbitrary/expired signatures.
+		gofakes3.WithHostBucket(false),
+		gofakes3.WithAutoBucket(false),
+		gofakes3.WithLogger(gofakes3.GlobalLog()),
+	).Server()
+	log.Fatal(http.ListenAndServe(":9090", cors(server)))
+}
+
+// Preserve S3Mock's permissive browser uploads, including arbitrary metadata
+// headers. GoFakeS3's default allow-list rejects custom x-amz-meta-* headers and
+// only exposes ETag on preflights, hiding it from actual browser responses.
+func cors(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		origin := r.Header.Get("Origin")
+		w.Header().Add("Vary", "Origin")
+		w.Header().Add("Vary", "Access-Control-Request-Method")
+		w.Header().Add("Vary", "Access-Control-Request-Headers")
+		if origin != "" && r.Method == "OPTIONS" && r.Header.Get("Access-Control-Request-Method") != "" {
+			w.Header().Set("Access-Control-Allow-Origin", origin)
+			w.Header().Set("Access-Control-Allow-Credentials", "true")
+			w.Header().Set("Access-Control-Allow-Methods", r.Header.Get("Access-Control-Request-Method"))
+			w.Header().Set("Access-Control-Allow-Headers", r.Header.Get("Access-Control-Request-Headers"))
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		writer := &corsWriter{ResponseWriter: w, hasOrigin: origin != ""}
+		next.ServeHTTP(writer, r)
+		if !writer.written {
+			writer.WriteHeader(http.StatusOK)
+		}
+	})
+}
+
+type corsWriter struct {
+	http.ResponseWriter
+	hasOrigin bool
+	written   bool
+}
+
+func (w *corsWriter) WriteHeader(status int) {
+	if w.written {
+		return
+	}
+	w.written = true
+	if w.hasOrigin {
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		w.Header().Set("Access-Control-Expose-Headers", "*")
+	} else {
+		w.Header().Del("Access-Control-Allow-Origin")
+	}
+	w.ResponseWriter.WriteHeader(status)
+}
+
+func (w *corsWriter) Write(body []byte) (int, error) {
+	if !w.written {
+		w.WriteHeader(http.StatusOK)
+	}
+	return w.ResponseWriter.Write(body)
+}

package/dist/components/s3-runtime/metadata.patch

@@ -0,0 +1,12 @@
+--- a/vendor/github.com/johannesboyne/gofakes3/gofakes3.go
++++ b/vendor/github.com/johannesboyne/gofakes3/gofakes3.go
+@@ -1191,6 +1191,9 @@
+ 	for hk, hv := range headers {
+ 		if strings.HasPrefix(hk, "X-Amz-") ||
+ 			hk == "Content-Type" ||
++			hk == "Cache-Control" ||
++			hk == "Content-Language" ||
++			hk == "Expires" ||
+ 			hk == "Content-Disposition" ||
+ 			hk == "Content-Encoding" {
+ 			meta[hk] = hv[0]

package/dist/components/s3.d.ts

@@ -1,8 +1,7 @@
 import { type S3ClientLike } from "../s3.js";
 export interface S3Options {
     /**
-     * Buckets to create on first boot. The backing server's own `initialBuckets`
-     * env is unreliable across versions, so the component creates them in `setup`
+     * Buckets to create on first boot. The component creates them in `setup`
      * (a plain CreateBucket `PUT`) — captured into the warm snapshot, never
      * re-run on warm starts/forks.
      */
@@ -42,7 +41,7 @@ export interface S3Helpers {
 }
 /**
  * A ready-to-use, S3-compatible object store (backed by
- * [`adobe/s3mock`](https://github.com/adobe/S3Mock)), with an instrumented S3
+ * [GoFakeS3](https://github.com/johannesboyne/gofakes3)), with an instrumented S3
  * client on `ctx.svc.<key>.client`. Drop into `environment.services`:
  *
  * ```ts
@@ -90,8 +89,8 @@ export declare function s3(opts?: S3Options): {
     }[] | undefined;
     env?: Record<string, string> | undefined;
     image: {
-        type: "registry";
-        reference: string;
+        type: "dockerfile";
+        content: string;
     };
     ports: number[];
 };

package/dist/components/s3.js

@@ -1,21 +1,31 @@
+import { readFileSync } from "node:fs";
 import { rawFetch } from "../harness/raw-fetch.js";
 import { S3Client } from "../s3.js";
-// Backing image, pinned internally (not user-configurable). adobe/s3mock 5.1.0
-// is the current release; avoid exactly 5.0.0, which crashed at startup on
-// Java 25 (`NoClassDefFoundError: KotlinBuiltIns$2`) — fixed in 5.1.0.
-const S3_IMAGE = "adobe/s3mock:5.1.0";
-// Port the store listens on, fixed like the image and deliberately NOT an
-// option. The backing server's HTTP port is baked into the image, and nothing
-// the component returns can move it — so a `port` option could only relabel
-// the ready check, the declared ports and the client endpoint while the
-// container kept listening here. That is exactly what it did until 0.78.0: a
-// project that passed one got 60 s of refused probes and an environment that
-// never booted, with a healthy container beside it. A service reaches the
-// store at `http://<key>:9090`.
+// Build once per architecture/cache from pinned source: upstream's Docker Hub
+// image is amd64-only. Only the static native server ships in the runtime image.
+// Keep the Dockerfile independent of options so stores share the build cache.
+const S3_DOCKERFILE = `
+FROM golang:1.27.2-alpine@sha256:f92b6ef800e499660581efdabdf25d9d817a9d124eaf900924f0504e7e27e12d AS build
+RUN apk add --no-cache patch
+WORKDIR /src
+${["go.mod", "go.sum", "main.go", "metadata.patch"].map((file) => {
+    const data = readFileSync(new URL(`./s3-runtime/${file}`, import.meta.url)).toString("base64");
+    return `RUN printf '%s' '${data}' | base64 -d > ${file}`;
+}).join("\n")}
+RUN go mod vendor && patch -p1 < metadata.patch
+RUN CGO_ENABLED=0 go build -mod=vendor -trimpath -ldflags='-s -w' -o /s3-server .
+FROM scratch
+COPY --from=build /s3-server /s3-server
+COPY --from=build /src/vendor/github.com/johannesboyne/gofakes3/LICENSE /licenses/gofakes3
+COPY --from=build /src/vendor/github.com/ryszard/goskiplist/LICENSE /licenses/goskiplist
+EXPOSE 9090
+ENTRYPOINT ["/s3-server"]
+`;
+// Public endpoint stays fixed across backing-server changes.
 const S3_PORT = 9090;
 /**
  * A ready-to-use, S3-compatible object store (backed by
- * [`adobe/s3mock`](https://github.com/adobe/S3Mock)), with an instrumented S3
+ * [GoFakeS3](https://github.com/johannesboyne/gofakes3)), with an instrumented S3
  * client on `ctx.svc.<key>.client`. Drop into `environment.services`:
  *
  * ```ts
@@ -51,7 +61,7 @@ export function s3(opts = {}) {
     const secretAccessKey = opts.secretAccessKey ?? "s3";
     const region = opts.region ?? "us-east-1";
     return {
-        image: { type: "registry", reference: S3_IMAGE },
+        image: { type: "dockerfile", content: S3_DOCKERFILE },
         ports: [S3_PORT],
         ...(opts.env ? { env: opts.env } : {}),
         ...(opts.hosts

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