@specific.dev/spectest 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/components/index.ts

@@ -11,6 +11,11 @@ export {
   type PostgresOptions,
   type PostgresHelpers,
 } from "./postgres.js";
+export {
+  s3,
+  type S3Options,
+  type S3Helpers,
+} from "./s3.js";
 // `SQL` / `SqlClient` now live in the core SDK (`@specific.dev/spectest`),
 // next to `expect` and `fetch` — re-exported here so existing
 // `from ".../components"` imports keep resolving.

package/src/components/s3.ts

@@ -0,0 +1,132 @@
+import type { ServiceDefinition } from "../index.js";
+import { S3Client, type S3ClientLike } from "../s3.js";
+
+export interface S3Options {
+  /** HTTP port the S3 API is served on. Default `9090`. */
+  port?: number;
+  /**
+   * Buckets to create on first boot. The backing server's own `initialBuckets`
+   * env is unreliable across versions, so the component creates them in `setup`
+   * (a plain CreateBucket `PUT`) — captured into the warm snapshot, never
+   * re-run on warm starts/forks.
+   */
+  buckets?: string[];
+  /**
+   * Default bucket the `helpers.client` targets (so `client.file("k")` resolves
+   * without a per-call `{ bucket }`). Defaults to the first entry of `buckets`.
+   */
+  bucket?: string;
+  /**
+   * Hostnames to additionally serve the store at over **HTTPS** (CA-trusted),
+   * via the daemon's TLS-terminating reverse proxy. Optional — defaults to none;
+   * the store is always reachable at `http://<key>:<port>` regardless. Set this
+   * only when the app under test hardcodes a specific prod S3 endpoint it can't
+   * be told to override (`https://<bucket>.s3.amazonaws.com`, a provider's
+   * storage host): the daemon mints a cert for each host and proxies to the
+   * store's plain HTTP. The store ignores SigV4, so the Host rewrite is harmless.
+   */
+  hosts?: string[];
+  /** Access key id the helper client signs with. The store ignores SigV4, so
+   *  any non-empty value works; default `"s3"`. */
+  accessKeyId?: string;
+  /** Secret key the helper client signs with (ignored by the store). Default
+   *  `"s3"`. */
+  secretAccessKey?: string;
+  /** Region for the helper client. Default `"us-east-1"`. */
+  region?: string;
+  /** Extra environment variables forwarded to the container. */
+  env?: Record<string, string>;
+}
+
+/** Helpers an `s3(...)` service exposes on `ctx.svc.<name>`. */
+export interface S3Helpers {
+  /** An instrumented {@link S3Client} pointed at this store (path-style) — each
+   *  object op lands on the test event log and its result comes back
+   *  provenance-wrapped, so `expect(...)` on a read links to the op. */
+  client: S3ClientLike;
+}
+
+// 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";
+
+/**
+ * A ready-to-use, S3-compatible object store (backed by
+ * [`adobe/s3mock`](https://github.com/adobe/S3Mock)), with an instrumented S3
+ * client on `ctx.svc.<key>.client`. Drop into `environment.services`:
+ *
+ * ```ts
+ * import { s3 } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   storage: s3({ buckets: ["uploads"] }),
+ * },
+ * ```
+ *
+ * Tests get an instrumented S3 client at `ctx.svc.<key>.client`:
+ *
+ * ```ts
+ * await ctx.svc.storage.client.write("hello.txt", "hi there");
+ * const body = await ctx.svc.storage.client.file("hello.txt").text();
+ * expect(body).toBe("hi there");          // nests under the s3 read step
+ * ```
+ *
+ * The store skips SigV4 validation and is path-style only (what S3-compatible
+ * clients use), so it stands in for AWS S3, R2, Spaces, etc. without credential
+ * plumbing. If — and only if — the app under test hardcodes a specific prod S3
+ * endpoint, pass `hosts` to also serve the store there over a CA-trusted cert:
+ *
+ * ```ts
+ * // app hardcodes https://files.example.com — serve it there too:
+ * storage: s3({ hosts: ["files.example.com"] }),
+ * ```
+ */
+export function s3(opts: S3Options = {}) {
+  const port = opts.port ?? 9090;
+  const buckets = opts.buckets ?? [];
+  const defaultBucket = opts.bucket ?? buckets[0];
+  const accessKeyId = opts.accessKeyId ?? "s3";
+  const secretAccessKey = opts.secretAccessKey ?? "s3";
+  const region = opts.region ?? "us-east-1";
+
+  return {
+    image: { type: "registry", reference: S3_IMAGE },
+    ports: [port],
+    ...(opts.env ? { env: opts.env } : {}),
+    ...(opts.hosts
+      ? { tls: opts.hosts.map((hostname) => ({ hostname, port })) }
+      : {}),
+    // GET / returns the ListBuckets XML with 200 once the store is up.
+    readyCheck: { type: "http" as const, port, path: "/", timeoutSecs: 60 },
+    helpers: ({ name }: { name: string }): S3Helpers => ({
+      client: new S3Client({
+        endpoint: `http://${name}:${port}`,
+        region,
+        accessKeyId,
+        secretAccessKey,
+        ...(defaultBucket ? { bucket: defaultBucket } : {}),
+        // Path-style (Bun's default) — the store is path-style only.
+      }),
+    }),
+    ...(buckets.length > 0
+      ? {
+          setup: async ({ name }: { name: string }) => {
+            for (const bucket of buckets) {
+              // CreateBucket is a plain `PUT` on the bucket root; the store
+              // returns 200 (or 409 if it already exists — idempotent enough to
+              // ignore).
+              const res = await fetch(`http://${name}:${port}/${bucket}`, {
+                method: "PUT",
+              });
+              if (!res.ok && res.status !== 409) {
+                throw new Error(
+                  `s3: failed to create bucket ${bucket}: ${res.status}`,
+                );
+              }
+            }
+          },
+        }
+      : {}),
+  } satisfies ServiceDefinition<S3Helpers>;
+}

