@specific.dev/spectest 0.130.0 → 0.131.1

package/README.md

@@ -478,8 +478,11 @@ time, and ends when that step completes. Both `call(destination, { waitFor })`
 and `say(text, { waitFor })` poll application state, then wait for incoming
 silence. For `call`, polling starts after the call connects, allowing the greeting
 to finish within the call step. For `say`, polling starts after outgoing playback.
-Without `waitFor`, `call` ends when connected and `say` ends after outgoing playback. The quiet
-period (700 ms), poll interval (100 ms), and wait timeout (30 seconds) are
+Without `waitFor`, `call` ends when connected and `say` ends after outgoing playback. The
+wait has no timeout of its own: the test case's `timeoutMs` is the only ceiling,
+and a bound on the reply belongs inside the predicate (for example a `ctx.poll`
+with its own `timeoutMs`), where it appears in the timeline. The quiet
+period (700 ms) and poll interval (100 ms) are
 internal defaults for now. `waitFor` may return a nonempty transcript string
 instead of `true`; after the silence wait, it appears as **Response** below **Caller** in an indented chat row beneath the waveform. Return `false` or `""` to keep waiting. Your test supplies the text
 from application state or a fake; an async callback can wait and then return it.

package/dist/harness/phone.py

@@ -14,7 +14,7 @@ import time
 import wave
 import math
 from array import array
-from phone_recording import StreamingRecording, MEDIA_RATE, PEAK_SAMPLES
+from phone_recording import RecordingError, StreamingRecording, MEDIA_RATE, PEAK_SAMPLES
 
 # PJSIP writes directly to fd 1. Keep the protocol on a private duplicate.
 protocol = os.fdopen(os.dup(1), "w", buffering=1)
@@ -179,22 +179,29 @@ class Call(pj.Call):
         result = {"event": "recording", "sessionId": self.session_id,
                   "startedAtMs": self.started_at_ms, "duration": 0, "bytes": 0,
                   "contentType": "audio/webm", "peaks": []}
+        errors = [self.capture_error] if self.capture_error else []
         try:
             self.clock.stopTransmit(self.recorder)
-            if self.media is not None:
-                try:
-                    self.media.stopTransmit(self.recorder)
-                    self.media.stopTransmit(self.recipient_meter)
-                except Exception:
-                    pass  # The remote peer may already have removed its port.
+        except Exception as error:
+            # Native error text can contain SIP identities or credentials.
+            errors.append(f"Could not disconnect recording clock ({type(error).__name__})")
+        if self.media is not None:
+            try:
+                self.media.stopTransmit(self.recorder)
+                self.media.stopTransmit(self.recipient_meter)
+            except Exception:
+                pass  # The remote peer may already have removed its port.
+        try:
+            # Always close the sink and reap the encoder, even if detach failed.
             result.update(self.recorder.finish())
             peaks = result["peaks"]
             for side, track in self.recorder.tracks.items():
                 result[side] = (track + [0.0] * max(0, len(peaks) - len(track)))[:len(peaks)]
-            if self.capture_error:
-                result["error"] = self.capture_error
-        except Exception:
-            result["error"] = "Call recording could not be finalized"
+        except Exception as error:
+            detail = str(error) if isinstance(error, RecordingError) else type(error).__name__
+            errors.append(f"Call recording could not be finalized: {detail}")
+        if errors:
+            result["error"] = "; ".join(errors)
         protocol.write(json.dumps(result) + "\n")
 
 
@@ -271,12 +278,14 @@ def main():
         else:
             time.sleep(0.01)
 
-    def wait(predicate, timeout, live=False):
-        deadline = time.monotonic() + timeout
+    def wait(predicate, timeout=None, live=False):
+        # No timeout: run until satisfied, the call ends, or the SDK closes
+        # stdin (which happens at case timeout and cleanup).
+        deadline = None if timeout is None else time.monotonic() + timeout
         while not predicate():
             if live and call.disconnected:
                 raise ValueError(f"SIP call ended ({call.status})")
-            if time.monotonic() >= deadline:
+            if deadline is not None and time.monotonic() >= deadline:
                 raise ValueError("SIP operation timed out")
             pump()
 
@@ -374,14 +383,14 @@ def main():
                     if not call or call.disconnected or call.media is None:
                         raise ValueError("No connected call; cannot wait for silence")
                     silence = float(data["silenceMs"]) / 1000
