@specific.dev/spectest 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.8.0",
+  "version": "0.9.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

@@ -572,8 +572,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 +765,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 +1020,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}). */
@@ -1341,6 +1368,15 @@ interface Transforms {
   /** URL-decode the value, mirroring `decodeURIComponent(x)`. Chains after
    *  `base64Decoded()` for base64-then-URL-encoded values. */
   urlDecoded(): Expectation;
+  /** Parse the value as JSON (`JSON.parse(x)`) and assert on the result with the
+   *  full matcher vocabulary — `toEqual` against the decoded object/array,
+   *  `toContain`/`toHaveLength` against a decoded array. Throws-as-failed-assertion
+   *  if the value isn't a string or isn't valid JSON. Chains after other
+   *  transforms (e.g. `base64Decoded().jsonDecoded()` for a base64-wrapped JSON
+   *  payload). The optional type parameter `T` annotates the decoded shape at the
+   *  call site (`jsonDecoded<User>()`) — it casts the parsed value, but, like the
+   *  matchers, is not enforced at runtime. */
+  jsonDecoded<T = unknown>(): 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"`,

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;