Add test coverage for error paths, edge cases, CLI, and concurrency

34 new tests across 7 files covering:
- readBody failure and handleCompletions catch handler (server)
- CLI argument validation, help, fixture loading, and shutdown
- nextRequestError stacking, stop() error, reset() idempotency
- buildTextChunks/buildToolCallChunks edge cases (empty, unicode, short)
- writeSSEStream mid-stream write failure
- fixture-loader fs error paths (EACCES, ENOENT)
- onToolResult integration, large payload (50KB) streaming
- concurrent request handling (10 parallel)
- header forwarding verification in journal

Author: jpr5

src/__tests__/cli.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { execFile, type ChildProcess } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const CLI_PATH = resolve(__dirname, "../../dist/cli.js");
+
+/** Spawn the CLI and collect stdout/stderr/exit code. */
+function runCli(
+    args: string[],
+    opts: { timeout?: number } = {},
+): Promise<{ stdout: string; stderr: string; code: number | null }> {
+    const timeout = opts.timeout ?? 5000;
+    return new Promise((res) => {
+        const cp = execFile("node", [CLI_PATH, ...args], { timeout }, (err, stdout, stderr) => {
+            const code = cp.exitCode ?? (err && "code" in err ? (err as { code: number }).code : null);
+            res({ stdout, stderr, code });
+        });
+    });
+}
+
+/**
+ * Spawn the CLI expecting a long-running server.  Returns the child
+ * process plus helpers to read accumulated output and send signals.
+ */
+function spawnCli(args: string[]): {
+    cp: ChildProcess;
+    stdout: () => string;
+    stderr: () => string;
+    kill: (signal?: NodeJS.Signals) => void;
+    waitForOutput: (match: RegExp, timeoutMs?: number) => Promise<void>;
+} {
+    let out = "";
+    let err = "";
+    const cp = execFile("node", [CLI_PATH, ...args]);
+    cp.stdout?.on("data", (d) => {
+        out += d;
+    });
+    cp.stderr?.on("data", (d) => {
+        err += d;
+    });
+
+    const waitForOutput = (match: RegExp, timeoutMs = 5000): Promise<void> =>
+        new Promise((resolve, reject) => {
+            const deadline = setTimeout(() => {
+                reject(new Error(`Timed out waiting for ${match} — stdout: ${out}, stderr: ${err}`));
+            }, timeoutMs);
+
+            const check = () => {
+                if (match.test(out) || match.test(err)) {
+                    clearTimeout(deadline);
+                    resolve();
+                    return;
+                }
+                setTimeout(check, 50);
+            };
+            check();
+        });
+
+    return {
+        cp,
+        stdout: () => out,
+        stderr: () => err,
+        kill: (signal: NodeJS.Signals = "SIGTERM") => cp.kill(signal),
+        waitForOutput,
+    };
+}
+
+function makeTmpDir(): string {
+    return mkdtempSync(join(tmpdir(), "cli-test-"));
+}
+
+function writeFixture(dir: string, name: string): string {
+    const filePath = join(dir, name);
+    writeFileSync(
+        filePath,
+        JSON.stringify({
+            fixtures: [
+                {
+                    match: { userMessage: "hello" },
+                    response: { content: "Hello from test fixture!" },
+                },
+            ],
+        }),
+        "utf-8",
+    );
+    return filePath;
+}
+
+/* ================================================================== */
+
+describe("CLI: --help", () => {
+    it("prints usage text and exits with code 0", async () => {
+        const { stdout, code } = await runCli(["--help"]);
+        expect(stdout).toContain("Usage: mock-openai");
+        expect(stdout).toContain("--port");
+        expect(stdout).toContain("--fixtures");
+        expect(code).toBe(0);
+    });
+});
+
+describe("CLI: argument validation", () => {
+    it("rejects --port 99999 (out of range)", async () => {
+        const { stderr, code } = await runCli(["--port", "99999"]);
+        expect(stderr).toContain("Invalid port");
+        expect(code).toBe(1);
+    });
+
+    it("rejects --port=-1 (negative)", async () => {
+        const { stderr, code } = await runCli(["--port=-1"]);
+        expect(stderr).toContain("Invalid port");
+        expect(code).toBe(1);
+    });
+
+    it("rejects --latency=-5 (negative)", async () => {
+        const { stderr, code } = await runCli(["--latency=-5"]);
+        expect(stderr).toContain("Invalid latency");
+        expect(code).toBe(1);
+    });
+
+    it("rejects --chunk-size 0 (below minimum)", async () => {
+        const { stderr, code } = await runCli(["--chunk-size", "0"]);
+        expect(stderr).toContain("Invalid chunk-size");
+        expect(code).toBe(1);
+    });
+});
+
+describe("CLI: fixture loading", () => {
+    let tmpDir: string;
+
+    beforeEach(() => {
+        tmpDir = makeTmpDir();
+    });
+
+    afterEach(() => {
+        rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it("starts server with a valid fixture file, then exits cleanly on SIGTERM", async () => {
+        const fixturePath = writeFixture(tmpDir, "test.json");
+        const child = spawnCli(["--fixtures", fixturePath, "--port", "0"]);
+
+        await child.waitForOutput(/listening on/i, 5000);
+        expect(child.stdout()).toContain("Loaded 1 fixture(s)");
+
+        child.kill("SIGTERM");
+
+        await new Promise<void>((resolve) => {
+            child.cp.on("close", (code) => {
+                expect(code).toBe(0);
+                resolve();
+            });
+        });
+    });
+
+    it("fails with error when --fixtures points to a non-existent path", async () => {
+        const { stderr, code } = await runCli(["--fixtures", "/nonexistent/path/to/fixtures"]);
+        expect(stderr).toContain("Fixtures path not found");
+        expect(code).toBe(1);
+    });
+});

src/__tests__/fixture-loader.test.ts

@@ -4,6 +4,27 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { loadFixtureFile, loadFixturesFromDir } from "../fixture-loader.js";
 
+/* ------------------------------------------------------------------ *
+ * vi.mock for node:fs — defaults to the real implementation so that  *
+ * every test using real files keeps working.  Individual tests in    *
+ * the "fs error paths" describe block override specific functions.   *
+ * ------------------------------------------------------------------ */
+const fsMocks = vi.hoisted(() => ({
+  readFileSync: vi.fn(),
+  readdirSync: vi.fn(),
+  statSync: vi.fn(),
+}));
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return {
+    ...actual,
+    readFileSync: fsMocks.readFileSync.mockImplementation(actual.readFileSync),
+    readdirSync: fsMocks.readdirSync.mockImplementation(actual.readdirSync),
+    statSync: fsMocks.statSync.mockImplementation(actual.statSync),
+  };
+});
+
 function makeTmpDir(): string {
   return mkdtempSync(join(tmpdir(), "fixture-loader-test-"));
 }
