// @vitest-environment jsdom /** * test/terminal-session.test.ts — frontend TerminalSession unit tests. * * Runs under jsdom with a mock WebSocket and a stubbed xterm Terminal so we can * exercise the reconnect state machine, buildWsUrl scheme selection, the * disposed-guard on the initialInput timer (Phase 1#4 regression), hide() * cleanup, and status handling — without a real browser or server. */ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' // ── Stub xterm + addons (heavy DOM/canvas deps we don't need here) ──────────── class FakeTerminal { options: Record = {} cols = 80 rows = 24 parser = { registerOscHandler: vi.fn() } loadAddon = vi.fn() open = vi.fn() write = vi.fn() focus = vi.fn() dispose = vi.fn() private dataCbs: Array<(d: string) => void> = [] onData = (cb: (d: string) => void) => { this.dataCbs.push(cb) return { dispose: vi.fn() } } onTitleChange = vi.fn(() => ({ dispose: vi.fn() })) emitData(d: string): void { for (const cb of this.dataCbs) cb(d) } } vi.mock('@xterm/xterm', () => ({ Terminal: FakeTerminal })) vi.mock('@xterm/addon-fit', () => ({ FitAddon: class { fit = vi.fn() }, })) vi.mock('@xterm/addon-search', () => ({ SearchAddon: class { findNext = vi.fn() findPrevious = vi.fn() clearDecorations = vi.fn() }, })) vi.mock('@xterm/addon-web-links', () => ({ WebLinksAddon: class {} })) // ── Mock WebSocket ──────────────────────────────────────────────────────────── class MockWebSocket { static OPEN = 1 static instances: MockWebSocket[] = [] static last(): MockWebSocket { return MockWebSocket.instances[MockWebSocket.instances.length - 1]! } url: string readyState = 0 // CONNECTING sent: string[] = [] private listeners: Record void>> = {} constructor(url: string) { this.url = url MockWebSocket.instances.push(this) } addEventListener(type: string, cb: (e: unknown) => void): void { ;(this.listeners[type] ??= []).push(cb) } send(data: string): void { this.sent.push(data) } close(): void { this.readyState = 3 this.fire('close', {}) } // test helpers fire(type: string, e: unknown): void { for (const cb of this.listeners[type] ?? []) cb(e) } openIt(): void { this.readyState = MockWebSocket.OPEN this.fire('open', {}) } message(data: string): void { this.fire('message', { data }) } } // ResizeObserver is absent in jsdom. class FakeResizeObserver { observe = vi.fn() disconnect = vi.fn() constructor(_cb: () => void) {} } // ── Wire globals, then import the module under test ─────────────────────────── beforeEach(() => { MockWebSocket.instances = [] vi.stubGlobal('WebSocket', MockWebSocket) vi.stubGlobal('ResizeObserver', FakeResizeObserver) vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => { cb(0) return 0 }) }) afterEach(() => { vi.unstubAllGlobals() vi.useRealTimers() }) const { TerminalSession } = await import('../public/terminal-session.js') function setLocation(protocol: string, host: string): void { vi.stubGlobal('location', { protocol, host }) } describe('buildWsUrl scheme selection (M6)', () => { it('uses ws:// on http pages', () => { setLocation('http:', 'lan:3000') const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() expect(MockWebSocket.last().url).toBe('ws://lan:3000/term') }) it('uses wss:// on https pages (Tailscale/TLS, avoids mixed content)', () => { setLocation('https:', 'host.ts.net') const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() expect(MockWebSocket.last().url).toBe('wss://host.ts.net/term') }) }) describe('attach handshake', () => { beforeEach(() => setLocation('http:', 'lan:3000')) it('sends attach{sessionId:null} on open for a fresh session', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() MockWebSocket.last().openIt() expect(JSON.parse(MockWebSocket.last().sent[0]!)).toEqual({ type: 'attach', sessionId: null }) }) it('persists the assigned id from the attached frame', () => { const onSessionId = vi.fn() const s = new TerminalSession({ sessionId: null, onSessionId }) s.connect() MockWebSocket.last().openIt() MockWebSocket.last().message(JSON.stringify({ type: 'attached', sessionId: 'sid-1' })) expect(onSessionId).toHaveBeenCalledWith('sid-1') expect(s.id).toBe('sid-1') }) }) describe('status frame (H3 pending approval)', () => { beforeEach(() => setLocation('http:', 'lan:3000')) it('sets pendingApproval / claudeStatus from a status frame', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() MockWebSocket.last().openIt() MockWebSocket.last().message(JSON.stringify({ type: 'status', status: 'waiting', detail: 'Bash', pending: true })) expect(s.claudeStatus).toBe('waiting') expect(s.pendingApproval).toBe(true) expect(s.pendingTool).toBe('Bash') }) }) describe('reconnect backoff', () => { beforeEach(() => { setLocation('http:', 'lan:3000') vi.useFakeTimers() }) it('doubles the delay each attempt and caps at 30s', () => { const s = new TerminalSession({ sessionId: 'sid', onSessionId: vi.fn() }) s.connect() const delays: number[] = [] const origSetTimeout = globalThis.setTimeout vi.spyOn(globalThis, 'setTimeout').mockImplementation(((fn: () => void, ms?: number) => { delays.push(ms ?? 0) return origSetTimeout(fn, 0) }) as typeof setTimeout) // Simulate repeated close→reconnect cycles. for (let i = 0; i < 7; i++) { MockWebSocket.last().fire('close', {}) vi.runOnlyPendingTimers() } // First delay 1000, then 2000, 4000 … capped at 30000. expect(delays[0]).toBe(1000) expect(delays[1]).toBe(2000) expect(delays[2]).toBe(4000) expect(Math.max(...delays)).toBeLessThanOrEqual(30_000) expect(delays[delays.length - 1]).toBe(30_000) }) }) describe('initialInput timer respects dispose (Phase 1#4 regression)', () => { beforeEach(() => { setLocation('http:', 'lan:3000') vi.useFakeTimers() }) it('does NOT send the initial command if disposed before the timer fires', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn(), initialInput: 'claude --resume x\r' }) s.connect() const ws = MockWebSocket.last() ws.openIt() ws.message(JSON.stringify({ type: 'attached', sessionId: 'sid' })) ws.sent.length = 0 // drop attach/resize frames s.dispose() // dispose BEFORE the 700ms initial-input timer fires vi.advanceTimersByTime(2000) // No input frame should have been sent after dispose. const inputs = ws.sent.map((x) => JSON.parse(x)).filter((m) => m.type === 'input') expect(inputs).toHaveLength(0) }) it('DOES send the initial command when not disposed', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn(), initialInput: 'echo hi\r' }) s.connect() const ws = MockWebSocket.last() ws.openIt() ws.message(JSON.stringify({ type: 'attached', sessionId: 'sid' })) ws.sent.length = 0 vi.advanceTimersByTime(800) const inputs = ws.sent.map((x) => JSON.parse(x)).filter((m) => m.type === 'input') expect(inputs).toContainEqual({ type: 'input', data: 'echo hi\r' }) }) }) describe('hide() does not send a blur frame (removed in latest-writer pivot)', () => { beforeEach(() => setLocation('http:', 'lan:3000')) it('hide() sends nothing and never emits type:"blur"', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() const ws = MockWebSocket.last() ws.openIt() ws.sent.length = 0 s.hide() const blur = ws.sent.map((x) => JSON.parse(x)).filter((m) => m.type === 'blur') expect(blur).toHaveLength(0) }) }) describe('dispose() tears down cleanly', () => { beforeEach(() => setLocation('http:', 'lan:3000')) it('closes the WS and does not reconnect afterwards', () => { const s = new TerminalSession({ sessionId: 'sid', onSessionId: vi.fn() }) s.connect() const ws = MockWebSocket.last() ws.openIt() const countBefore = MockWebSocket.instances.length s.dispose() // A close after dispose must NOT trigger a new connection. ws.fire('close', {}) expect(MockWebSocket.instances.length).toBe(countBefore) }) it('connect() is a no-op after dispose', () => { const s = new TerminalSession({ sessionId: 'sid', onSessionId: vi.fn() }) s.dispose() s.connect() expect(MockWebSocket.instances).toHaveLength(0) }) }) describe('output + activity + send paths', () => { beforeEach(() => setLocation('http:', 'lan:3000')) function connected(opts: { onActivity?: () => void } = {}) { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn(), ...opts }) s.connect() const ws = MockWebSocket.last() ws.openIt() return { s, ws } } it('writes output to the terminal and fires onActivity for a hidden pane', () => { const onActivity = vi.fn() const { s, ws } = connected({ onActivity }) // pane starts display:none (hidden) → output triggers activity ws.message(JSON.stringify({ type: 'output', data: 'hello' })) expect(onActivity).toHaveBeenCalled() // show() flips display to block → no further activity on next output s.show() onActivity.mockClear() ws.message(JSON.stringify({ type: 'output', data: 'more' })) expect(onActivity).not.toHaveBeenCalled() }) it('send() routes keyboard bytes as an input frame', () => { const { s, ws } = connected() ws.sent.length = 0 s.send('ls\r') expect(JSON.parse(ws.sent[0]!)).toEqual({ type: 'input', data: 'ls\r' }) }) it('approve()/reject() send their frames and clear pendingApproval', () => { const { s, ws } = connected() ws.message(JSON.stringify({ type: 'status', status: 'waiting', detail: 'Bash', pending: true })) ws.sent.length = 0 s.approve() expect(JSON.parse(ws.sent[0]!)).toEqual({ type: 'approve' }) expect(s.pendingApproval).toBe(false) s.reject() expect(JSON.parse(ws.sent[1]!)).toEqual({ type: 'reject' }) }) it('ignores malformed JSON frames without throwing', () => { const { ws } = connected() expect(() => ws.message('{not json')).not.toThrow() }) }) describe('exit handling', () => { beforeEach(() => setLocation('http:', 'lan:3000')) it('sets status to exited and writes the exit line', () => { const onStatus = vi.fn() const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn(), onStatus }) s.connect() const ws = MockWebSocket.last() ws.openIt() ws.message(JSON.stringify({ type: 'exit', code: 0 })) expect(s.status).toBe('exited') expect(onStatus).toHaveBeenCalledWith('exited') }) it('exit with a reason includes it in the rendered line', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() const ws = MockWebSocket.last() ws.openIt() expect(() => ws.message(JSON.stringify({ type: 'exit', code: -1, reason: 'spawn failed' }))).not.toThrow() }) }) describe('search + theme passthrough', () => { beforeEach(() => setLocation('http:', 'lan:3000')) it('findNext/findPrevious/clearSearch are callable', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) expect(() => { s.findNext('x') s.findPrevious('x') s.clearSearch() }).not.toThrow() }) it('applyTheme updates terminal options', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) expect(() => s.applyTheme({ background: '#000' }, 14)).not.toThrow() }) }) describe('attach with cwd (M6 "new tab here")', () => { beforeEach(() => setLocation('http:', 'lan:3000')) it('includes cwd in the attach frame for a fresh session', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn(), cwd: '/work/here' }) s.connect() MockWebSocket.last().openIt() expect(JSON.parse(MockWebSocket.last().sent[0]!)).toEqual({ type: 'attach', sessionId: null, cwd: '/work/here' }) }) it('omits cwd on a reconnect to an existing sessionId', () => { const s = new TerminalSession({ sessionId: '44444444-4444-4444-8444-444444444444', onSessionId: vi.fn(), cwd: '/x' }) s.connect() MockWebSocket.last().openIt() expect(JSON.parse(MockWebSocket.last().sent[0]!)).toEqual({ type: 'attach', sessionId: '44444444-4444-4444-8444-444444444444', }) }) }) describe('exit → press Enter reconnects with a fresh session', () => { beforeEach(() => setLocation('http:', 'lan:3000')) it('Enter after exit closes the old WS and opens a new connection (sessionId reset)', () => { const s = new TerminalSession({ sessionId: '55555555-5555-4555-8555-555555555555', onSessionId: vi.fn() }) s.connect() const ws1 = MockWebSocket.last() ws1.openIt() ws1.message(JSON.stringify({ type: 'exit', code: 0 })) const before = MockWebSocket.instances.length // The exit handler registers a term.onData listener; pressing Enter ('\r') // triggers reconnect. Drive it via the fake terminal's data callback. ;(s as unknown as { term: { emitData(d: string): void } }).term.emitData('\r') expect(MockWebSocket.instances.length).toBe(before + 1) expect(s.id).toBeNull() // fresh session id on reconnect }) }) describe('show()/refit() re-fit when visible', () => { beforeEach(() => setLocation('http:', 'lan:3000')) it('show() makes the pane visible and focuses without throwing', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() MockWebSocket.last().openIt() expect(() => s.show()).not.toThrow() expect(s.el.style.display).toBe('block') }) it('refit() is a no-op while hidden, runs when visible', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() MockWebSocket.last().openIt() expect(() => s.refit()).not.toThrow() // hidden → no-op s.show() expect(() => s.refit()).not.toThrow() // visible → fits }) it('safefit returns null on NaN dims → no resize frame sent (display:none guard, §9)', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() const ws = MockWebSocket.last() ws.openIt() // Make the fake terminal report NaN cols (simulating fit() while hidden). ;(s as unknown as { term: { cols: number; rows: number } }).term.cols = NaN ws.sent.length = 0 s.show() const resizes = ws.sent.map((x) => JSON.parse(x)).filter((m) => m.type === 'resize') expect(resizes).toHaveLength(0) }) it('status frame WITHOUT pending leaves pendingApproval false', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() MockWebSocket.last().openIt() MockWebSocket.last().message(JSON.stringify({ type: 'status', status: 'working' })) expect(s.claudeStatus).toBe('working') expect(s.pendingApproval).toBe(false) expect(s.pendingTool).toBeUndefined() }) it('send() while the WS is closed is a no-op (guarded)', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() const ws = MockWebSocket.last() ws.openIt() ws.readyState = 3 // CLOSED ws.sent.length = 0 s.send('x') expect(ws.sent).toHaveLength(0) }) }) // ── B2 telemetry frame ──────────────────────────────────────────────────────── describe('telemetry frame (B2)', () => { beforeEach(() => setLocation('http:', 'lan:3000')) function connected(opts: { onTelemetry?: (t: unknown) => void } = {}) { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn(), onTelemetry: opts.onTelemetry as Parameters[0]['onTelemetry'], }) s.connect() const ws = MockWebSocket.last() ws.openIt() return { s, ws } } it('telemetry getter starts as null before any telemetry frame', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) expect(s.telemetry).toBeNull() }) it('fires onTelemetry callback and updates the telemetry getter', () => { const onTelemetry = vi.fn() const { s, ws } = connected({ onTelemetry }) const tel = { at: 1000, contextUsedPct: 42, costUsd: 0.5, model: 'claude-opus-4' } ws.message(JSON.stringify({ type: 'telemetry', telemetry: tel })) expect(onTelemetry).toHaveBeenCalledOnce() expect(onTelemetry).toHaveBeenCalledWith(tel) expect(s.telemetry).toEqual(tel) }) it('works without onTelemetry (callback is optional — no throw)', () => { const { ws } = connected() // no onTelemetry const tel = { at: 2000, costUsd: 0.1 } expect(() => ws.message(JSON.stringify({ type: 'telemetry', telemetry: tel }))).not.toThrow() }) it('updates telemetry on subsequent frames (latest wins)', () => { const { s, ws } = connected() ws.message(JSON.stringify({ type: 'telemetry', telemetry: { at: 1000, costUsd: 0.1 } })) ws.message(JSON.stringify({ type: 'telemetry', telemetry: { at: 2000, costUsd: 0.9 } })) expect(s.telemetry).toMatchObject({ at: 2000, costUsd: 0.9 }) }) it('onTelemetry is called once per frame (not debounced)', () => { const onTelemetry = vi.fn() const { ws } = connected({ onTelemetry }) ws.message(JSON.stringify({ type: 'telemetry', telemetry: { at: 1 } })) ws.message(JSON.stringify({ type: 'telemetry', telemetry: { at: 2 } })) ws.message(JSON.stringify({ type: 'telemetry', telemetry: { at: 3 } })) expect(onTelemetry).toHaveBeenCalledTimes(3) }) }) // ── B4 pendingGate from status frame ───────────────────────────────────────── describe('pendingGate from status frame (B4)', () => { beforeEach(() => setLocation('http:', 'lan:3000')) function connected() { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() const ws = MockWebSocket.last() ws.openIt() return { s, ws } } it('pendingGate starts as null', () => { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) expect(s.pendingGate).toBeNull() }) it('records pendingGate="plan" from a status message with gate:"plan"', () => { const { s, ws } = connected() ws.message(JSON.stringify({ type: 'status', status: 'waiting', pending: true, gate: 'plan' })) expect(s.pendingGate).toBe('plan') }) it('records pendingGate="tool" from a status message with gate:"tool"', () => { const { s, ws } = connected() ws.message(JSON.stringify({ type: 'status', status: 'waiting', pending: true, gate: 'tool' })) expect(s.pendingGate).toBe('tool') }) it('sets pendingGate to null when gate is absent from status', () => { const { s, ws } = connected() ws.message(JSON.stringify({ type: 'status', status: 'waiting', pending: true })) expect(s.pendingGate).toBeNull() }) it('clears pendingGate to null on a subsequent status without gate', () => { const { s, ws } = connected() ws.message(JSON.stringify({ type: 'status', status: 'waiting', pending: true, gate: 'plan' })) expect(s.pendingGate).toBe('plan') ws.message(JSON.stringify({ type: 'status', status: 'working' })) expect(s.pendingGate).toBeNull() }) }) // ── B4 approve(mode?) with PermissionMode ──────────────────────────────────── describe('approve(mode?) — B4 permission-mode relay', () => { beforeEach(() => setLocation('http:', 'lan:3000')) function connected() { const s = new TerminalSession({ sessionId: null, onSessionId: vi.fn() }) s.connect() const ws = MockWebSocket.last() ws.openIt() ws.message(JSON.stringify({ type: 'status', status: 'waiting', pending: true, gate: 'plan' })) ws.sent.length = 0 return { s, ws } } it('approve() without mode sends {type:"approve"} with NO mode field', () => { const { s, ws } = connected() s.approve() const msg = JSON.parse(ws.sent[0]!) expect(msg).toEqual({ type: 'approve' }) expect('mode' in msg).toBe(false) }) it('approve("acceptEdits") sends {type:"approve", mode:"acceptEdits"}', () => { const { s, ws } = connected() s.approve('acceptEdits') expect(JSON.parse(ws.sent[0]!)).toEqual({ type: 'approve', mode: 'acceptEdits' }) }) it('approve("plan") sends {type:"approve", mode:"plan"}', () => { const { s, ws } = connected() s.approve('plan') expect(JSON.parse(ws.sent[0]!)).toEqual({ type: 'approve', mode: 'plan' }) }) it('approve("auto") sends {type:"approve", mode:"auto"}', () => { const { s, ws } = connected() s.approve('auto') expect(JSON.parse(ws.sent[0]!)).toEqual({ type: 'approve', mode: 'auto' }) }) it('approve("default") sends {type:"approve", mode:"default"}', () => { const { s, ws } = connected() s.approve('default') expect(JSON.parse(ws.sent[0]!)).toEqual({ type: 'approve', mode: 'default' }) }) it('approve() clears pendingApproval regardless of mode', () => { const { s } = connected() expect(s.pendingApproval).toBe(true) s.approve('acceptEdits') expect(s.pendingApproval).toBe(false) }) })