package/src/index.ts

@@ -42,7 +42,7 @@ export { field } from "./inspect.js";
 // assertions stay tracked. See `sql.ts` / `redis.ts` / `s3.ts`.
 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 S3Options } from "./s3.js";
+export { S3Client, type S3ClientLike, type S3File, type S3ClientOptions } from "./s3.js";
 
 export type {
   Browser,
@@ -1350,6 +1350,8 @@ interface Matchers {
   toBeFalsy(): void;
   toBeGreaterThan(n: number): void;
   toBeLessThan(n: number): void;
+  toBeGreaterThanOrEqual(n: number): void;
+  toBeLessThanOrEqual(n: number): void;
   toContain(expected: unknown): void;
   toMatch(re: RegExp): void;
   toHaveLength(n: number): void;
@@ -1359,12 +1361,19 @@ export interface Expectation extends Matchers {
   not: Matchers;
 }
 
-export function expect(actual: Provenanced): Expectation {
-  // The parameter is typed to the {@link Provenanced} family so a raw value
-  // (`expect(res.status === 200)`, `expect(2 + 2)`) is a *compile error* — every
-  // assertion that reaches the timeline this way carries a provenance link back
-  // to the op that produced it. Assert on a genuinely raw value with
-  // `expectRaw(message, value)` instead.
+export function expect(actual: Provenanced, message?: string): Expectation {
+  // The first parameter is typed to the {@link Provenanced} family so a raw
+  // value (`expect(res.status === 200)`, `expect(2 + 2)`) is a *compile error* —
+  // every assertion that reaches the timeline this way carries a provenance link
+  // back to the op that produced it. Assert on a genuinely raw value with
+  // `expectRaw(value, message)` instead.
+  //
+  // `message` is an **optional** human label for the assertion. The UI already
+  // renders the target, matcher, and expected value, so a message that just
+  // restates them is noise — supply one *only* when the check's intent isn't
+  // obvious from those alone (e.g.
+  // `expect(res.status, "blocked once the rate limit trips").toBe(429)`). When
+  // present it leads the assertion's summary, the same way `expectRaw`'s does.
   //
   // A `null`/`undefined` read off a wrapped op result reaches here untagged
   // (a symbol can't ride on nullish). `adoptNullishTag` recovers the tag from
@@ -1372,20 +1381,22 @@ export function expect(actual: Provenanced): Expectation {
   // `expect(dep.status.readyReplicas).toBeFalsy()` nests under its op just like
   // a non-nullish read. Done once here (not in `buildMatchers`) so the `.not`
   // re-pass reuses the same tagged holder instead of re-consuming the note.
-  return buildMatchers(adoptNullishTag(actual), false);
+  return buildMatchers(adoptNullishTag(actual), false, message);
 }
 
 /**
  * Assert on a value with **no provenance** — a computed number, a raw
  * WebSocket frame, anything that didn't flow from a recorded op. `message` is
- * required and reads as the natural follow-on to "assert …" (e.g.
- * `expectRaw("id matches the generated value", id)`); it renders as the
- * assertion's label in the CLI/dashboard ("ASSERT <message>") since a raw
- * assertion has no op to nest under. Prefer `expect(...)` whenever the value
- * carries provenance — only reach for this when the type gate would (rightly)
- * reject the value.
+ * required (it's the second argument) and reads as the natural follow-on to
+ * "assert …" (e.g. `expectRaw(id, "id matches the generated value")`); it
+ * renders as the assertion's label in the CLI/dashboard ("ASSERT <message>")
+ * since a raw assertion has no op to nest under. Prefer `expect(...)` whenever
+ * the value carries provenance — only reach for this when the type gate would
+ * (rightly) reject the value. (`expect`'s own `message` is optional; here it is
+ * mandatory, since the label is the only human-meaningful summary a raw
+ * assertion has.)
  */
-export function expectRaw(message: string, actual: unknown): Expectation {
+export function expectRaw(actual: unknown, message: string): Expectation {
   // Force the raw form so no stray tag is read even if a wrapped value is
   // passed: an `expectRaw` assertion is *deliberately* unlinked, rendered at
   // top level under its own message rather than nested beneath an op.
@@ -1425,7 +1436,7 @@ function buildCore(
     cond: boolean,
     msg: string,
     expectedFor?: unknown,
-    opts?: { actual?: unknown; pathSuffix?: string },
+    opts?: { actual?: unknown },
   ): void => {
     // A failed upstream transform short-circuits every matcher to a failure —
     // there is no meaningful value to match, and negation can't rescue a value
@@ -1455,9 +1466,7 @@ function buildCore(
       error: passed ? undefined : msg,
       message,
       sourceSeq: tag?.sourceSeq,
-      path: tag
-        ? [...tag.path, ...(opts?.pathSuffix ? [opts.pathSuffix] : [])]
-        : undefined,
+      path: tag ? [...tag.path] : undefined,
     });
     if (!passed) throw new ExpectationError(msg);
   };
@@ -1516,6 +1525,22 @@ function buildCore(
         n,
       );
     },
+    toBeGreaterThanOrEqual(n) {
+      run(
+        "toBeGreaterThanOrEqual",
+        typeof actual === "number" && actual >= n,
+        `expected ${fmt(actual)}${negated ? " not" : ""} to be >= ${n}`,
+        n,
+      );
+    },
+    toBeLessThanOrEqual(n) {
+      run(
+        "toBeLessThanOrEqual",
+        typeof actual === "number" && actual <= n,
+        `expected ${fmt(actual)}${negated ? " not" : ""} to be <= ${n}`,
+        n,
+      );
+    },
     toContain(expected) {
       const exp = readRaw(expected);
       let contained = false;
@@ -1560,13 +1585,19 @@ function buildCore(
               typeof (actual as { length?: unknown }).length === "number"
             ? ((actual as { length: number }).length as number)
             : undefined;
+      // The provenance `path` stays the container's own path — `.length` is
+      // the matcher's internal read, not a property access the author wrote,
+      // so it doesn't belong in the path (recording it produced a redundant
+      // "length toHaveLength N" in the UI, since the matcher name already says
+      // "length"). `actual` is still the length number: that's what's worth
+      // showing on failure, and the `toHaveLength` matcher disambiguates it.
       run(
         "toHaveLength",
         len === n,
         `expected ${fmt(actual)}${negated ? " not" : ""} to have length ${n}` +
           (len === undefined ? " (value has no length)" : ` (got ${len})`),
         n,
-        { actual: len, pathSuffix: "length" },
+        { actual: len },
       );
     },
     get not(): Matchers {

package/src/inspect.ts

@@ -482,7 +482,7 @@ export interface Carrier<T> {
  * tag, but `adoptNullishTag` recovers its provenance at runtime, so
  * `expect(rows[0]?.text)` and `expect(dep.status.readyReplicas)` stay on
  * `expect`. To assert on a value with no provenance (a computed number, a raw
- * WebSocket frame), use `expectRaw(message, value)` instead.
+ * WebSocket frame), use `expectRaw(value, message)` instead.
  */
 export type Provenanced = { unwrap(): unknown } | null | undefined;
 

package/src/recorder.ts

@@ -84,11 +84,13 @@ export interface AssertionEvent extends BaseEvent {
   /** Failure message produced by the matcher (only when `passed` is false). */
   error?: string;
   /**
-   * Author-supplied label for a raw assertion made via
-   * `expectRaw(message, …)`. Renders as the assertion's summary
-   * ("ASSERT <message>") and serves as its diff-alignment key, since a raw
-   * assertion has no provenance `path`. Absent for provenance-linked
-   * `expect(...)` assertions.
+   * Author-supplied label for the assertion. **Required** for a raw assertion
+   * (`expectRaw(value, message)`), where it renders as the summary
+   * ("ASSERT <message>") and serves as the diff-alignment key since a raw
+   * assertion has no provenance `path`. **Optional** for a provenance-linked
+   * `expect(value, message)`, where it leads the summary as a clarifying note
+   * alongside the rendered matcher/target. Absent when `expect(...)` was called
+   * without a message.
    */
   message?: string;
   /**

package/src/s3.ts

@@ -79,9 +79,9 @@ export interface S3ClientLike {
   [m: string]: (...args: any[]) => any;
 }
 
-/** Options accepted by the {@link S3Client} constructor — Bun's own plus a
- *  recording `label`. Passed through to `Bun.S3Client` verbatim. */
-export interface S3Options {
+/** Options accepted by the {@link S3Client} constructor — Bun's `S3Options`,
+ *  passed through to `Bun.S3Client` verbatim. */
+export interface S3ClientOptions {
   accessKeyId?: string;
   secretAccessKey?: string;
   sessionToken?: string;
@@ -92,12 +92,12 @@ export interface S3Options {
 }
 
 interface BunGlobal {
-  S3Client: new (options?: S3Options) => RawS3Client;
+  S3Client: new (options?: S3ClientOptions) => RawS3Client;
 }
 
 interface S3Constructor {
-  new (options?: S3Options): S3ClientLike;
-  (options?: S3Options): S3ClientLike;
+  new (options?: S3ClientOptions): S3ClientLike;
+  (options?: S3ClientOptions): S3ClientLike;
 }
 
 const MAX_PREVIEW = 512;
@@ -106,7 +106,7 @@ const MAX_PREVIEW = 512;
  * Open an instrumented S3 client. Usable with or without `new`. Requires the
  * Bun runtime — it runs inside the spectest daemon.
  */
-export const S3Client = function S3Client(options?: S3Options): S3ClientLike {
+export const S3Client = function S3Client(options?: S3ClientOptions): S3ClientLike {
   const bun = (globalThis as unknown as { Bun?: BunGlobal }).Bun;
   if (!bun?.S3Client) {
     throw new Error(