@@ -256,3 +277,85 @@ describe("loadFixturesFromDir", () => {
     warn.mockRestore();
   });
 });
+
+/* ------------------------------------------------------------------ *
+ * fs error paths (uses the vi.mock overrides declared at top level)  *
+ * ------------------------------------------------------------------ */
+describe("fixture-loader fs error paths", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("loadFixtureFile warns and returns empty when readFileSync throws EACCES", () => {
+    fsMocks.readFileSync.mockImplementation(() => {
+      const err = new Error("permission denied") as NodeJS.ErrnoException;
+      err.code = "EACCES";
+      throw err;
+    });
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const result = loadFixtureFile("/some/protected-file.json");
+    expect(result).toHaveLength(0);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("Could not read file"),
+      expect.anything(),
+    );
+  });
+
+  it("loadFixturesFromDir silently skips a file when statSync throws ENOENT", () => {
+    fsMocks.readdirSync.mockReturnValue(["a.json", "vanished.json", "b.json"]);
+    fsMocks.statSync.mockImplementation((p: unknown) => {
+      if (String(p).includes("vanished.json")) {
+        const err = new Error("no such file") as NodeJS.ErrnoException;
+        err.code = "ENOENT";
+        throw err;
+      }
+      return { isDirectory: () => false };
+    });
+    fsMocks.readFileSync.mockImplementation((p: unknown) => {
+      return JSON.stringify({
+        fixtures: [{ match: { userMessage: String(p) }, response: { content: "ok" } }],
+      });
+    });
+
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const result = loadFixturesFromDir("/fake/dir");
+
+    // vanished.json is silently skipped (ENOENT is not warned about per the source)
+    expect(result).toHaveLength(2);
+
+    const statWarns = warn.mock.calls.filter(
+      (c) => typeof c[0] === "string" && c[0].includes("Could not stat"),
+    );
+    expect(statWarns).toHaveLength(0);
+  });
+
+  it("loadFixturesFromDir warns when statSync throws a non-ENOENT error (e.g. EACCES)", () => {
+    fsMocks.readdirSync.mockReturnValue(["ok.json", "noperm.json"]);
+    fsMocks.statSync.mockImplementation((p: unknown) => {
+      if (String(p).includes("noperm.json")) {
+        const err = new Error("permission denied") as NodeJS.ErrnoException;
+        err.code = "EACCES";
+        throw err;
+      }
+      return { isDirectory: () => false };
+    });
+    fsMocks.readFileSync.mockImplementation(() => {
+      return JSON.stringify({
+        fixtures: [{ match: { userMessage: "x" }, response: { content: "y" } }],
+      });
+    });
+
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const result = loadFixturesFromDir("/fake/dir");
+
+    // noperm.json is skipped but a warning IS emitted for non-ENOENT errors
+    expect(result).toHaveLength(1);
+
+    const statWarns = warn.mock.calls.filter(
+      (c) => typeof c[0] === "string" && c[0].includes("Could not stat"),
+    );
+    expect(statWarns).toHaveLength(1);
+    expect(statWarns[0][0]).toContain("noperm.json");
+  });
+});