-                    timeout = float(data["timeoutMs"]) / 1000
-                    if not math.isfinite(silence) or not math.isfinite(timeout) or silence <= 0 or timeout <= 0:
-                        raise ValueError("Silence duration and timeout must be positive")
+                    if not math.isfinite(silence) or silence <= 0:
+                        raise ValueError("Silence duration must be positive")
                     # A fresh quiet window starts AFTER the application predicate
                     # succeeds; quiet heard before that does not satisfy this wait.
+                    # The wait is bounded only by the test case's own timeout.
                     began = time.monotonic()
                     wait(lambda: time.monotonic() - max(began, call.incoming.last_voice) >= silence,
-                         timeout, live=True)
+                         live=True)
                     result["offset"] = call.recorder.offset
                 elif action == "position":
                     if not call:

package/dist/harness/phone_recording.py

@@ -10,6 +10,10 @@ MEDIA_RATE = 48000
 PEAK_SAMPLES = MEDIA_RATE // 20
 
 
+class RecordingError(RuntimeError):
+    """SDK-authored capture diagnostics, safe to include in test results."""
+
+
 class StreamingRecording:
     def __init__(self, path):
         self.path = path
@@ -85,7 +89,7 @@ class StreamingRecording:
             self.encoder.kill()
             self.writer.join(timeout=1)
         if self.error:
-            raise RuntimeError(self.error)
+            raise RecordingError(self.error)
         return {
             "duration": self.frames / MEDIA_RATE,
             "bytes": os.path.getsize(self.path),

package/dist/phone.js

@@ -116,7 +116,9 @@ class PhoneSession {
             return Promise.reject(new Error("Phone is closed"));
         const id = ++this.nextId;
         return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => { this.fail(new Error(`Phone ${action} timed out after ${timeout}ms`)); void this.close(); }, timeout);
+            const timer = Number.isFinite(timeout)
+                ? setTimeout(() => { this.fail(new Error(`Phone ${action} timed out after ${timeout}ms`)); void this.close(); }, timeout)
+                : undefined;
             this.pending.set(id, { resolve, reject, timer, position });
             this.child.stdin.write(JSON.stringify({ id, action, ...data }) + "\n");
         });
@@ -128,15 +130,15 @@ class PhoneSession {
         await this.request("open", { ...this.options, directory: this.directory }, 60_000);
         return this;
     }
