/** * agent-api 單元測試(AF6) * * 驗證重點: * 1. Wails runtime 偵測:window.go 不存在時走 mock、存在時呼叫 real binding * 2. Go DTO → TS 介面的轉換(特別是 int64 ms → ISO string) * 3. Go error 字串 → PairErrorCode 的解析 * 4. Event 訂閱:wails 環境下 EventsOn 被呼叫、mock 環境下為 no-op * * 不測試: * - Wails 內部序列化行為(由 Wails runtime 保證) * - 實際網路 handshake(那是 Go 側責任) */ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import type { ConnectionSnapshot } from "@/types/agent"; import { __isWailsRuntimeForTest, __resetMockForTest, agentAPI, onConnectionStatus, } from "./agent-api"; /* -------------------------------------------------------------------------- */ /* 測試工具:安裝假的 window.go / window.runtime */ /* -------------------------------------------------------------------------- */ interface FakeBinding { GetConnectionStatus: ReturnType; Pair: ReturnType; Unpair: ReturnType; Reconnect: ReturnType; Disconnect: ReturnType; GetAgentSettings: ReturnType; SaveAgentSettings: ReturnType; TestConnection: ReturnType; ResetAllSettings: ReturnType; GetRecentLogs: ReturnType; ExportLog: ReturnType; } function installFakeWails(): { binding: FakeBinding; eventsOn: ReturnType; eventsOff: ReturnType; browserOpenURL: ReturnType; } { const binding: FakeBinding = { GetConnectionStatus: vi.fn(), Pair: vi.fn(), Unpair: vi.fn(), Reconnect: vi.fn(), Disconnect: vi.fn(), GetAgentSettings: vi.fn(), SaveAgentSettings: vi.fn(), TestConnection: vi.fn(), ResetAllSettings: vi.fn(), GetRecentLogs: vi.fn(), ExportLog: vi.fn(), }; const eventsOn = vi.fn(() => vi.fn()); // EventsOn 回傳取消訂閱函式 const eventsOff = vi.fn(); const browserOpenURL = vi.fn(); // jsdom 環境:把假的 go / runtime 直接塞到 window (window as unknown as { go: unknown }).go = { main: { App: binding } }; (window as unknown as { runtime: unknown }).runtime = { EventsOn: eventsOn, EventsOff: eventsOff, BrowserOpenURL: browserOpenURL, }; return { binding, eventsOn, eventsOff, browserOpenURL }; } function uninstallFakeWails() { delete (window as unknown as { go?: unknown }).go; delete (window as unknown as { runtime?: unknown }).runtime; } /* -------------------------------------------------------------------------- */ /* 測試:Mock 路徑(window.go 不存在) */ /* -------------------------------------------------------------------------- */ describe("agentAPI — Mock 路徑(瀏覽器 dev 模式)", () => { beforeEach(() => { uninstallFakeWails(); __resetMockForTest(); }); it("偵測到無 Wails runtime", () => { expect(__isWailsRuntimeForTest()).toBe(false); }); it("getConnectionStatus 回 notPaired 預設值", async () => { const snap = await agentAPI.getConnectionStatus(); expect(snap.state).toBe("notPaired"); expect(snap.relayUrl).toContain("wss://"); }); it("pair 接受合法 token 後 resolve", async () => { const validToken = "vAc_" + "a".repeat(32); await expect(agentAPI.pair(validToken)).resolves.toBeUndefined(); }); it("pair 收到格式錯誤的 token 時 reject 帶 PairError", async () => { await expect(agentAPI.pair("not-a-valid-token")).rejects.toMatchObject({ code: "token_invalid", }); }); it("testConnection 驗證 URL 協議", async () => { const ok = await agentAPI.testConnection("wss://relay.example.com"); expect(ok.ok).toBe(true); expect(ok.latencyMs).toBeTypeOf("number"); const bad = await agentAPI.testConnection("http://not-ws"); expect(bad.ok).toBe(false); expect(bad.reason).toContain("ws://"); }); it("saveAgentSettings / getAgentSettings 能來回讀寫", async () => { const patched = { relayUrl: "wss://custom.test", autoStart: true, reconnectStrategy: "manual" as const, logLevel: "debug" as const, }; await agentAPI.saveAgentSettings(patched); const read = await agentAPI.getAgentSettings(); expect(read).toEqual(patched); }); it("getRecentLogs 回空陣列(Phase 0 mock)", async () => { const logs = await agentAPI.getRecentLogs(10); expect(logs).toEqual([]); }); it("exportLog 回 mock path", async () => { const path = await agentAPI.exportLog(); expect(path).toMatch(/\.zip$/); }); it("openURL(mock 環境)退到 window.open,noopener noreferrer", () => { // Fix-F3:mock 環境沒 Wails runtime → fallback window.open const spy = vi.spyOn(window, "open").mockImplementation(() => null); agentAPI.openURL("https://example.com"); expect(spy).toHaveBeenCalledWith( "https://example.com", "_blank", "noopener,noreferrer", ); spy.mockRestore(); }); it("onConnectionStatus 回 no-op unsubscribe,callback 永遠不被呼叫", () => { const cb = vi.fn(); const off = onConnectionStatus(cb); expect(typeof off).toBe("function"); expect(() => off()).not.toThrow(); expect(cb).not.toHaveBeenCalled(); }); }); /* -------------------------------------------------------------------------- */ /* 測試:Real 路徑(window.go 存在) */ /* -------------------------------------------------------------------------- */ describe("agentAPI — Real 路徑(Wails runtime 模擬)", () => { let binding: FakeBinding; let eventsOn: ReturnType; let browserOpenURL: ReturnType; beforeEach(() => { const fake = installFakeWails(); binding = fake.binding; eventsOn = fake.eventsOn; browserOpenURL = fake.browserOpenURL; }); afterEach(() => { uninstallFakeWails(); }); it("偵測到 Wails runtime", () => { expect(__isWailsRuntimeForTest()).toBe(true); }); it("getConnectionStatus 呼叫 Go binding 並轉 ms → ISO", async () => { const goMs = 1_700_000_000_000; binding.GetConnectionStatus.mockResolvedValue({ state: "online", relayUrl: "wss://relay.test", connectedSince: goMs, sessionTokenPreview: "vAs_abc ··· def", }); const snap: ConnectionSnapshot = await agentAPI.getConnectionStatus(); expect(binding.GetConnectionStatus).toHaveBeenCalledOnce(); expect(snap.state).toBe("online"); expect(snap.connectedSince).toBe(new Date(goMs).toISOString()); expect(snap.sessionTokenPreview).toBe("vAs_abc ··· def"); }); it("getConnectionStatus 把未知 state 收斂到 error", async () => { binding.GetConnectionStatus.mockResolvedValue({ state: "weird-unknown-value", relayUrl: "wss://relay.test", }); const snap = await agentAPI.getConnectionStatus(); expect(snap.state).toBe("error"); }); it("getConnectionStatus 不帶 connectedSince 時欄位省略", async () => { binding.GetConnectionStatus.mockResolvedValue({ state: "notPaired", relayUrl: "wss://relay.test", }); const snap = await agentAPI.getConnectionStatus(); expect(snap.connectedSince).toBeUndefined(); }); it("pair 成功時 resolve", async () => { binding.Pair.mockResolvedValue(undefined); await expect(agentAPI.pair("vAc_abc")).resolves.toBeUndefined(); expect(binding.Pair).toHaveBeenCalledWith("vAc_abc"); }); it.each([ ["pairing token expired", "token_expired"], ["pairing token already used", "token_used"], ["pairing token revoked", "token_revoked"], ["pairing token invalid", "token_invalid"], ["invalid pairing token format (expected vAc_ + 32 hex)", "token_invalid"], ["websocket dial: connection refused", "relay_unreachable"], ["network timeout", "network_error"], ["something else entirely", "unknown"], ])("pair Go error %q → code %q", async (goMsg, expectedCode) => { binding.Pair.mockRejectedValue(new Error(goMsg)); try { await agentAPI.pair("vAc_xxx"); throw new Error("should have rejected"); } catch (err) { expect(err).toMatchObject({ code: expectedCode }); } }); it("testConnection 透傳 Go 結果", async () => { binding.TestConnection.mockResolvedValue({ ok: true, latencyMs: 30 }); const r = await agentAPI.testConnection("wss://test"); expect(r).toEqual({ ok: true, latencyMs: 30, reason: undefined }); expect(binding.TestConnection).toHaveBeenCalledWith("wss://test"); }); it("saveAgentSettings 透傳整包 settings 給 Go", async () => { binding.SaveAgentSettings.mockResolvedValue(undefined); const patch = { relayUrl: "wss://new", autoStart: true, reconnectStrategy: "manual" as const, logLevel: "debug" as const, }; await agentAPI.saveAgentSettings(patch); expect(binding.SaveAgentSettings).toHaveBeenCalledWith(patch); }); it("exportLog 透傳 Go 回的 path", async () => { binding.ExportLog.mockResolvedValue("/tmp/export.zip"); const path = await agentAPI.exportLog(); expect(path).toBe("/tmp/export.zip"); }); it("openURL(Wails 環境)呼叫 runtime.BrowserOpenURL", () => { // Fix-F3:Wails 環境下走 BrowserOpenURL,不該打到 window.open const winOpenSpy = vi.spyOn(window, "open").mockImplementation(() => null); agentAPI.openURL("https://docs.visionA.cloud/agent"); expect(browserOpenURL).toHaveBeenCalledWith("https://docs.visionA.cloud/agent"); expect(winOpenSpy).not.toHaveBeenCalled(); winOpenSpy.mockRestore(); }); it("onConnectionStatus 訂閱 Wails event", () => { const cb = vi.fn(); onConnectionStatus(cb); expect(eventsOn).toHaveBeenCalledWith( "connection:status", expect.any(Function), ); }); it("onConnectionStatus 收到 Go payload 會轉成 TS snapshot 後呼 callback", () => { const cb = vi.fn(); onConnectionStatus(cb); const wailsHandler = eventsOn.mock.calls[0][1] as ( ...data: unknown[] ) => void; // 模擬 Wails 推一個 payload(spread 參數進來) wailsHandler({ state: "online", relayUrl: "wss://r", connectedSince: 1_700_000_000_000, }); expect(cb).toHaveBeenCalledOnce(); const snap = cb.mock.calls[0][0] as ConnectionSnapshot; expect(snap.state).toBe("online"); expect(snap.connectedSince).toBe( new Date(1_700_000_000_000).toISOString(), ); }); });