src/__tests__/helpers.test.ts

@@ -92,6 +92,48 @@ describe("buildTextChunks", () => {
       expect(chunk.model).toBe("gpt-4o-mini");
     }
   });
+
+  it("produces role + finish with no content chunks for empty string", () => {
+    const chunks = buildTextChunks("", "gpt-4", 20);
+    expect(chunks.length).toBe(2); // role + finish only
+
+    // Role chunk
+    expect(chunks[0].choices[0].delta.role).toBe("assistant");
+    expect(chunks[0].choices[0].delta.content).toBe("");
+    expect(chunks[0].choices[0].finish_reason).toBeNull();
+
+    // Finish chunk
+    expect(chunks[1].choices[0].delta).toEqual({});
+    expect(chunks[1].choices[0].finish_reason).toBe("stop");
+  });
+
+  it("produces a single content chunk for a single character", () => {
+    const chunks = buildTextChunks("a", "gpt-4", 20);
+    expect(chunks.length).toBe(3); // role + "a" + finish
+
+    expect(chunks[1].choices[0].delta.content).toBe("a");
+  });
+
+  it("preserves unicode multibyte content through chunking and reassembly", () => {
+    const chunks = buildTextChunks("Hello 🌍🎉", "gpt-4", 3);
+
+    // Reassemble all content chunks — slice() splits on UTF-16 code units,
+    // so individual chunks may contain lone surrogates, but concatenation
+    // must reproduce the original string.
+    const contentChunks = chunks.slice(1, -1); // skip role and finish
+    const reassembled = contentChunks.map((c) => c.choices[0].delta.content).join("");
+    expect(reassembled).toBe("Hello 🌍🎉");
+
+    // "Hello 🌍🎉" is 10 UTF-16 code units, so ceil(10/3) = 4 content chunks
+    expect(contentChunks.length).toBe(4);
+  });
+
+  it("produces a single content chunk when content is shorter than chunkSize", () => {
+    const chunks = buildTextChunks("hi", "gpt-4", 100);
+    expect(chunks.length).toBe(3); // role + "hi" + finish
+
+    expect(chunks[1].choices[0].delta.content).toBe("hi");
+  });
 });
 
 describe("buildToolCallChunks", () => {
@@ -170,4 +212,60 @@ describe("buildToolCallChunks", () => {
     const initial = chunks.find((c) => c.choices[0].delta.tool_calls?.[0]?.id);
     expect(initial!.choices[0].delta.tool_calls![0].id).toBe("call_custom123");
   });
+
+  it("handles empty arguments string with role + initial + finish", () => {
+    const chunks = buildToolCallChunks(
+      [{ name: "fn", arguments: "" }],
+      "gpt-4",
+      20,
+    );
+    // role + initial tool call chunk + finish = 3 (no arg chunks since args is empty)
+    expect(chunks.length).toBe(3);
+
+    // Role chunk
+    expect(chunks[0].choices[0].delta.role).toBe("assistant");
+    expect(chunks[0].choices[0].delta.content).toBeNull();
+
+    // Initial tool call chunk
+    const tc = chunks[1].choices[0].delta.tool_calls;
+    expect(tc).toBeDefined();
+    expect(tc![0].function?.name).toBe("fn");
+    expect(tc![0].function?.arguments).toBe("");
+
+    // Finish chunk
+    expect(chunks[2].choices[0].delta).toEqual({});
+    expect(chunks[2].choices[0].finish_reason).toBe("tool_calls");
+  });
+
+  it("handles empty toolCalls array with role + finish only", () => {
+    const chunks = buildToolCallChunks([], "gpt-4", 20);
+    expect(chunks.length).toBe(2); // role + finish
+
+    // Role chunk
+    expect(chunks[0].choices[0].delta.role).toBe("assistant");
+    expect(chunks[0].choices[0].delta.content).toBeNull();
+    expect(chunks[0].choices[0].finish_reason).toBeNull();
+
+    // Finish chunk
+    expect(chunks[1].choices[0].delta).toEqual({});
+    expect(chunks[1].choices[0].finish_reason).toBe("tool_calls");
+  });
+
+  it("produces a single arg chunk when arguments are shorter than chunkSize", () => {
+    const chunks = buildToolCallChunks(
+      [{ name: "fn", arguments: '{"x":1}' }],
+      "gpt-4",
+      100,
+    );
+    // role + initial + 1 arg chunk + finish = 4
+    expect(chunks.length).toBe(4);
+
+    const argChunks = chunks.filter(
+      (c) =>
+        c.choices[0].delta.tool_calls?.[0].function?.arguments !== undefined &&
+        c.choices[0].delta.tool_calls?.[0].function?.arguments !== "",
+    );
+    expect(argChunks.length).toBe(1);
+    expect(argChunks[0].choices[0].delta.tool_calls![0].function!.arguments).toBe('{"x":1}');
+  });
 });