+    // The predicate and the silence wait have no timeout of their own: a bound on
+    // the reply belongs inside the predicate (a poll with its own timeout), and the
+    // case timeout closes the phone, which aborts this wait.
     async waitForResponse(options) {
-        const timeout = 30_000;
-        const deadline = performance.now() + timeout;
         const controller = new AbortController();
         const cancel = () => controller.abort(this.failure ?? new Error("Phone closed"));
         this.cancellation.signal.addEventListener("abort", cancel, { once: true });
         if (this.closed)
             cancel();
-        const timer = setTimeout(() => controller.abort(new Error(`Phone response wait timed out after ${timeout}ms`)), timeout);
         const aborted = new Promise((_, reject) => {
             const rejectAbort = () => reject(controller.signal.reason);
             controller.signal.addEventListener("abort", rejectAbort, { once: true });
@@ -163,13 +165,11 @@ class PhoneSession {
                         }
                     }
                     controller.signal.throwIfAborted();
-                    const remaining = Math.max(1, deadline - performance.now());
-                    const reply = await this.request("wait_silence", { silenceMs: 700, timeoutMs: remaining }, remaining + 1000);
+                    const reply = await this.request("wait_silence", { silenceMs: 700 }, Infinity);
                     return { ...reply, response };
                 })]);
         }
         finally {
-            clearTimeout(timer);
             this.cancellation.signal.removeEventListener("abort", cancel);
             controller.abort();
             branch.finish(false);

package/package.json

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

package/src/harness/phone.py

@@ -14,7 +14,7 @@ import time
 import wave
 import math
 from array import array
-from phone_recording import StreamingRecording, MEDIA_RATE, PEAK_SAMPLES
+from phone_recording import RecordingError, StreamingRecording, MEDIA_RATE, PEAK_SAMPLES
 
 # PJSIP writes directly to fd 1. Keep the protocol on a private duplicate.
 protocol = os.fdopen(os.dup(1), "w", buffering=1)
@@ -179,22 +179,29 @@ class Call(pj.Call):
         result = {"event": "recording", "sessionId": self.session_id,
                   "startedAtMs": self.started_at_ms, "duration": 0, "bytes": 0,
                   "contentType": "audio/webm", "peaks": []}
+        errors = [self.capture_error] if self.capture_error else []
         try:
             self.clock.stopTransmit(self.recorder)
-            if self.media is not None:
-                try:
-                    self.media.stopTransmit(self.recorder)
-                    self.media.stopTransmit(self.recipient_meter)
-                except Exception:
-                    pass  # The remote peer may already have removed its port.
+        except Exception as error:
+            # Native error text can contain SIP identities or credentials.
+            errors.append(f"Could not disconnect recording clock ({type(error).__name__})")
+        if self.media is not None:
+            try:
+                self.media.stopTransmit(self.recorder)
+                self.media.stopTransmit(self.recipient_meter)
+            except Exception:
+                pass  # The remote peer may already have removed its port.
+        try:
+            # Always close the sink and reap the encoder, even if detach failed.
             result.update(self.recorder.finish())
             peaks = result["peaks"]
             for side, track in self.recorder.tracks.items():
                 result[side] = (track + [0.0] * max(0, len(peaks) - len(track)))[:len(peaks)]
-            if self.capture_error:
-                result["error"] = self.capture_error
-        except Exception:
-            result["error"] = "Call recording could not be finalized"
+        except Exception as error:
+            detail = str(error) if isinstance(error, RecordingError) else type(error).__name__
+            errors.append(f"Call recording could not be finalized: {detail}")
+        if errors:
+            result["error"] = "; ".join(errors)
         protocol.write(json.dumps(result) + "\n")
 
 
@@ -271,12 +278,14 @@ def main():
         else:
             time.sleep(0.01)
 
-    def wait(predicate, timeout, live=False):
-        deadline = time.monotonic() + timeout
+    def wait(predicate, timeout=None, live=False):
+        # No timeout: run until satisfied, the call ends, or the SDK closes
+        # stdin (which happens at case timeout and cleanup).
+        deadline = None if timeout is None else time.monotonic() + timeout
         while not predicate():
             if live and call.disconnected:
                 raise ValueError(f"SIP call ended ({call.status})")
-            if time.monotonic() >= deadline:
+            if deadline is not None and time.monotonic() >= deadline:
                 raise ValueError("SIP operation timed out")
             pump()
 
@@ -374,14 +383,14 @@ def main():
                     if not call or call.disconnected or call.media is None:
                         raise ValueError("No connected call; cannot wait for silence")
                     silence = float(data["silenceMs"]) / 1000
-                    timeout = float(data["timeoutMs"]) / 1000
-                    if not math.isfinite(silence) or not math.isfinite(timeout) or silence <= 0 or timeout <= 0:
-                        raise ValueError("Silence duration and timeout must be positive")
+                    if not math.isfinite(silence) or silence <= 0:
+                        raise ValueError("Silence duration must be positive")
                     # A fresh quiet window starts AFTER the application predicate
                     # succeeds; quiet heard before that does not satisfy this wait.
+                    # The wait is bounded only by the test case's own timeout.
                     began = time.monotonic()
                     wait(lambda: time.monotonic() - max(began, call.incoming.last_voice) >= silence,
-                         timeout, live=True)
+                         live=True)
                     result["offset"] = call.recorder.offset
                 elif action == "position":
                     if not call:

package/src/harness/phone_recording.py

@@ -10,6 +10,10 @@ MEDIA_RATE = 48000
 PEAK_SAMPLES = MEDIA_RATE // 20
 
 
+class RecordingError(RuntimeError):
+    """SDK-authored capture diagnostics, safe to include in test results."""
+
+
 class StreamingRecording:
     def __init__(self, path):
         self.path = path
@@ -85,7 +89,7 @@ class StreamingRecording:
             self.encoder.kill()
             self.writer.join(timeout=1)
         if self.error:
