@specific.dev/spectest 0.8.0 → 0.10.0

package/package.json

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

package/src/daemon.ts

@@ -3016,11 +3016,27 @@ function installFetchWrapper(): () => void {
   };
 }
 
-function execInService(service: string, command: string): Promise<ExecResult> {
+/** Build the `docker exec` argv for a service command. An optional `cwd`
+ *  becomes `-w <cwd>` (the working-directory option of `ctx.exec`), so the
+ *  command runs from that directory without it being baked into the command
+ *  string. Used by both the buffered and streaming variants so they stay in
+ *  lockstep. */
+function dockerExecArgs(service: string, command: string, cwd?: string): string[] {
+  const args = ["exec"];
+  if (cwd) args.push("-w", cwd);
+  args.push(service, "sh", "-lc", command);
+  return args;
+}
+
+function execInService(
+  service: string,
+  command: string,
+  cwd?: string,
+): Promise<ExecResult> {
   return new Promise((resolve) => {
     execFile(
       "docker",
-      ["exec", service, "sh", "-lc", command],
+      dockerExecArgs(service, command, cwd),
       { maxBuffer: 16 * 1024 * 1024 },
       (err, stdout, stderr) => {
         const exitCode =
@@ -3046,8 +3062,9 @@ function execInService(service: string, command: string): Promise<ExecResult> {
 async function execInServiceWrapped(
   service: string,
   command: string,
+  opts?: { cwd?: string },
 ): Promise<Wrapped<ExecResult>> {
-  const res = await execInService(service, command);
+  const res = await execInService(service, command, opts?.cwd);
   return wrap(res, undefined) as unknown as Wrapped<ExecResult>;
 }
 
@@ -3074,9 +3091,10 @@ function execInServiceStreaming(
   service: string,
   command: string,
   onChunk: (stream: "stdout" | "stderr", data: string) => void,
+  cwd?: string,
 ): Promise<ExecResult> {
   return new Promise((resolve) => {
-    const child = spawn("docker", ["exec", service, "sh", "-lc", command], {
+    const child = spawn("docker", dockerExecArgs(service, command, cwd), {
       stdio: ["ignore", "pipe", "pipe"],
     });
     const acc = { stdout: "", stderr: "" };
@@ -3267,8 +3285,13 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   // or animated output replays with real timing in the web UI. The
   // frames are presentation-only; the ExecResult (and any assertions on
   // it) still sees the plain separated stdout/stderr.
-  const recordedExec = async (service: string, command: string): Promise<ExecResult> => {
+  const recordedExec = async (
+    service: string,
+    command: string,
+    opts?: { cwd?: string },
+  ): Promise<ExecResult> => {
     const t = Date.now();
+    const cwd = opts?.cwd;
     const resv = reserveEvent();
     const session = newTerminalSession(
       start,
@@ -3280,8 +3303,11 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     );
     terminalSessions.push(session.record);
     // Synthetic prompt frame so the replay is self-describing — the
-    // program's own output starts on the next line, like a real shell.
-    session.pushFrame(0, `\x1b[32m${service} $\x1b[0m \x1b[1m${command}\x1b[0m\r\n`);
+    // program's own output starts on the next line, like a real shell. A
+    // working directory rides in the prompt sigil (`svc:/dir $`) the way a
+    // real shell prompt shows it, so the recording stays self-describing.
+    const sigil = cwd ? `${service}:${cwd}` : service;
+    session.pushFrame(0, `\x1b[32m${sigil} $\x1b[0m \x1b[1m${command}\x1b[0m\r\n`);
     let frameBytes = 0;
     let frameCapped = false;
     const res = await execInServiceStreaming(service, command, (_stream, data) => {
@@ -3302,13 +3328,14 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
       // `\r\n` too keeps a CR|LF split across chunk boundaries
       // harmless (`\r\r\n` renders identically).
       session.pushFrame((Date.now() - t) / 1000, data.replace(/\r?\n/g, "\r\n"));
-    });
+    }, cwd);
     session.markClosed();
     const stdout = truncateUtf8(res.stdout);
     const stderr = truncateUtf8(res.stderr);
     const seq = recordExec({
       service,
       command,
+      cwd,
       exitCode: res.exitCode,
       stdout: stdout.value,
       stdoutTruncated: stdout.truncated,

package/src/index.ts

@@ -26,8 +26,9 @@ import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
 // `field` — a provenance-preserving, null-safe selector: a `null`/`undefined`
 // leaf read off a wrapped op result is raw and untagged, so an `expect(...)` on
 // it renders detached from its source op; `field` tags from the container so the
-// assertion still nests. (Base64-decoded values lose provenance the same way;
-// that case is the `.base64Decoded()` provenance transform on `expect(...)`.)
+// assertion still nests. (A decoded value loses provenance the same way — that
+// case is the `.transform(label, fn)` method every wrapped value carries, which
+// runs the still-tagged value through `fn` and re-wraps the result.)
 // To recover a raw value, call `.unwrap()` on it — spectest op results are
 // always wrapped (in every context), so the method is always there; there is no
 // `unwrap(x)` free function. See the `.unwrap()` discipline section of `spectest docs`.
@@ -572,8 +573,17 @@ export interface TestContext<
    *  program sees plain pipes (`isatty` false), so stdout/stderr stay
    *  byte-identical to what `exec` always returned and TTY-gated
    *  spinners/colour won't be emitted — reach for `terminal` when the
-   *  CLI needs to believe it's on a TTY. */
-  exec(service: string, command: string): Promise<Wrapped<ExecResult>>;
+   *  CLI needs to believe it's on a TTY.
+   *
+   *  Pass `{ cwd }` to run the command from a working directory instead of
+   *  prefixing it with `cd <dir> && ` — the cwd is kept off the command
+   *  string, so the timeline sidebar shows just the command and the
+   *  directory surfaces in the detail view. */
+  exec(
+    service: string,
+    command: string,
+    opts?: ExecOpts,
+  ): Promise<Wrapped<ExecResult>>;
   /**
    * Run a command inside a service container under a PTY and record the
    * full terminal session as an asciicast for replay in the web UI.
@@ -756,6 +766,20 @@ export interface ExecResult {
   exitCode: number;
 }
 
+/** Options for {@link TestContext.exec}. */
+export interface ExecOpts {
+  /**
+   * Working directory inside the container to run the command from.
+   * Equivalent to prefixing the command with `cd <cwd> && `, but the
+   * directory is kept off the command string: the recorded step's
+   * sidebar summary shows just the command, while the working directory
+   * is surfaced in the detail view (the prompt line of the captured
+   * terminal and the step's panel header). Implemented as `docker exec
+   * -w <cwd>`, so a relative path resolves against the image's WORKDIR.
+   */
+  cwd?: string;
+}
+
 export interface TestSuite<
   S extends ServicesMap = ServicesMap,
   F extends FakesMap = FakesMap,
@@ -997,7 +1021,11 @@ export interface ProjectSetupContext<
   F extends FakesMap = FakesMap,
 > {
   fetch: SpectestFetch;
-  exec(service: string, command: string): Promise<Wrapped<ExecResult>>;
+  exec(
+    service: string,
+    command: string,
+    opts?: ExecOpts,
+  ): Promise<Wrapped<ExecResult>>;
   readonly svc: ServiceHandlesFor<S>;
   /** Same surface tests see — fakes are already up by setup time. Typed
    * against the declared fakes map (see {@link TestContext.fakes}). */
@@ -1317,43 +1345,7 @@ interface Matchers {
   toHaveLength(n: number): void;
 }
 
-/**
- * Provenance-preserving transforms. Each returns a fresh {@link Expectation}
- * bound to the *decoded* value but still carrying the originating op's tag (its
- * path extended by a marker like `<base64>`), so the eventual assertion nests
- * under the source read in the timeline. This is what lets a value that must be
- * decoded through a plain function — `Buffer.from(x,"base64").toString()`,
- * `decodeURIComponent(x)` — be asserted on with the *full* matcher vocabulary
- * (`toHaveLength`, `toContain`, `toMatch`, …) without dropping to `expectRaw`,
- * which severs the link. Transforms chain (`.base64Decoded().urlDecoded()`),
- * and the matcher you finish with may be negated (`.base64Decoded().not.…`).
- *
- * They supersede the old `toBeBase64Of` matcher, which was equality-only:
- * `expect(secret.data?.X).base64Decoded().toBe("plain")` is the direct
- * replacement, and `.toHaveLength(32)` / `.toContain("redis://")` / `.toMatch(re)`
- * are the cases it couldn't express.
- */
-interface Transforms {
-  /** Interpret the value as a base64 string and decode it (UTF-8), mirroring
-   *  `Buffer.from(x, "base64").toString()`. Throws-as-failed-assertion if the
-   *  value isn't a string. */
-  base64Decoded(): Expectation;
-  /** URL-decode the value, mirroring `decodeURIComponent(x)`. Chains after
-   *  `base64Decoded()` for base64-then-URL-encoded values. */
-  urlDecoded(): Expectation;
-  /**
-   * Generic escape hatch: apply an arbitrary `fn` to the raw value and assert on
-   * the result, keeping provenance. `label` is a plain word (`"json"`,
-   * `"decompressed"`) appended to the op path so the timeline shows what was
-   * derived; the UI brackets it (`<json>`) to mark it as a derived step, so do
-   * **not** include the brackets yourself. Sugar like {@link base64Decoded} is
-   * built on this. If `fn` throws, the next assertion records as a failure
-   * describing the transform error.
-   */
-  transform(label: string, fn: (value: unknown) => unknown): Expectation;
-}
-
-export interface Expectation extends Matchers, Transforms {
+export interface Expectation extends Matchers {
   not: Matchers;
 }
 
@@ -1459,31 +1451,6 @@ function buildCore(
     });
     if (!passed) throw new ExpectationError(msg);
   };
-  // Apply `fn` to the raw value and rebuild against the result, extending the
-  // op path by a derived-step marker so the decoded value still nests under the
-  // source read. `label` is a plain word ("base64", "json"); the `<…>` marker
-  // syntax that distinguishes a transform from a real property read in the
-  // timeline is added here, so it lives in one place and never leaks into the
-  // API surface — the same convention `inspect.ts` uses for array methods
-  // (`<find>`, `<map>`). A throw becomes a `pendingError` on the returned
-  // Expectation rather than escaping — a malformed decode renders as a failed
-  // assertion in the timeline, not an unhandled exception. Propagates an
-  // existing `pendingError` untouched.
-  const applyTransform = (label: string, fn: (value: unknown) => unknown): Expectation => {
-    const marker = `<${label}>`;
-    const nextTag: OpTag | undefined = tag
-      ? { sourceSeq: tag.sourceSeq, path: [...tag.path, marker] }
-      : undefined;
-    if (pendingError !== undefined) {
-      return buildCore(undefined, nextTag, false, message, pendingError);
-    }
-    try {
-      return buildCore(fn(actual), nextTag, false, message);
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      return buildCore(undefined, nextTag, false, message, `${marker}: ${detail}`);
-    }
-  };
   return {
     toBe(expected) {
       const exp = readRaw(expected);
@@ -1592,25 +1559,6 @@ function buildCore(
         { actual: len, pathSuffix: "length" },
       );
     },
-    transform(label, fn) {
-      return applyTransform(label, fn);
-    },
-    base64Decoded() {
-      return applyTransform("base64", (v) => {
-        if (typeof v !== "string") {
-          throw new Error(`base64Decoded expects a string, got ${typeof v}`);
-        }
-        return Buffer.from(v, "base64").toString();
-      });
-    },
-    urlDecoded() {
-      return applyTransform("urldecode", (v) => {
-        if (typeof v !== "string") {
-          throw new Error(`urlDecoded expects a string, got ${typeof v}`);
-        }
-        return decodeURIComponent(v);
-      });
-    },
     get not(): Matchers {
       // Re-pass the already-unwrapped value, tag and message so the tag and raw
       // label are preserved for the negated branch's AssertionEvent.

package/src/inspect.ts

@@ -248,6 +248,12 @@ function wrapObject<T extends object>(
           return () => readRaw(target);
         }
       }
+      // `.transform(label, fn)` — same shape/guard as `unwrap`: only intercept
+      // when the underlying object has no own `transform`, so a real data field
+      // named `transform` is never shadowed.
+      if (prop === "transform" && !(prop in (target as object))) {
+        return makeTransform(readRaw(target), sourceSeq, path);
+      }
       // Hide thenable-ness from `await`. We must never accidentally
       // implement `then`, or `await fetch(...)` would resolve to the
       // wrong thing if we ever wrapped a Promise (we don't, but be safe).
@@ -298,6 +304,34 @@ function wrapObject<T extends object>(
   return new Proxy(raw, handler);
 }
 
+// The `.transform(label, fn)` method every wrapper (carrier + object/array
+// proxy) carries — the value-level analogue of `.unwrap()`. It runs the raw
+// value through `fn` and re-`wrap`s the result with `path` extended by a
+// `<label>` derived-step marker, so the decoded value keeps the source op's
+// provenance (`sourceSeq`) and stays navigable: a later `expect(...)` on it, or
+// on a subfield, still nests under the originating op (`secret.data.config.<json>.tier`).
+// `label` is a plain word; the `<…>` brackets are added here so they never leak
+// into the call site (the same convention array methods use, `<find>`/`<map>`).
+// A throw in `fn` (a non-string value, malformed base64/JSON) is rethrown
+// prefixed with `<label>:`, failing the test at the bad value.
+function makeTransform(
+  raw: unknown,
+  sourceSeq: number | undefined,
+  path: readonly string[],
+): (label: string, fn: (raw: never) => unknown) => unknown {
+  return (label, fn) => {
+    const nextPath = [...path, `<${label}>`];
+    let result: unknown;
+    try {
+      result = (fn as (r: unknown) => unknown)(raw);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`<${label}>: ${detail}`);
+    }
+    return wrap(result, sourceSeq, nextPath);
+  };
+}
+
 // Runtime shape of a primitive carrier: the public `Carrier<T>` surface
 // (`unwrap()`) plus the internal provenance symbols. Kept private so the
 // exported `Carrier<T>` stays clean.
@@ -316,6 +350,7 @@ function makeCarrier<T>(
     [OP_TAG]: tag,
     [UNWRAP]: raw,
     unwrap: () => raw,
+    transform: makeTransform(raw, sourceSeq, path) as unknown as Carrier<T>["transform"],
     // Coercion sinks recover the raw primitive instead of inheriting
     // Object.prototype's defaults ("[object Object]" / NaN / {}). A
     // carrier interpolated into a string, fed to arithmetic, `==`, or
@@ -338,10 +373,10 @@ function makeCarrier<T>(
 // passes them through raw. So `expect(row.deleted_at).toBe(null)` reaches
 // `expect()` as a bare `null` with no tag and renders as a disconnected
 // top-level row. `field` recovers the link by tagging from the *container*.
-// (Base64-decoded values lose their tag the same way, via the transform; that
-// case is handled by the `.base64Decoded()` provenance transform in index.ts,
-// which decodes the still-tagged value internally and rebuilds the Expectation
-// against the result.)
+// (A decoded value loses its tag the same way, through the decode; the
+// `.transform(label, fn)` method every wrapper carries (see `makeTransform`)
+// recovers it — it runs the still-tagged value through `fn` and re-`wrap`s the
+// result with the source path extended by a `<label>` marker.)
 // ───────────────────────────────────────────────────────────────────────────
 
 /**
@@ -410,6 +445,22 @@ export function field(value: unknown, ...path: Array<string | number>): unknown
 export interface Carrier<T> {
   /** Recover the raw underlying value. */
   unwrap(): T;
+  /**
+   * Run the raw value through `fn` and get back a provenance-carrying handle to
+   * the result — for asserting on a *decoded* value (base64, JSON, JWT, …) while
+   * keeping its link to the op that produced it. The op path is extended by a
+   * `<label>` marker, so a later `expect(...)` on the result still nests under
+   * the source op. `label` is a plain word (`"base64"`, `"json"`); the UI adds
+   * the `<…>` brackets, so don't include them yourself. `fn` receives the raw
+   * value (typed `T`), so no cast is needed. `R` types the result. A throw in
+   * `fn` is rethrown prefixed with `<label>:`, failing the test at the value.
+   *
+   * ```ts
+   * expect(secret.data.url.transform("base64", (s) => Buffer.from(s, "base64").toString()))
+   *   .toContain("redis://");
+   * ```
+   */
+  transform<R = unknown>(label: string, fn: (raw: T) => R): Wrapped<R>;
   /** Coerces to the raw value (arithmetic, `==`). */
   valueOf(): T;
   /** Renders the raw value (template interpolation). */
@@ -475,6 +526,9 @@ export type WrappedObject<T> = {
 } & {
   /** Recover the fully raw value (nested leaves unwrapped too). */
   unwrap(): T;
+  /** Run the raw object through `fn`, keeping provenance (op path + `<label>`),
+   *  and get back a navigable handle to the result. See {@link Carrier.transform}. */
+  transform<R = unknown>(label: string, fn: (raw: T) => R): Wrapped<R>;
 };
 
 /**
@@ -491,6 +545,9 @@ export interface WrappedArray<U> {
   readonly [index: number]: Wrapped<U>;
   /** Recover the raw array (elements unwrapped). */
   unwrap(): U[];
+  /** Run the raw array through `fn`, keeping provenance (op path + `<label>`),
+   *  and get back a navigable handle to the result. See {@link Carrier.transform}. */
+  transform<R = unknown>(label: string, fn: (raw: U[]) => R): Wrapped<R>;
   at(index: number): Wrapped<U> | undefined;
   find(
     predicate: (value: U, index: number, obj: U[]) => unknown,

package/src/recorder.ts

@@ -47,6 +47,12 @@ export interface ExecEvent extends BaseEvent {
   kind: "exec";
   service: string;
   command: string;
+  /**
+   * Working directory the command ran from (`ctx.exec(svc, cmd, { cwd })`),
+   * if any. Kept off `command` so the sidebar shows just the command; the
+   * detail view surfaces it. Absent when the call used no `cwd`.
+   */
+  cwd?: string;
   exitCode: number;
   /** stdout truncated to OUTPUT_SNIPPET_BYTES. */
   stdout: string;