Test boundaries and wiring

When writing tests, choose the boundary intentionally: validate user-/system-relevant behavior without brittle low-level mocking, and stub only external dependencies.

Practical rules:

• Prefer “real behavior” tests over mocking critical runtime plumbing (process spawning, log formats, etc.), especially when platform differences exist.
• If a bug happens in a multi-step state/render/wiring pipeline, don’t rely on helper-only/unit tests—test the composed behavior at the boundary where the bug manifests.
• For adapter/wiring coverage, run the real adapter code while stubbing external IO (e.g., network via fetch), then assert the request/response path.
• Stub at the correct abstraction layer to avoid hangs or leaked listeners (don’t feed never-ending streams if you can stub the terminal/process runner).
• Avoid brittle assertions on non-behavioral details (like exact log field payload shapes) when existing tests already exercise the behavioral path.
• Ensure tests enforce the actual correctness contract (e.g., don’t “flatten away” required plural categories; compare against the expected category sets).

Example pattern (adapter wiring):

it("wires request through the real adapter", async () => {
  const fetchStub = vi.fn(() => Promise.resolve(new Response(JSON.stringify({ text: "hi" }))));
  vi.stubGlobal("fetch", fetchStub);

  const result = await transcribeAudio({
    // real adapter used
    config: { type: "openai-native", model: "gpt-4o-mini-transcribe" },
    audio: /* ... */,
  });

  expect(fetchStub).toHaveBeenCalledWith(
    expect.stringContaining("/v1/audio/transcriptions"),
    expect.any(Object)
  );
  expect(result.text).toBe("hi");
});