// Repository request-shape tests: the templates catalogue and the validate // command, driven through the real transport against a fake WebSocket so the // exact frames sent (and the error-envelope handling) are proven, not assumed. import { test } from "node:test"; import assert from "node:assert/strict"; import { PipelinesClient, ProtocolError } from "../src/client.js"; import { PipelinesRepository } from "../src/repository.js"; import { validateServerUrl } from "../src/serverUrl.js"; const VALID = validateServerUrl("ws://host:8080/connect"); /** The same minimal fake the client tests use (test files are not importable). */ class FakeWebSocket { static instances = []; constructor(url) { this.url = url; this.sent = []; this.onopen = null; this.onmessage = null; this.onclose = null; this.onerror = null; this.reply = null; FakeWebSocket.instances.push(this); } send(data) { const frame = JSON.parse(data); this.sent.push(frame); const response = this.reply?.(frame); if (response !== undefined) { this.onmessage?.({ data: JSON.stringify(response) }); } } close(code, reason) { this.onclose?.({ code, reason }); } open() { this.onopen?.({}); } } function connected() { FakeWebSocket.instances = []; const client = new PipelinesClient({ WebSocketImpl: FakeWebSocket }); const repo = new PipelinesRepository(client); client.connect(VALID); const ws = FakeWebSocket.instances.at(-1); ws.open(); return { repo, ws, client }; } /** The last frame without the client-generated id, for an exact shape assertion. */ function lastFrame(ws) { const { id, ...frame } = ws.sent.at(-1); assert.match(id, /^web-\d+$/); return frame; } test("listTemplates sends exactly {type:'list_templates'} and returns the catalogue", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "templates", templates: [{ key: "task", name: "Complete a task" }], }); const templates = await repo.listTemplates(); assert.deepEqual(lastFrame(ws), { type: "list_templates" }); assert.equal(templates.length, 1); assert.equal(templates[0].key, "task"); }); test("listTemplates returns [] when the reply carries no templates", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "templates" }); assert.deepEqual(await repo.listTemplates(), []); }); test("validate sends exactly {type:'validate', source} and returns response.graph", async () => { const { repo, ws } = connected(); const graph = { stages: [{ key: "plan" }] }; ws.reply = (frame) => ({ id: frame.id, type: "validated", graph }); const result = await repo.validate("the source"); assert.deepEqual(lastFrame(ws), { type: "validate", source: "the source" }); assert.deepEqual(result, graph); }); test("validate rejects a server error envelope with the server's text", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "error", error: "unexpected token" }); await assert.rejects(() => repo.validate("bad source"), { name: "ProtocolError", message: "unexpected token", }); }); test("validate throws when the reply has no graph", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "validated" }); await assert.rejects(() => repo.validate("empty"), ProtocolError); }); test("search sends exactly {type:'search',search:{query,kind:'',limit:0}} and returns search_results", async () => { const { repo, ws } = connected(); const payload = { query: "release", results: [{ kind: "run" }], cap: 50, scanned_steps: 3 }; ws.reply = (frame) => ({ id: frame.id, type: "search_results", search_results: payload }); const reply = await repo.search("release"); assert.deepEqual(lastFrame(ws), { type: "search", search: { query: "release", kind: "", limit: 0 }, }); assert.deepEqual(reply, payload); }); test("search sends the selected kind verbatim and never a limit above the cap", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "search_results", search_results: { results: [] } }); await repo.search("release", "run"); const { search } = lastFrame(ws); assert.deepEqual(search, { query: "release", kind: "run", limit: 0 }); // limit 0 asks for the server's own default (SearchDefaultLimit 50); the client // never asks for more than SearchMaxLimit (200), let alone sends a larger value. assert.ok(search.limit <= 200); }); test("search returns null when an older server replies without search_results", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "pong" }); assert.equal(await repo.search("release"), null); }); test("search surfaces an explicit server error with the server's own text", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "error", error: "unknown command: search" }); await assert.rejects(() => repo.search("release"), { name: "ProtocolError", message: "unknown command: search", }); }); /** The run detail a run.action reply carries in these tests. */ const RUN_DETAIL = { id: 440, status: "failed" }; test("decideRun sends exactly {type:'decide_run',run_id,option,feedback} and returns the run detail", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "run", run_detail: RUN_DETAIL }); const detail = await repo.decideRun(440, { stage: "review", option: "approve", feedback: " yes " }); assert.deepEqual(lastFrame(ws), { type: "decide_run", run_id: 440, stage: "review", option: "approve", feedback: "yes", }); assert.deepEqual(detail, RUN_DETAIL); }); test("decideRun omits a blank stage and blank feedback", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "run", run_detail: RUN_DETAIL }); await repo.decideRun(12, { stage: " ", option: "publish", feedback: " " }); assert.deepEqual(lastFrame(ws), { type: "decide_run", run_id: 12, option: "publish" }); }); test("cancelRun sends exactly {type:'cancel_run',run_id} and returns the run detail", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "run", run_detail: RUN_DETAIL }); const detail = await repo.cancelRun(440); assert.deepEqual(lastFrame(ws), { type: "cancel_run", run_id: 440 }); assert.deepEqual(detail, RUN_DETAIL); }); test("retryRun always sends request_key and omits retry_mode for the default resume", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "run_started", run_detail: RUN_DETAIL }); await repo.retryRun(440, { requestKey: "key-1" }); assert.deepEqual(lastFrame(ws), { type: "retry_run", run_id: 440, request_key: "key-1" }); }); test("retryRun sends retry_mode only for an explicit restart", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "run_started", run_detail: RUN_DETAIL }); await repo.retryRun(440, { mode: "restart", requestKey: "key-2" }); assert.deepEqual(lastFrame(ws), { type: "retry_run", run_id: 440, request_key: "key-2", retry_mode: "restart", }); }); test("setRunTitle sends exactly {type:'set_run_title',run_id,title} and returns the run detail", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "run", run_detail: RUN_DETAIL }); const detail = await repo.setRunTitle(440, "New title"); assert.deepEqual(lastFrame(ws), { type: "set_run_title", run_id: 440, title: "New title" }); assert.deepEqual(detail, RUN_DETAIL); }); test("each run action rejects a server error envelope instead of returning a detail", async () => { const calls = [ (repo) => () => repo.decideRun(440, { option: "approve" }), (repo) => () => repo.cancelRun(440), (repo) => () => repo.retryRun(440, { requestKey: "key-3" }), (repo) => () => repo.setRunTitle(440, ""), ]; for (const makeCall of calls) { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "error", error: "a title with usable text is required" }); await assert.rejects(makeCall(repo), { name: "ProtocolError", message: "a title with usable text is required", }); } }); test("a run action throws when the reply has no run detail", async () => { const { repo, ws } = connected(); ws.reply = (frame) => ({ id: frame.id, type: "run" }); await assert.rejects(() => repo.cancelRun(7), ProtocolError); });