Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* Hermetic tests for startup-trace.ts.
*
* Everything is injected via __configureStartupTraceForTests: a fake clock, a
* temp-dir output path, a captured stderr sink, an isolated env object, and
* small caps/thresholds. No real ~/.claudish file, no real timers needed for
* the timing-math tests, and no output escapes the test.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
SLOW_START_THRESHOLD_MS,
STARTUP_METRICS_MAX_LINES,
type StartupTracePayload,
__configureStartupTraceForTests,
__getStartupSpansForTests,
__resetStartupTraceForTests,
addSpanMeta,
beginQueuedSpan,
beginSpan,
finalizeStartupTrace,
setStartupAuthKind,
suppressStartupTraceTerminalOutput,
traceSpan,
} from "./startup-trace.js";
let tmpDir: string;
let outPath: string;
let stderrLines: string[];
let t: number; // fake clock (ms since "process start")
/** Configure the trace with the fake clock + captured stderr + temp path. */
function configure(
overrides: { env?: NodeJS.ProcessEnv; slowThresholdMs?: number; maxLines?: number } = {}
): void {
__configureStartupTraceForTests({
now: () => t,
outPath,
env: overrides.env ?? {},
stderr: (line) => stderrLines.push(line),
slowThresholdMs: overrides.slowThresholdMs ?? SLOW_START_THRESHOLD_MS,
maxLines: overrides.maxLines ?? STARTUP_METRICS_MAX_LINES,
});
}
function readPayloads(): StartupTracePayload[] {
return readFileSync(outPath, "utf-8")
.split("\n")
.filter((l) => l.trim() !== "")
.map((l) => JSON.parse(l) as StartupTracePayload);
}
beforeEach(() => {
tmpDir = mkdtempSync(join(tmpdir(), "claudish-startup-trace-"));
outPath = join(tmpDir, "startup-metrics.jsonl");
stderrLines = [];
t = 0;
configure();
});
afterEach(() => {
__resetStartupTraceForTests();
rmSync(tmpDir, { recursive: true, force: true });
});
describe("traceSpan timing math (injected clock)", () => {
test("sync fn: records start/duration and returns the value", () => {
t = 100;
const out = traceSpan("phase:sync", () => {
t = 350;
return 42;
});
expect(out).toBe(42);
const spans = __getStartupSpansForTests();
expect(spans).toHaveLength(1);
expect(spans[0].name).toBe("phase:sync");
expect(spans[0].startMs).toBe(100);
expect(spans[0].durMs).toBe(250);
});
test("async fn: records when the promise settles", async () => {
t = 10;
const out = await traceSpan("phase:async", async () => {
t = 1010;
return "done";
});
expect(out).toBe("done");
const spans = __getStartupSpansForTests();
expect(spans).toHaveLength(1);
expect(spans[0].startMs).toBe(10);
expect(spans[0].durMs).toBe(1000);
});
test("meta is attached to the span", () => {
traceSpan("phase:meta", () => 1, { providers: 16, mayIncludeUserPrompt: true });
const [span] = __getStartupSpansForTests();
expect(span.meta).toEqual({ providers: 16, mayIncludeUserPrompt: true });
});
test("a throwing sync fn propagates AND records an error span", () => {
expect(() =>
traceSpan("phase:boom", () => {
t = 5;
throw new Error("locked: user denied\nsecond line never logged");
})
).toThrow("locked");
const [span] = __getStartupSpansForTests();
expect(span.name).toBe("phase:boom");
expect(span.meta?.error).toBe(true);
expect(span.meta?.errorMsg).toBe("locked: user denied"); // first line only
});
test("a rejecting async fn propagates AND records an error span", async () => {
await expect(
traceSpan("phase:reject", async () => {
t = 77;
throw new Error("1Password desktop app is locked");
})
).rejects.toThrow("locked");
const [span] = __getStartupSpansForTests();
expect(span.durMs).toBe(77);
expect(span.meta?.error).toBe(true);
expect(String(span.meta?.errorMsg)).toContain("locked");
});
});
describe("beginSpan / beginQueuedSpan", () => {
test("beginSpan: manual end with extra meta; end is idempotent", () => {
t = 0;
const end = beginSpan("phase:manual", { stage: "imports" });
t = 500;
end({ modules: 9 });
t = 900;
end(); // second end must be a no-op
const spans = __getStartupSpansForTests();
expect(spans).toHaveLength(1);
expect(spans[0].durMs).toBe(500);
expect(spans[0].meta).toEqual({ stage: "imports", modules: 9 });
});
test("beginQueuedSpan: records queue-wait vs exec split", () => {
t = 0;
const span = beginQueuedSpan("op:resolve(GEMINI_API_KEY)");
t = 4000; // waited 4s behind the queue
span.start();
t = 9100; // executed for 5.1s
span.end();
const [s] = __getStartupSpansForTests();
expect(s.startMs).toBe(0);
expect(s.durMs).toBe(9100);
expect(s.meta?.waitMs).toBe(4000);
expect(s.meta?.execMs).toBe(5100);
});
test("beginQueuedSpan: end without start counts everything as wait", () => {
t = 0;
const span = beginQueuedSpan("op:never-started");
t = 300;
span.end({ error: true });
const [s] = __getStartupSpansForTests();
expect(s.meta?.waitMs).toBe(300);
expect(s.meta?.execMs).toBe(0);
expect(s.meta?.error).toBe(true);
});
});
describe("addSpanMeta", () => {
test("merges into the MOST RECENT span with the name", () => {
traceSpan("op:x", () => 1, { attempt: 1 });
traceSpan("op:x", () => 2, { attempt: 2 });
addSpanMeta("op:x", { attempts: 2, retried: true });
const spans = __getStartupSpansForTests();
expect(spans[0].meta).toEqual({ attempt: 1 });
expect(spans[1].meta).toEqual({ attempt: 2, attempts: 2, retried: true });
});
test("no-op when no span has that name", () => {
addSpanMeta("op:missing", { attempts: 3 });
expect(__getStartupSpansForTests()).toHaveLength(0);
});
});
describe("finalize → JSONL", () => {
test("appends one parseable line with all payload fields", () => {
traceSpan("phase:a", () => {
t = 120;
});
setStartupAuthKind("desktop");
t = 500;
finalizeStartupTrace("config");
const [payload] = readPayloads();
expect(payload.argvKind).toBe("config");
expect(payload.totalMs).toBe(500);
expect(payload.authKind).toBe("desktop");
expect(typeof payload.version).toBe("string");
expect(new Date(payload.ts).toString()).not.toBe("Invalid Date");
expect(payload.spans).toHaveLength(1);
expect(payload.spans[0].name).toBe("phase:a");
});
test("authKind defaults to none", () => {
finalizeStartupTrace("run");
expect(readPayloads()[0].authKind).toBe("none");
});
test("finalize is idempotent — only the first call writes", () => {
finalizeStartupTrace("run");
finalizeStartupTrace("run");
finalizeStartupTrace("other");
expect(readPayloads()).toHaveLength(1);
});
test("spans recorded AFTER finalize are dropped (env off)", () => {
finalizeStartupTrace("run");
traceSpan("post:finalize", () => 1);
expect(__getStartupSpansForTests()).toHaveLength(0);
expect(stderrLines).toHaveLength(0);
});
test("line cap: oldest lines are dropped on overflow", () => {
configure({ maxLines: 3 });
writeFileSync(
outPath,
`${["one", "two", "three", "four"].map((n) => JSON.stringify({ old: n })).join("\n")}\n`
);
finalizeStartupTrace("run");
const lines = readFileSync(outPath, "utf-8")
.split("\n")
.filter((l) => l.trim() !== "");
expect(lines).toHaveLength(3);
expect(lines[0]).toBe(JSON.stringify({ old: "three" })); // one+two dropped
expect(JSON.parse(lines[2]).argvKind).toBe("run"); // newest is ours
});
});
describe("slow-start threshold gating", () => {
// There is no automatic slow line: interactive startup:model-select can dominate
// totalMs with the time the user spends reading and choosing from the model picker.
test("below threshold → silent (JSONL still written)", () => {
t = 2000;
finalizeStartupTrace("run");
expect(stderrLines).toHaveLength(0);
expect(readPayloads()).toHaveLength(1);
});
test("far above the old threshold → silent (JSONL still preserves timing data)", () => {
t = 0;
traceSpan("op:vaults.list", () => {
t = 900;
});
const q = beginQueuedSpan("op:items.list");
t = 5000;
q.start();
t = 10100;
q.end(); // 9.2s total: wait 4.1s (5000-900), exec 5.1s — dominant span
traceSpan("op:client-handshake", () => {
t = 18300;
}); // 8.2s
traceSpan("op:sdk-wasm-import", () => {
t = 21400;
}); // 3.1s
t = 31200;
finalizeStartupTrace("config");
expect(stderrLines).toHaveLength(0);
const [payload] = readPayloads();
expect(payload.totalMs).toBe(31200);
expect(payload.spans).toEqual([
{ name: "op:vaults.list", startMs: 0, durMs: 900 },
{
name: "op:items.list",
startMs: 900,
durMs: 9200,
meta: { waitMs: 4100, execMs: 5100 },
},
{ name: "op:client-handshake", startMs: 10100, durMs: 8200 },
{ name: "op:sdk-wasm-import", startMs: 18300, durMs: 3100 },
]);
});
test("quiet:true remains silent (JSONL still written)", () => {
t = 20000;
finalizeStartupTrace("run", { quiet: true });
expect(stderrLines).toHaveLength(0);
expect(readPayloads()).toHaveLength(1); // data still captured
});
test("crossing an injected threshold remains silent", () => {
configure({ slowThresholdMs: 100 });
t = 150;
finalizeStartupTrace("run");
expect(stderrLines).toHaveLength(0);
expect(readPayloads()[0].totalMs).toBe(150);
});
});
describe("CLAUDISH_STARTUP_TRACE=1 full table + live detail", () => {
test("finalize prints the aligned phase table", () => {
configure({ env: { CLAUDISH_STARTUP_TRACE: "1" } });
traceSpan("startup:parse-args", () => {
t = 42;
});
const q = beginQueuedSpan("op:resolve(GEMINI_API_KEY)");
t = 100;
q.start();
t = 9000;
q.end();
t = 30000; // way past the old threshold — trace mode still prints the table
finalizeStartupTrace("config");
const all = stderrLines.join("\n");
expect(all).toContain("startup trace (config)");
expect(all).toContain("total 30.0s");
expect(all).toContain("startup:parse-args");
expect(all).toContain("op:resolve(GEMINI_API_KEY) (wait 58ms + exec 8.9s)"); // enqueued t=42
expect(all).not.toContain("slow start");
});
test("post-finalize spans live-print when trace mode is on", () => {
configure({ env: { CLAUDISH_STARTUP_TRACE: "1" } });
finalizeStartupTrace("config");
stderrLines.length = 0;
t = 0;
traceSpan("tui:load-fields", () => {
t = 234;
});
expect(stderrLines).toHaveLength(1);
expect(stderrLines[0]).toContain("[startup-trace] tui:load-fields 234ms");
});
});
describe("suppressStartupTraceTerminalOutput — the TUI owns the terminal", () => {
test("after suppression, a span produces ZERO terminal writes but IS still recorded", () => {
// Trace mode ON — the worst case: without suppression this live-prints.
configure({ env: { CLAUDISH_STARTUP_TRACE: "1" } });
finalizeStartupTrace("config"); // pre-mount finalize (table prints — allowed)
stderrLines.length = 0;
suppressStartupTraceTerminalOutput(); // right before the TUI mounts
t = 0;
traceSpan("tui:load-fields", () => {
t = 381;
});
const q = beginQueuedSpan("op:resolve(OLLAMA_API_KEY)");
q.start();
t = 5300;
q.end();
// NOTHING hit the terminal — these lines would overwrite TUI rows.
expect(stderrLines).toHaveLength(0);
// …but the spans were NOT dropped: they're in the buffer.
const names = __getStartupSpansForTests().map((s) => s.name);
expect(names).toContain("tui:load-fields");
expect(names).toContain("op:resolve(OLLAMA_API_KEY)");
});
test("suppressed spans are mirrored to an injected log sink (the --debug logger seam)", () => {
configure({ env: { CLAUDISH_STARTUP_TRACE: "1" } });
finalizeStartupTrace("config");
stderrLines.length = 0;
const logLines: string[] = [];
suppressStartupTraceTerminalOutput({ logSink: (line) => logLines.push(line) });
t = 0;
traceSpan("tui:confirm-add", () => {
t = 1200;
});
expect(stderrLines).toHaveLength(0); // terminal stays untouched
expect(logLines).toHaveLength(1); // full detail goes to the log file
expect(logLines[0]).toContain("[startup-trace] tui:confirm-add 1.2s");
});
test("a late finalize after suppression prints nothing (JSONL still written)", () => {
// Defensive path: suppression arrives BEFORE finalize (e.g. the exit hook
// finalizes after a TUI mounted). The table must not print.
configure({ env: { CLAUDISH_STARTUP_TRACE: "1" } });
suppressStartupTraceTerminalOutput();
t = 30000; // way past the slow threshold, and trace mode is on
finalizeStartupTrace("config");
expect(stderrLines).toHaveLength(0);
expect(readPayloads()).toHaveLength(1); // the metrics line still landed
});
test("a throwing log sink never breaks the traced code path", () => {
configure({ env: {} });
finalizeStartupTrace("config");
suppressStartupTraceTerminalOutput({
logSink: () => {
throw new Error("log file closed");
},
});
expect(traceSpan("tui:anything", () => "ok")).toBe("ok");
expect(stderrLines.filter((l) => l.includes("startup-trace"))).toHaveLength(0);
});
test("pre-suppression behavior is unchanged (post-finalize live print still works)", () => {
configure({ env: { CLAUDISH_STARTUP_TRACE: "1" } });
finalizeStartupTrace("config");
stderrLines.length = 0;
traceSpan("tui:before-suppress", () => {
t = 10;
});
expect(stderrLines).toHaveLength(1); // live print until suppression is invoked
});
});
describe("never throws (tracing failures can't break startup)", () => {
test("unwritable output path → finalize returns, startup continues", () => {
// Parent "directory" is a FILE → mkdir + write both fail.
const blocker = join(tmpDir, "blocker");
writeFileSync(blocker, "i am a file");
__configureStartupTraceForTests({
now: () => t,
outPath: join(blocker, "nested", "metrics.jsonl"),
env: {},
stderr: (line) => stderrLines.push(line),
});
t = 20000;
expect(() => finalizeStartupTrace("run")).not.toThrow();
expect(stderrLines).toHaveLength(0);
expect(existsSync(join(blocker, "nested"))).toBe(false);
});
test("a broken injected clock never breaks the traced fn", () => {
__configureStartupTraceForTests({
now: () => {
throw new Error("clock exploded");
},
outPath,
env: {},
stderr: () => {},
});
expect(traceSpan("phase:x", () => "value")).toBe("value");
expect(() => finalizeStartupTrace("run")).not.toThrow();
});
test("a broken stderr sink never breaks finalize", () => {
__configureStartupTraceForTests({
now: () => t,
outPath,
env: { CLAUDISH_STARTUP_TRACE: "1" },
stderr: () => {
throw new Error("stderr closed");
},
});
t = 30000;
expect(() => finalizeStartupTrace("run")).not.toThrow();
expect(readPayloads()).toHaveLength(1); // the JSONL write still landed
});
test("span buffer is capped (long-lived process protection)", () => {
for (let i = 0; i < 600; i++) traceSpan(`s${i}`, () => i);
expect(__getStartupSpansForTests().length).toBeLessThanOrEqual(500);
});
});