~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
/**
* Tests for services/socket.js
*
* Verifies the page-load subscribe/connect race fixes:
* - subscribeToResearch with a mid-connect socket does NOT call
* fallbackToPolling and does NOT emit (the connect handler will).
* - The 'connect' event clears any leftover polling intervals.
* - subscribeToResearch uses the canonical 'subscribe_to_research'
* event name, not the legacy 'join'.
*/
let socketModule;
// Mock socket factory that lets tests fire connect/disconnect manually.
function createMockSocket() {
const handlers = {};
return {
connected: false,
emit: vi.fn(),
on: vi.fn((event, cb) => {
handlers[event] ||= [];
handlers[event].push(cb);
}),
off: vi.fn((event) => {
delete handlers[event];
}),
// Test helper — simulate an event from the server.
_fire(event, ...args) {
(handlers[event] || []).forEach((cb) => cb(...args));
},
};
}
let mockSocket;
beforeAll(async () => {
// The socket module checks window.location.pathname for a research page.
Object.defineProperty(window, 'location', {
configurable: true,
value: { ...window.location, pathname: '/progress/abc-123', protocol: 'http:', host: 'localhost' },
});
mockSocket = createMockSocket();
globalThis.io = vi.fn(() => mockSocket);
// Stub the API + URLBuilder helpers used by polling fallback.
window.api = {
getResearchStatus: vi.fn(() => Promise.resolve({ status: 'in_progress' })),
getCsrfToken: () => '',
};
window.ResearchStates = { isTerminal: () => false, logLevel: () => 'info' };
await import('@js/services/socket.js');
socketModule = window.socket;
// socket.js schedules its eager progress-page bootstrap 100 ms after
// import. Wait for it here so the real timer cannot outlive this test
// environment and fire after jsdom has torn down `window`.
await vi.waitFor(() => expect(globalThis.io).toHaveBeenCalledOnce());
});
beforeEach(() => {
// Reset polling state and the mock socket for each test.
window.pollIntervals = {};
mockSocket.emit.mockClear();
mockSocket.on.mockClear();
mockSocket.off.mockClear();
mockSocket.connected = false;
});
describe('subscribeToResearch — page-load race', () => {
it('exports the lifecycle API consumed by the benchmark page', () => {
expect(socketModule.init).toEqual(expect.any(Function));
expect(socketModule.getSocketInstance).toEqual(expect.any(Function));
// Exercise the checked-in service rather than a benchmark-page mock:
// init is idempotent and the getter returns that same live instance.
expect(socketModule.init()).toBe(mockSocket);
expect(socketModule.getSocketInstance()).toBe(mockSocket);
});
it('does not fall back to polling when socket exists but is mid-connect', () => {
// Simulate the page-load state: io() has been called (so socket
// exists) but the websocket handshake hasn't completed yet.
socketModule.subscribeToResearch('research-1', () => {});
// No emit should have happened — the connect handler will subscribe.
expect(mockSocket.emit).not.toHaveBeenCalled();
// Polling should not have been kicked off either.
expect(window.pollIntervals['research-1']).toBeUndefined();
});
it('emits subscribe_to_research (not join) when socket is connected', () => {
mockSocket.connected = true;
socketModule.subscribeToResearch('research-2', () => {});
// Should use the canonical event name that the server handles directly.
const emittedEvents = mockSocket.emit.mock.calls.map((c) => c[0]);
expect(emittedEvents).toContain('subscribe_to_research');
expect(emittedEvents).not.toContain('join');
});
it('listens on the FastAPI research_progress_{id} channel and forwards data', () => {
mockSocket.connected = true;
const callback = vi.fn();
socketModule.subscribeToResearch('research-events', callback);
expect(mockSocket.off).toHaveBeenCalledWith(
'research_progress_research-events'
);
expect(mockSocket.on).toHaveBeenCalledWith(
'research_progress_research-events',
expect.any(Function)
);
const listenerNames = mockSocket.on.mock.calls.map(([event]) => event);
expect(listenerNames).not.toContain('progress_research-events');
const payload = { status: 'in_progress', progress: 42 };
mockSocket._fire('research_progress_research-events', payload);
expect(callback).toHaveBeenCalledTimes(1);
expect(callback).toHaveBeenCalledWith(payload);
});
it('falls back to polling only for a matching FastAPI subscribe_error', () => {
const researchId = 'research-subscribe-error';
const pollResearchStatus = vi.fn();
window.pollResearchStatus = pollResearchStatus;
mockSocket.connected = true;
try {
socketModule.subscribeToResearch(researchId, () => {});
// The FastAPI protocol always scopes this event. Treat an
// unscoped packet as malformed instead of assigning it to the
// currently active run.
mockSocket._fire('subscribe_error', {
error: 'Unscoped subscription failure',
});
mockSocket._fire('subscribe_error', {
error: 'Not authorized',
research_id: 'previous-research',
});
expect(pollResearchStatus).not.toHaveBeenCalled();
expect(socketModule.isUsingPolling()).toBe(false);
mockSocket._fire('subscribe_error', {
error: 'Not authorized',
research_id: researchId,
});
expect(pollResearchStatus).toHaveBeenCalledOnce();
expect(pollResearchStatus).toHaveBeenCalledWith(researchId);
expect(socketModule.isUsingPolling()).toBe(true);
// Expired sessions emit subscribe_error immediately before the
// server disconnects the socket. That second signal must not
// start another polling loop for the same research.
mockSocket._fire('disconnect', 'io server disconnect');
mockSocket._fire('error', new Error('late transport error'));
expect(pollResearchStatus).toHaveBeenCalledOnce();
} finally {
mockSocket._fire('connect');
socketModule.unsubscribeFromResearch(researchId);
delete window.pollResearchStatus;
}
});
it('matches numeric room IDs to string IDs in FastAPI subscribe_error payloads', () => {
const pollResearchStatus = vi.fn();
window.pollResearchStatus = pollResearchStatus;
mockSocket.connected = true;
try {
socketModule.subscribeToResearch(42, () => {});
// FastAPI serializes identifiers in event payloads, while page
// callers may retain the numeric route parameter. The rejected
// active room must still enter fallback exactly once.
mockSocket._fire('subscribe_error', {
error: 'Not authorized',
research_id: '42',
});
mockSocket._fire('disconnect', 'io server disconnect');
expect(pollResearchStatus).toHaveBeenCalledOnce();
expect(pollResearchStatus).toHaveBeenCalledWith(42);
expect(socketModule.isUsingPolling()).toBe(true);
} finally {
mockSocket._fire('connect');
socketModule.unsubscribeFromResearch(42);
delete window.pollResearchStatus;
}
});
it('starts a fresh fallback after leaving a previously rejected research', () => {
const firstResearchId = 'research-subscribe-error-a';
const secondResearchId = 'research-subscribe-error-b';
const pollResearchStatus = vi.fn();
window.pollResearchStatus = pollResearchStatus;
mockSocket.connected = true;
try {
socketModule.subscribeToResearch(firstResearchId, () => {});
mockSocket._fire('subscribe_error', {
error: 'Not authorized',
research_id: firstResearchId,
});
// The server may close the transport after rejecting A. Leaving
// A must clear its poll without pretending the transport has
// recovered; B then needs an immediate polling fallback.
mockSocket.connected = false;
mockSocket._fire('disconnect', 'io server disconnect');
socketModule.unsubscribeFromResearch(firstResearchId);
socketModule.subscribeToResearch(secondResearchId, () => {});
expect(pollResearchStatus.mock.calls).toEqual([
[firstResearchId],
[secondResearchId],
]);
expect(socketModule.isUsingPolling()).toBe(true);
} finally {
mockSocket.connected = true;
mockSocket._fire('connect');
socketModule.unsubscribeFromResearch(secondResearchId);
delete window.pollResearchStatus;
}
});
it('clears stale polling intervals when the socket connects', () => {
// Simulate a leftover polling interval from a fallback path.
const intervalId = setInterval(() => {}, 9999);
window.pollIntervals = { 'research-3': intervalId };
// Manually fire 'connect' on the mock socket.
mockSocket.connected = true;
mockSocket._fire('connect');
// The interval should have been cleared and the entry removed.
expect(window.pollIntervals).toEqual({});
});
it('re-subscribes to the deferred research id once connect fires', () => {
// Subscribe while the socket is mid-connect — must NOT emit yet.
socketModule.subscribeToResearch('research-deferred', () => {});
expect(mockSocket.emit).not.toHaveBeenCalled();
// The websocket completes the handshake and the server fires connect.
mockSocket.connected = true;
mockSocket._fire('connect');
// Exactly one subscribe_to_research must have been emitted, with
// the deferred id — the page-load race fix depends on this
// follow-through. A regression that drops currentResearchId before
// the connect handler runs would silently break the progress page.
const subscribeCalls = mockSocket.emit.mock.calls.filter(
(c) => c[0] === 'subscribe_to_research'
);
expect(subscribeCalls.length).toBe(1);
expect(subscribeCalls[0][1]).toEqual({ research_id: 'research-deferred' });
});
it('returns from polling fallback to the canonical websocket channel', () => {
const researchId = 'research-recovery';
const pollResearchStatus = vi.fn((id) => {
window.pollIntervals[id] = setInterval(() => {}, 9999);
});
window.pollResearchStatus = pollResearchStatus;
try {
socketModule.subscribeToResearch(researchId, () => {});
mockSocket._fire('connect_error', new Error('attempt 1'));
mockSocket._fire('connect_error', new Error('attempt 2'));
expect(pollResearchStatus).not.toHaveBeenCalled();
mockSocket._fire('connect_error', new Error('attempt 3'));
expect(pollResearchStatus).toHaveBeenCalledOnce();
expect(pollResearchStatus).toHaveBeenCalledWith(researchId);
expect(window.pollIntervals[researchId]).toBeDefined();
mockSocket.connected = true;
mockSocket._fire('connect');
expect(window.pollIntervals).toEqual({});
expect(mockSocket.emit).toHaveBeenCalledWith(
'subscribe_to_research',
{ research_id: researchId }
);
expect(mockSocket.off).toHaveBeenCalledWith(
`research_progress_${researchId}`
);
expect(mockSocket.on).toHaveBeenCalledWith(
`research_progress_${researchId}`,
expect.any(Function)
);
} finally {
if (window.pollIntervals[researchId]) {
clearInterval(window.pollIntervals[researchId]);
delete window.pollIntervals[researchId];
}
delete window.pollResearchStatus;
}
});
it('delivers a terminal fallback poll and removes its completed interval', async () => {
const researchId = 'research-terminal-poll';
const callback = vi.fn();
const terminalPayload = { status: 'completed', progress: 100 };
const originalIsTerminal = window.ResearchStates.isTerminal;
vi.useFakeTimers();
delete window.pollResearchStatus;
window.ResearchStates.isTerminal = vi.fn(
status => status === 'completed',
);
window.api.getResearchStatus.mockResolvedValueOnce(terminalPayload);
try {
mockSocket.connected = true;
socketModule.subscribeToResearch(researchId, callback);
// Losing the migrated websocket transport starts socket.js's own
// HTTP fallback when the page did not provide a polling helper.
mockSocket.connected = false;
mockSocket._fire('disconnect', 'transport close');
expect(window.pollIntervals[researchId]).toBeDefined();
expect(window.api.getResearchStatus).not.toHaveBeenCalled();
await vi.advanceTimersByTimeAsync(3000);
expect(window.api.getResearchStatus).toHaveBeenCalledOnce();
expect(window.api.getResearchStatus).toHaveBeenCalledWith(researchId);
expect(callback).toHaveBeenCalledOnce();
expect(callback).toHaveBeenCalledWith(terminalPayload);
// A terminal FastAPI status must retire the timer and its public
// bookkeeping entry; otherwise every completed run keeps polling.
expect(window.pollIntervals).toEqual({});
} finally {
if (window.pollIntervals[researchId]) {
clearInterval(window.pollIntervals[researchId]);
delete window.pollIntervals[researchId];
}
// Test cleanup deliberately restores the shared transport after
// awaiting the fake-timer callback above.
// eslint-disable-next-line require-atomic-updates
mockSocket.connected = true;
mockSocket._fire('connect');
socketModule.unsubscribeFromResearch(researchId);
window.ResearchStates.isTerminal = originalIsTerminal;
window.api.getResearchStatus.mockReset();
delete window.pollResearchStatus;
vi.useRealTimers();
}
});
it('isolates progress handlers so one broken consumer cannot block the others', () => {
const researchId = 'research-handler-isolation';
const brokenHandler = vi.fn(() => {
throw new Error('consumer render failed');
});
const healthyHandler = vi.fn();
const payload = { status: 'in_progress', progress: 61 };
mockSocket.connected = true;
try {
socketModule.subscribeToResearch(researchId, brokenHandler);
socketModule.subscribeToResearch(researchId, healthyHandler);
expect(() => {
mockSocket._fire(`research_progress_${researchId}`, payload);
}).not.toThrow();
expect(brokenHandler).toHaveBeenCalledOnce();
expect(healthyHandler).toHaveBeenCalledOnce();
expect(healthyHandler).toHaveBeenCalledWith(payload);
} finally {
socketModule.unsubscribeFromResearch(researchId);
}
});
it('does not register the same progress consumer twice', () => {
const researchId = 'research-handler-dedup';
const handler = vi.fn();
mockSocket.connected = true;
try {
socketModule.subscribeToResearch(researchId, handler);
socketModule.subscribeToResearch(researchId, handler);
mockSocket._fire(`research_progress_${researchId}`, {
status: 'in_progress',
});
expect(handler).toHaveBeenCalledOnce();
} finally {
socketModule.unsubscribeFromResearch(researchId);
}
});
});
describe('unsubscribeFromResearch', () => {
it('emits unsubscribe_from_research (not legacy leave)', () => {
mockSocket.connected = true;
// First subscribe so there's something to leave.
socketModule.subscribeToResearch('research-4', () => {});
mockSocket.emit.mockClear();
mockSocket.off.mockClear();
socketModule.unsubscribeFromResearch('research-4');
const emittedEvents = mockSocket.emit.mock.calls.map((c) => c[0]);
expect(emittedEvents).toContain('unsubscribe_from_research');
expect(emittedEvents).not.toContain('leave');
expect(mockSocket.off).toHaveBeenCalledWith(
'research_progress_research-4'
);
expect(mockSocket.off).not.toHaveBeenCalledWith('progress_research-4');
});
it('keeps the newer room active when an older room is unsubscribed', () => {
mockSocket.connected = true;
try {
socketModule.subscribeToResearch('research-old', () => {});
socketModule.subscribeToResearch('research-current', () => {});
socketModule.unsubscribeFromResearch('research-old');
mockSocket.emit.mockClear();
// A reconnect must restore the current room, not the stale room
// whose page cleanup arrived after the newer subscription.
mockSocket._fire('connect');
const roomSubscriptions = mockSocket.emit.mock.calls.filter(
([event]) => event === 'subscribe_to_research'
);
expect(roomSubscriptions).toEqual([
[
'subscribe_to_research',
{ research_id: 'research-current' },
],
]);
} finally {
socketModule.unsubscribeFromResearch('research-current');
}
});
it('treats numeric and string room IDs as the same unsubscribe owner', () => {
mockSocket.connected = true;
try {
socketModule.subscribeToResearch(3299, () => {});
socketModule.unsubscribeFromResearch('3299');
mockSocket.emit.mockClear();
// FastAPI event payloads commonly stringify identifiers. Once the
// equivalent string ID leaves, reconnect must not resurrect the
// numerically supplied room.
mockSocket._fire('connect');
expect(mockSocket.emit).not.toHaveBeenCalledWith(
'subscribe_to_research',
expect.anything(),
);
} finally {
socketModule.unsubscribeFromResearch(3299);
}
});
});
describe('addLogEntry — delegation routing (window._socketAddLogEntry)', () => {
// The IIFE-private addLogEntry is reachable from outside only via the
// exported window._socketAddLogEntry. The function delegates in three
// tiers: (1) if window._socketAddLogEntry was replaced by something
// OTHER than itself (logpanel.js does this in production), call that;
// (2) else if window.addConsoleLog exists, call it with adapted args;
// (3) else fall back to inline DOM template work — NOT tested here
// (would mostly assert CSS class names we'd type in the test setup).
let originalAddLogEntry;
let originalAddConsoleLog;
beforeAll(() => {
// Capture the original (which IS the function we want to invoke)
// BEFORE any test reassigns window._socketAddLogEntry.
originalAddLogEntry = window._socketAddLogEntry;
});
beforeEach(() => {
originalAddConsoleLog = window.addConsoleLog;
});
afterEach(() => {
// Restore both globals so the next test starts clean.
window._socketAddLogEntry = originalAddLogEntry;
if (originalAddConsoleLog === undefined) {
delete window.addConsoleLog;
} else {
window.addConsoleLog = originalAddConsoleLog;
}
});
it('delegates to a replaced window._socketAddLogEntry (logpanel override)', () => {
const spy = vi.fn();
window._socketAddLogEntry = spy;
originalAddLogEntry({ message: 'hi', type: 'info' });
expect(spy).toHaveBeenCalledTimes(1);
expect(spy).toHaveBeenCalledWith({ message: 'hi', type: 'info' });
});
it('falls back to window.addConsoleLog when _socketAddLogEntry was not overridden', () => {
const consoleSpy = vi.fn();
window.addConsoleLog = consoleSpy;
// _socketAddLogEntry intentionally NOT overridden — it === originalAddLogEntry,
// so the first branch is skipped.
originalAddLogEntry({ message: 'm', type: 'warning', metadata: { foo: 'bar' } });
expect(consoleSpy).toHaveBeenCalledTimes(1);
expect(consoleSpy).toHaveBeenCalledWith('m', 'warning', { foo: 'bar' });
});
it('derives logLevel from metadata.type when top-level type is missing', () => {
const consoleSpy = vi.fn();
window.addConsoleLog = consoleSpy;
originalAddLogEntry({ message: 'm', metadata: { type: 'error' } });
expect(consoleSpy).toHaveBeenCalledWith('m', 'error', { type: 'error' });
});
it('defaults logLevel to "info" when neither type nor metadata.type is present', () => {
const consoleSpy = vi.fn();
window.addConsoleLog = consoleSpy;
originalAddLogEntry({ message: 'm' });
expect(consoleSpy).toHaveBeenCalledWith('m', 'info', undefined);
});
});