@specific.dev/spectest 0.51.0 → 0.52.0

package/dist/daemon.js

@@ -46,7 +46,7 @@ import { conflict, notFound, requireString, } from "./harness/methods.js";
 import { openTerminal } from "./terminal.js";
 import { readAnnotation } from "./annotate.js";
 import { pauseRecording, recordEmail, recordEnv, recordExec, recordFake, recordHttp, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, resumeRecording, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
-import { deepUnwrap, wrap, wrapResponse } from "./inspect.js";
+import { deepUnwrap, readRaw, wrap, wrapResponse } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
 function namedServices(cfg) {
@@ -3074,17 +3074,41 @@ const TEST_DATA = new Map();
  *  test timeout instead, and a project `setup` — which routinely waits on
  *  rollouts — stays unbounded, so neither gets a default. */
 const COMPONENT_EXEC_DEFAULT_TIMEOUT_MS = 120_000;
-/** Raw `docker exec` with optional piped stdin. Array command = exact
- * argv (no shell); string = `sh -lc`. Non-zero exit is reported via
- * `exitCode`, never thrown. Unlike the test-context `exec` this records
- * nothing — setup/helpers-factory time has no test timeline. */
+/** The running test case's recording `exec`, installed by `runOne`
+ *  for the length of the case and cleared again in its `finally`. It is
+ *  read at *call* time, which is the whole point: a component's context —
+ *  a `helpers` factory's, a service `setup` hook's — is built once during
+ *  bootstrap and cached, so the `exec` those hooks destructure can never
+ *  be the test's own. Without this, everything a service helper did was
+ *  invisible: `ctx.svc.<name>.<helper>()` shelling into a container
+ *  recorded no step, and a helper called inside a `ctx.poll` predicate
+ *  left the wait with nothing to render inside it (the poll keeps the
+ *  events of its last attempt — there were none). Undefined outside a
+ *  test, so bootstrap and project setup stay uninstrumented. */
+let RECORDING_EXEC;
+/** `docker exec` with optional piped stdin. Array command = exact argv
+ * (no shell); string = `sh -lc`. Non-zero exit is reported via
+ * `exitCode`, never thrown.
+ *
+ * Records a step when a test is running (through `RECORDING_EXEC`, which
+ * also captures the asciicast), and nothing at bootstrap. Either way the
+ * caller gets the PLAIN `ExecResult`, never the test context's
+ * provenance-wrapped one: component code is ordinary code written against
+ * the declared type, and a wrapper is an object — `res.exitCode !== 0`
+ * would be true for every exit code, and a client branching on `typeof`
+ * would take the wrong arm. Provenance has nothing to point at here
+ * anyway, since the helper's return value is not what the step recorded. */
 function componentExec(service, command, opts, defaultTimeoutMs) {
     assertKnownOpts("ctx.exec", opts, EXEC_OPT_KEYS);
     const timeoutMs = opts?.timeoutMs ?? defaultTimeoutMs;
-    return execInService(service, command, {
+    const merged = {
         ...opts,
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-    });
+    };
+    const recording = RECORDING_EXEC;
+    if (recording)
+        return recording(service, command, merged).then(readRaw);
+    return execInService(service, command, merged);
 }
 /** Transitive `dependsOn` closure of a service, by name. */
 function transitiveDeps(service) {
@@ -3918,6 +3942,12 @@ async function runOne(testCase) {
         testName: testCase.name,
         parent,
     };
+    // Let a component's `exec` record for the length of this case. The
+    // context a `helpers` factory or a service `setup` hook holds was built
+    // at bootstrap and carries `componentExec`, which reads this at call
+    // time — so from here on a service helper's `docker exec` lands on the
+    // timeline (and in the cast) exactly like the test's own `ctx.exec`.
+    RECORDING_EXEC = recordedExec;
     const timeoutMs = testCase.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
     let timer;
     const timedOut = new Promise((_, reject) => {
@@ -3946,6 +3976,7 @@ async function runOne(testCase) {
     finally {
         if (timer)
             clearTimeout(timer);
+        RECORDING_EXEC = undefined;
         restoreFetch();
         restoreConsole();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/daemon.ts

@@ -134,7 +134,7 @@ import {
   type TestEvent,
   type OmittedBody,
 } from "./recorder.js";
-import { deepUnwrap, wrap, wrapResponse } from "./inspect.js";
+import { deepUnwrap, readRaw, wrap, wrapResponse } from "./inspect.js";
 import type { Wrapped, WrappedResponse } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
@@ -3773,10 +3773,37 @@ const TEST_DATA = new Map<string, unknown>();
  *  rollouts — stays unbounded, so neither gets a default. */
 const COMPONENT_EXEC_DEFAULT_TIMEOUT_MS = 120_000;
 
-/** Raw `docker exec` with optional piped stdin. Array command = exact
- * argv (no shell); string = `sh -lc`. Non-zero exit is reported via
- * `exitCode`, never thrown. Unlike the test-context `exec` this records
- * nothing — setup/helpers-factory time has no test timeline. */
+/** The running test case's recording `exec`, installed by `runOne`
+ *  for the length of the case and cleared again in its `finally`. It is
+ *  read at *call* time, which is the whole point: a component's context —
+ *  a `helpers` factory's, a service `setup` hook's — is built once during
+ *  bootstrap and cached, so the `exec` those hooks destructure can never
+ *  be the test's own. Without this, everything a service helper did was
+ *  invisible: `ctx.svc.<name>.<helper>()` shelling into a container
+ *  recorded no step, and a helper called inside a `ctx.poll` predicate
+ *  left the wait with nothing to render inside it (the poll keeps the
+ *  events of its last attempt — there were none). Undefined outside a
+ *  test, so bootstrap and project setup stay uninstrumented. */
+let RECORDING_EXEC:
+  | ((
+      service: string,
+      command: string | string[],
+      opts?: ExecOpts,
+    ) => Promise<ExecResult>)
+  | undefined;
+
+/** `docker exec` with optional piped stdin. Array command = exact argv
+ * (no shell); string = `sh -lc`. Non-zero exit is reported via
+ * `exitCode`, never thrown.
+ *
+ * Records a step when a test is running (through `RECORDING_EXEC`, which
+ * also captures the asciicast), and nothing at bootstrap. Either way the
+ * caller gets the PLAIN `ExecResult`, never the test context's
+ * provenance-wrapped one: component code is ordinary code written against
+ * the declared type, and a wrapper is an object — `res.exitCode !== 0`
+ * would be true for every exit code, and a client branching on `typeof`
+ * would take the wrong arm. Provenance has nothing to point at here
+ * anyway, since the helper's return value is not what the step recorded. */
 function componentExec(
   service: string,
   command: string | string[],
@@ -3785,10 +3812,13 @@ function componentExec(
 ): Promise<ExecResult> {
   assertKnownOpts("ctx.exec", opts, EXEC_OPT_KEYS);
   const timeoutMs = opts?.timeoutMs ?? defaultTimeoutMs;
-  return execInService(service, command, {
+  const merged = {
     ...opts,
     ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-  });
+  };
+  const recording = RECORDING_EXEC;
+  if (recording) return recording(service, command, merged).then(readRaw);
+  return execInService(service, command, merged);
 }
 
 // ────────────────────────────────────────────────────────────────────────
@@ -4796,6 +4826,13 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     parent,
   };
 
+  // Let a component's `exec` record for the length of this case. The
+  // context a `helpers` factory or a service `setup` hook holds was built
+  // at bootstrap and carries `componentExec`, which reads this at call
+  // time — so from here on a service helper's `docker exec` lands on the
+  // timeline (and in the cast) exactly like the test's own `ctx.exec`.
+  RECORDING_EXEC = recordedExec;
+
   const timeoutMs = testCase.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
   let timer: NodeJS.Timeout | undefined;
   const timedOut = new Promise<never>((_, reject) => {
@@ -4825,6 +4862,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     };
   } finally {
     if (timer) clearTimeout(timer);
+    RECORDING_EXEC = undefined;
     restoreFetch();
     restoreConsole();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any