-            raise RuntimeError(self.error)
+            raise RecordingError(self.error)
         return {
             "duration": self.frames / MEDIA_RATE,
             "bytes": os.path.getsize(self.path),

package/src/phone.test.ts

@@ -1,4 +1,4 @@
-import { afterAll, afterEach, beforeAll, expect, spyOn, test } from "bun:test";
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
 import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -16,7 +16,7 @@ beforeAll(async () => {
     runtime,
     `#!/usr/bin/env bun
 import { createInterface } from "node:readline";
-let connected = false, directory, sessionId, started, clockRate = 1;
+let connected = false, directory, sessionId, started, recordingError, clockRate = 1;
 const offset = () => (Date.now() - started) / 1000 * clockRate;
 function finish() {
   if (!sessionId) return;
@@ -24,7 +24,7 @@ function finish() {
   const bytes = Buffer.alloc(128);
   bytes.set([0x1a,0x45,0xdf,0xa3]);
   require("node:fs").writeFileSync(directory + "/" + sessionId + ".webm", bytes);
-  console.log(JSON.stringify({event:"recording", sessionId, startedAtMs:started, duration, contentType:"audio/webm", encodingFinalizeMs:1, bytes:bytes.length, peaks:[.2,.8], callerPeaks:[.2,0], recipientPeaks:[0,.8]}));
+  console.log(JSON.stringify({event:"recording", sessionId, startedAtMs:started, duration, contentType:"audio/webm", encodingFinalizeMs:1, bytes:bytes.length, peaks:[.2,.8], callerPeaks:[.2,0], recipientPeaks:[0,.8], error:recordingError}));
   sessionId = undefined;
 }
 createInterface({ input: process.stdin }).on("line", async line => {
@@ -34,6 +34,9 @@ createInterface({ input: process.stdin }).on("line", async line => {
   if (data.action === "open") directory = data.directory;
   if (data.action === "call") {
     sessionId = data.sessionId; started = Date.now();
+    recordingError = data.destination === "recording-failure"
+      ? "Call recording could not be finalized: Phone recording encoder could not keep up with audio"
+      : undefined;
     clockRate = data.destination === "clock-drift" ? 0.25 : 1;
     console.log(JSON.stringify({event:"operation_started", id:data.id, offset:0}));
     if (data.destination === "timeout") return;
@@ -55,10 +58,9 @@ createInterface({ input: process.stdin }).on("line", async line => {
     }
   }
   if (data.action === "wait_silence") {
-    await Bun.sleep(Math.min(data.silenceMs, data.timeoutMs));
-    result = data.silenceMs > data.timeoutMs
-      ? {error:"SIP operation timed out"}
-      : {offset:offset()};
+    if (data.timeoutMs !== undefined) throw new Error("wait_silence must not carry a timeout");
+    await Bun.sleep(data.silenceMs);
+    result = {offset:offset()};
   }
   if (data.action === "position") result = {offset:offset()};
   console.log(JSON.stringify({ id: data.id, ...result }));
@@ -363,17 +365,17 @@ test("waits for the predicate then a fresh silence window inside one serialized
   expect(recording!.duration - b.end).toBeGreaterThanOrEqual(.04);
 });
 
-test("predicate errors and hung predicates fail the say step without waiting for silence", async () => {
+test("predicate errors fail the say step without waiting for silence, and a hung predicate waits until the phone closes", async () => {
   startRecording();
   const phone = await scope.open(options);
   await phone.call("123");
   await expect(phone.say("Throw", { waitFor: () => { throw new Error("Application failed"); } })).rejects.toThrow("Application failed");
-  const nativeTimeout = globalThis.setTimeout;
-  const timer = spyOn(globalThis, "setTimeout").mockImplementation(((fn: any, ms: number, ...args: any[]) =>
-    nativeTimeout(fn, ms === 30_000 ? 40 : ms, ...args)) as typeof setTimeout);
-  try {
-    await expect(phone.say("Hang", { waitFor: () => new Promise(() => {}) })).rejects.toThrow("response wait timed out");
-  } finally { timer.mockRestore(); }
+  // No response-wait timeout of its own: only closing the phone (case timeout
+  // or cleanup) ends a predicate that never returns.
+  const hung = phone.say("Hang", { waitFor: () => new Promise(() => {}) }).catch(error => error);
+  await Bun.sleep(200);
+  await phone.close();
+  expect(String(await hung)).toContain("closed");
   await scope.finish();
   const events = stopRecording() as any[];
   expect(events.slice(1).map(e => e.status)).toEqual(["failed", "failed"]);
@@ -413,10 +415,10 @@ test("real harness exposes ctx.phone, seals recordings on every outcome and serv
   await writeFile(join(root, "spectest/index.ts"), `
     import { defineEnvironment } from ${JSON.stringify(sdk)};
     const env = defineEnvironment({ name: "phone-integration", services: {} });
-    const cases = ["success", "failure", "timeout"].map(outcome => env.test(outcome,
+    const cases = ["success", "failure", "timeout", "recording-failure"].map(outcome => env.test(outcome,
       { timeoutMs: outcome === "timeout" ? 350 : 2000 }, async ctx => {
         const phone = await ctx.phone(${JSON.stringify(options)});
-        await phone.call("123");
+        await phone.call(outcome === "recording-failure" ? outcome : "123");
         await phone.say("One. Two.");
         await new Promise(r => setTimeout(r, 30));
         if (outcome === "failure") throw new Error("application assertion failed");
@@ -429,7 +431,7 @@ test("real harness exposes ctx.phone, seals recordings on every outcome and serv
     import { strict as assert } from "node:assert";
     import { METHODS } from ${JSON.stringify(daemon)};
     const loaded = await METHODS.load({});
-    assert.equal(loaded.cases.length, 3);
+    assert.equal(loaded.cases.length, 4);
     for (const [index, test] of loaded.cases.entries()) {
       const result = await METHODS.run({caseId:test.id});
       assert.equal(result.status, index === 0 ? "passed" : "failed", JSON.stringify(result));
@@ -437,6 +439,13 @@ test("real harness exposes ctx.phone, seals recordings on every outcome and serv
       if (index === 2) assert.match(result.error.message, /timed out/);
       assert.equal(result.phoneRecordings.length, 1);
       const recording = result.phoneRecordings[0];
+      if (index === 3) {
+        const message = "Call recording could not be finalized: Phone recording encoder could not keep up with audio";
+        assert.equal(recording.error, message);
+        assert.equal(result.error.message, message);
+        await assert.rejects(METHODS.phoneRecordingChunk({caseId:recording.id}), /Unknown/);
+        continue;
+      }
       assert.equal(recording.error, undefined);
       assert.ok(recording.duration > 0);
       assert.deepEqual(recording.callerPeaks, [.2,0]);

package/src/phone.ts

@@ -83,7 +83,7 @@ export async function releasePhoneRecording(id: string) {
 }
 
 class PhoneSession implements Phone {
-  private pending = new Map<number, { resolve: (r: Reply) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout>; position?: (event: string, offset: number) => void }>();
+  private pending = new Map<number, { resolve: (r: Reply) => void; reject: (e: Error) => void; timer?: ReturnType<typeof setTimeout>; position?: (event: string, offset: number) => void }>();
   private nextId = 0;
   private closed = false;
   private failure?: Error;
@@ -138,7 +138,9 @@ class PhoneSession implements Phone {
     if (this.closed) return Promise.reject(new Error("Phone is closed"));
     const id = ++this.nextId;
     return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => { this.fail(new Error(`Phone ${action} timed out after ${timeout}ms`)); void this.close(); }, timeout);
+      const timer = Number.isFinite(timeout)
+        ? setTimeout(() => { this.fail(new Error(`Phone ${action} timed out after ${timeout}ms`)); void this.close(); }, timeout)
+        : undefined;
       this.pending.set(id, { resolve, reject, timer, position });
       this.child.stdin.write(JSON.stringify({ id, action, ...data }) + "\n");
     });
@@ -149,14 +151,14 @@ class PhoneSession implements Phone {
     await this.request("open", { ...this.options, directory: this.directory }, 60_000);
     return this;
   }
+  // The predicate and the silence wait have no timeout of their own: a bound on
+  // the reply belongs inside the predicate (a poll with its own timeout), and the
+  // case timeout closes the phone, which aborts this wait.
   private async waitForResponse(options: CallOptions): Promise<Reply & { response?: string }> {
-    const timeout = 30_000;
-    const deadline = performance.now() + timeout;
     const controller = new AbortController();
     const cancel = () => controller.abort(this.failure ?? new Error("Phone closed"));
     this.cancellation.signal.addEventListener("abort", cancel, { once: true });
     if (this.closed) cancel();
-    const timer = setTimeout(() => controller.abort(new Error(`Phone response wait timed out after ${timeout}ms`)), timeout);
     const aborted = new Promise<never>((_, reject) => {
       const rejectAbort = () => reject(controller.signal.reason);
       controller.signal.addEventListener("abort", rejectAbort, { once: true });
@@ -181,12 +183,10 @@ class PhoneSession implements Phone {
           }
         }
         controller.signal.throwIfAborted();
-        const remaining = Math.max(1, deadline - performance.now());
-        const reply = await this.request("wait_silence", { silenceMs: 700, timeoutMs: remaining }, remaining + 1000);
+        const reply = await this.request("wait_silence", { silenceMs: 700 }, Infinity);
         return { ...reply, response };
       })]);
     } finally {
-      clearTimeout(timer);
       this.cancellation.signal.removeEventListener("abort", cancel);
       controller.abort();
       branch.finish(false);