Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import {
type Config,
type ConfigBinding,
DEFAULT_EMBEDDINGS_BASE_URL,
DEFAULT_EMBEDDINGS_DOC_TIMEOUT_MS,
DEFAULT_EMBEDDINGS_MAX_BATCH_CHARS,
DEFAULT_EMBEDDINGS_MAX_BATCH_SIZE,
type SemanticIndexStatus,
} from '@inkeep/open-knowledge-core';
import { i18n } from '@lingui/core';
import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { describedTextOf } from './settings-a11y.test-helper';
type WindowGlobals = { NodeFilter?: typeof NodeFilter };
type GlobalWithDomShims = typeof globalThis &
WindowGlobals & { window?: WindowGlobals; ResizeObserver?: unknown };
const globalWithDomShims = globalThis as GlobalWithDomShims;
if (
globalWithDomShims.NodeFilter === undefined &&
globalWithDomShims.window?.NodeFilter !== undefined
) {
globalWithDomShims.NodeFilter = globalWithDomShims.window.NodeFilter;
}
if (globalWithDomShims.ResizeObserver === undefined) {
class NoopResizeObserver {
observe() {}
unobserve() {}
disconnect() {}
}
globalWithDomShims.ResizeObserver = NoopResizeObserver;
}
let mockProjectLocalConfig: Config | null = null;
let mockProjectLocalSynced = true;
let mockProjectLocalBinding: ConfigBinding | null = null;
vi.doMock('@/lib/config-provider', () => ({
useConfigContext: () => ({
userBinding: null,
userSynced: false,
projectBinding: null,
projectLocalBinding: mockProjectLocalBinding,
okignoreBinding: null,
okignoreSynced: false,
userConfig: null,
projectConfig: null,
projectLocalConfig: mockProjectLocalConfig,
projectLocalSynced: mockProjectLocalSynced,
merged: null,
}),
}));
const { SearchSection } = await import('./SearchSection');
function configWithSemantic({
enabled,
baseUrl,
model,
maxBatchSize,
maxBatchChars,
docTimeoutMs,
}: {
enabled: boolean;
baseUrl?: string;
model?: string;
maxBatchSize?: number;
maxBatchChars?: number;
docTimeoutMs?: number;
}): Config {
return {
search: {
semantic: {
enabled,
...(baseUrl ? { baseUrl } : {}),
...(model ? { model } : {}),
...(maxBatchSize !== undefined ? { maxBatchSize } : {}),
...(maxBatchChars !== undefined ? { maxBatchChars } : {}),
...(docTimeoutMs !== undefined ? { docTimeoutMs } : {}),
},
},
} as unknown as Config;
}
function makeBinding(onPatch?: () => void): { binding: ConfigBinding; calls: unknown[] } {
const calls: unknown[] = [];
const binding = {
current: () => ({}),
patch: (patch: unknown) => {
calls.push(patch);
onPatch?.();
return { ok: true, value: { applied: [], effective: {} } };
},
subscribe: () => () => {},
hasSynced: () => true,
subscribeSynced: () => () => {},
dispose: () => {},
} as unknown as ConfigBinding;
return { binding, calls };
}
let mockStatus: SemanticIndexStatus | null = null;
const originalFetch = global.fetch;
beforeEach(() => {
i18n.loadAndActivate({ locale: 'en', messages: {} });
mockProjectLocalConfig = null;
mockProjectLocalSynced = true;
mockProjectLocalBinding = null;
mockStatus = null;
global.fetch = (async () => ({
ok: true,
json: async () => mockStatus,
})) as unknown as typeof fetch;
});
afterEach(() => {
cleanup();
global.fetch = originalFetch;
vi.useRealTimers();
});
describe('SearchSection', () => {
test('off: switch is unchecked, body says no content leaves, no coverage panel', () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
const toggle = screen.getByTestId('settings-search-semantic-toggle');
expect(toggle.getAttribute('aria-checked')).toBe('false');
expect(screen.getByTestId('settings-search-body').textContent).toContain(
'No content leaves this computer',
);
expect(screen.queryByTestId('settings-search-coverage')).toBeNull();
expect(screen.queryByTestId('settings-search-needs-key')).toBeNull();
});
test('the egress disclosure is announced with the toggle, not just shown beside it', () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
render(<SearchSection />);
expect(describedTextOf('settings-search-semantic-toggle')).toContain(
'sent to your embeddings provider',
);
});
test('toggle is disabled until the project-local binding has synced', () => {
mockProjectLocalBinding = null;
mockProjectLocalSynced = false;
render(<SearchSection />);
expect(
screen.getByTestId('settings-search-semantic-toggle').getAttribute('disabled'),
).not.toBeNull();
});
test('enabling opens the egress confirm dialog and does NOT write until confirmed', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await user.click(screen.getByTestId('settings-search-semantic-toggle'));
expect(await screen.findByText('This sends content off your machine')).toBeDefined();
expect(calls.length).toBe(0);
await user.click(screen.getByTestId('settings-search-confirm-enable'));
expect(calls).toEqual([{ search: { semantic: { enabled: true } } }]);
});
test('disabling commits immediately with no confirmation dialog', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: true,
keyNotRequired: false,
keySource: 'file',
keyHint: 'a1b2',
ready: true,
capable: true,
embedded: 2,
total: 5,
};
render(<SearchSection />);
await user.click(screen.getByTestId('settings-search-semantic-toggle'));
expect(screen.queryByText('This sends content off your machine')).toBeNull();
expect(calls).toEqual([{ search: { semantic: { enabled: false } } }]);
});
test('on + keyed + warmed + capable: shows read-only coverage', async () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: true,
keyNotRequired: false,
keySource: 'file',
keyHint: 'a1b2',
ready: true,
capable: true,
embedded: 3,
total: 5,
};
render(<SearchSection />);
const coverage = await screen.findByTestId('settings-search-coverage');
expect(coverage.textContent).toMatch(/Indexed\s*3\s*of\s*5/);
});
test('on + capable but nothing embedded yet: shows the lazy-warm hint', async () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: true,
keyNotRequired: false,
keySource: 'file',
keyHint: 'a1b2',
ready: true,
capable: true,
embedded: 0,
total: 5,
};
render(<SearchSection />);
const coverage = await screen.findByTestId('settings-search-coverage');
expect(coverage.textContent).toContain('first time a search needs them');
});
test('on + NO key: shows the needs-a-key hint pointing at the on-screen field (instant, no warm)', async () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: false,
keyNotRequired: false,
keySource: null,
keyHint: null,
ready: false,
capable: false,
embedded: 0,
total: 5,
};
render(<SearchSection />);
const hint = await screen.findByTestId('settings-search-needs-key');
expect(hint.textContent).toContain('no API key is set');
expect(hint.textContent).toContain('below');
expect(screen.queryByTestId('settings-search-coverage')).toBeNull();
expect(screen.queryByTestId('settings-search-pending')).toBeNull();
});
test.each([
[null, '~/.ok/secrets.yml'],
['ok-beta', '~/.ok-beta/secrets.yml'],
])(
'names the key file in the home of the channel main named (%s)',
async (cliCommandName, path) => {
(window as unknown as { okDesktop?: unknown }).okDesktop =
cliCommandName === null ? undefined : { cliCommandName };
try {
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: false,
keyNotRequired: false,
keySource: null,
keyHint: null,
ready: false,
capable: false,
embedded: 0,
total: 5,
};
render(<SearchSection />);
const stored = await screen.findByText(
(_content, el) =>
el?.tagName === 'P' && (el.textContent ?? '').includes('Stored on this machine only'),
);
expect(stored.textContent).toContain(`(in ${path})`);
} finally {
(window as unknown as { okDesktop?: unknown }).okDesktop = undefined;
}
},
);
test('on + key present but provider rejected it: shows the provider-error hint', async () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: true,
keyNotRequired: false,
keySource: 'file',
keyHint: 'a1b2',
ready: true,
capable: false,
embedded: 0,
total: 5,
};
render(<SearchSection />);
const err = await screen.findByTestId('settings-search-provider-error');
expect(err.textContent).toContain('rejected it');
expect(screen.queryByTestId('settings-search-needs-key')).toBeNull();
});
test('on + terminal vector-size drift: asks for a restart', async () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: true,
keyNotRequired: false,
keySource: 'file',
keyHint: 'a1b2',
ready: true,
capable: false,
embedded: 0,
total: 5,
providerError: true,
providerErrorReason: 'dimensions',
};
render(<SearchSection />);
const alert = await screen.findByTestId('settings-search-restart-required');
expect(alert.textContent).toContain('OpenKnowledge restarts');
expect(screen.queryByTestId('settings-search-provider-error')).toBeNull();
});
test('on + ignored configured dimensions: points back to the config key', async () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true, dimensions: 1536 });
mockStatus = {
enabled: true,
keyPresent: true,
keyNotRequired: false,
keySource: 'file',
keyHint: 'a1b2',
ready: true,
capable: false,
embedded: 0,
total: 5,
providerError: true,
providerErrorReason: 'configured_dimensions',
};
render(<SearchSection />);
const alert = await screen.findByTestId('settings-search-dimensions-mismatch');
expect(alert.textContent).toContain(
"Remove search.semantic.dimensions to use the model's own size",
);
expect(screen.queryByTestId('settings-search-provider-error')).toBeNull();
});
test('on + keyed but not warmed: shows the pending state', async () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: true,
keyNotRequired: false,
keySource: 'file',
keyHint: 'a1b2',
ready: false,
capable: false,
embedded: 0,
total: 5,
};
render(<SearchSection />);
const pending = await screen.findByTestId('settings-search-pending');
expect(pending.textContent).toContain('activates the first time');
expect(screen.queryByTestId('settings-search-needs-key')).toBeNull();
expect(screen.queryByTestId('settings-search-coverage')).toBeNull();
});
test('on but server not yet settled: shows the applying state', async () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: false,
keyPresent: false,
keyNotRequired: false,
keySource: null,
keyHint: null,
ready: false,
capable: false,
embedded: 0,
total: 5,
};
render(<SearchSection />);
await waitFor(() =>
expect(screen.getByTestId('settings-search-settling').textContent).toContain(
'Applying your change',
),
);
});
test('cancelling the confirm dialog writes nothing and leaves the toggle off', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await user.click(screen.getByTestId('settings-search-semantic-toggle'));
await user.click(await screen.findByRole('button', { name: /cancel/i }));
expect(calls.length).toBe(0);
expect(screen.getByTestId('settings-search-semantic-toggle').getAttribute('aria-checked')).toBe(
'false',
);
});
test('write failure keeps the confirm dialog open for retry (egress consent invariant)', async () => {
const user = userEvent.setup();
const failBinding = {
...makeBinding().binding,
patch: () => ({ ok: false, error: { code: 'noop', message: 'fail' } }),
} as unknown as ConfigBinding;
mockProjectLocalBinding = failBinding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await user.click(screen.getByTestId('settings-search-semantic-toggle'));
await user.click(await screen.findByTestId('settings-search-confirm-enable'));
expect(await screen.findByTestId('settings-search-confirm')).toBeDefined();
});
async function openCustomEndpoint(user: ReturnType<typeof userEvent.setup>) {
await user.click(screen.getByTestId('settings-search-custom-endpoint-trigger'));
return screen.getByTestId('settings-search-base-url') as HTMLInputElement;
}
async function openPerformanceTuning(user: ReturnType<typeof userEvent.setup>) {
const trigger = screen.getByTestId('settings-search-performance-trigger');
if (screen.queryByTestId('settings-search-max-batch-size') === null) await user.click(trigger);
}
async function confirmProviderChange(user: ReturnType<typeof userEvent.setup>) {
await user.click(await screen.findByTestId('settings-search-provider-confirm-apply'));
}
const DEFAULT_MODEL = 'text-embedding-3-small';
test('shows the default endpoint and model when nothing is overridden', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
const input = await openCustomEndpoint(user);
expect(input.value).toBe(DEFAULT_EMBEDDINGS_BASE_URL);
expect((screen.getByTestId('settings-search-model') as HTMLInputElement).value).toBe(
DEFAULT_MODEL,
);
});
test('shows legacy transport defaults and does not persist machine-specific values in a new project', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await openPerformanceTuning(user);
expect((screen.getByTestId('settings-search-max-batch-size') as HTMLInputElement).value).toBe(
String(DEFAULT_EMBEDDINGS_MAX_BATCH_SIZE),
);
expect((screen.getByTestId('settings-search-max-batch-chars') as HTMLInputElement).value).toBe(
String(DEFAULT_EMBEDDINGS_MAX_BATCH_CHARS),
);
expect(
(screen.getByTestId('settings-search-doc-timeout-seconds') as HTMLInputElement).value,
).toBe(String(DEFAULT_EMBEDDINGS_DOC_TIMEOUT_MS / 1000));
expect(calls).toEqual([]);
});
test('describes tuning controls in terms of embedding requests', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await openPerformanceTuning(user);
expect(screen.getByTestId('settings-search-performance-trigger').textContent).toContain(
'Embedding request settings',
);
expect(
screen.getByText(
'Adjust indexing request size and timeout for slow or memory-constrained embedding servers. Most setups should keep the defaults.',
),
).toBeDefined();
expect(screen.getByLabelText('Maximum text chunks per indexing request')).toBeDefined();
expect(
screen.getByText(
'Lower this to reduce memory use and work per request. Smaller batches send more requests and may make indexing slower overall.',
),
).toBeDefined();
expect(screen.getByLabelText('Character budget per indexing request')).toBeDefined();
expect(
screen.getByText(
'Limits the combined text sent in each request. A single larger chunk is sent on its own; documents are not split again.',
),
).toBeDefined();
expect(screen.getByLabelText('Indexing request timeout (seconds)')).toBeDefined();
expect(
screen.getByText(
'How long OpenKnowledge waits for each embedding request while indexing. Search requests use a fixed 8-second timeout per attempt, unchanged by this setting.',
),
).toBeDefined();
});
test('reaches the tuning controls without opening the Custom endpoint disclosure', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
expect(screen.queryByTestId('settings-search-base-url')).toBeNull();
await user.click(screen.getByTestId('settings-search-performance-trigger'));
expect(screen.getByTestId('settings-search-max-batch-size')).toBeDefined();
expect(screen.queryByTestId('settings-search-base-url')).toBeNull();
});
test('describes the custom endpoint disclosure', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await openCustomEndpoint(user);
expect(
screen.getByText(
'Point semantic search at any OpenAI-compatible embeddings endpoint — a self-hosted server or another provider. The API key above is for whichever endpoint you set here.',
),
).toBeDefined();
expect(
screen.getByText('Clear the field to reset back to the default OpenAI endpoint.'),
).toBeDefined();
expect(screen.queryByTestId('settings-search-max-batch-size')).toBeNull();
});
test('existing transport overrides auto-expand and display seconds for the timeout', () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({
enabled: false,
maxBatchSize: 2,
maxBatchChars: 16_000,
docTimeoutMs: 120_000,
});
render(<SearchSection />);
expect((screen.getByTestId('settings-search-max-batch-size') as HTMLInputElement).value).toBe(
'2',
);
expect((screen.getByTestId('settings-search-max-batch-chars') as HTMLInputElement).value).toBe(
'16000',
);
expect(
(screen.getByTestId('settings-search-doc-timeout-seconds') as HTMLInputElement).value,
).toBe('120');
});
test.each([
['settings-search-max-batch-size', 'maxBatchSize', '2', 2],
['settings-search-max-batch-size', 'maxBatchSize', '1', 1],
['settings-search-max-batch-size', 'maxBatchSize', '2048', 2048],
['settings-search-max-batch-chars', 'maxBatchChars', '16000', 16_000],
['settings-search-max-batch-chars', 'maxBatchChars', '1', 1],
['settings-search-max-batch-chars', 'maxBatchChars', '16384000', 16_384_000],
['settings-search-doc-timeout-seconds', 'docTimeoutMs', '120', 120_000],
['settings-search-doc-timeout-seconds', 'docTimeoutMs', '0.001', 1],
['settings-search-doc-timeout-seconds', 'docTimeoutMs', '600', 600_000],
])(
'commits %s directly without a provider-change confirmation',
async (id, key, draft, value) => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await openPerformanceTuning(user);
const input = screen.getByTestId(id);
await user.clear(input);
await user.type(input, `${draft}{Enter}`);
expect(calls).toEqual([{ search: { semantic: { [key]: value } } }]);
expect(screen.queryByTestId(`${id}-error`)).toBeNull();
expect(screen.queryByTestId('settings-search-provider-confirm')).toBeNull();
},
);
test('resetting the final override keeps the disclosure open and the field focused', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding(() => {
mockProjectLocalConfig = configWithSemantic({ enabled: false });
view.rerender(<SearchSection />);
});
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false, maxBatchSize: 2 });
const view = render(<SearchSection />);
const input = screen.getByTestId('settings-search-max-batch-size');
await user.clear(input);
await user.keyboard('{Enter}');
expect(calls).toEqual([
{ search: { semantic: { maxBatchSize: DEFAULT_EMBEDDINGS_MAX_BATCH_SIZE } } },
]);
expect(screen.getByTestId('settings-search-max-batch-size')).toBe(input);
expect(document.activeElement).toBe(input);
expect(
screen.getByTestId('settings-search-performance-trigger').getAttribute('aria-expanded'),
).toBe('true');
expect(screen.getByTestId('settings-search-max-batch-size-saved').textContent).toBe('Saved');
});
test('a tuning commit refreshes status immediately and after the server settles', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true, maxBatchSize: 2 });
mockStatus = {
enabled: true,
keyPresent: true,
keyNotRequired: false,
keySource: 'file',
keyHint: 'a1b2',
ready: true,
capable: true,
embedded: 4,
total: 4,
};
const fetchStatus = vi.fn(global.fetch);
global.fetch = fetchStatus;
render(<SearchSection />);
await screen.findByTestId('settings-search-coverage');
mockStatus = { ...mockStatus, ready: false };
const input = screen.getByTestId('settings-search-max-batch-size');
await user.clear(input);
await user.type(input, '4');
fetchStatus.mockClear();
vi.useFakeTimers();
fireEvent.keyDown(input, { key: 'Enter' });
await act(async () => {});
expect(fetchStatus).toHaveBeenCalledTimes(1);
expect(screen.getByTestId('settings-search-pending')).toBeTruthy();
mockStatus = { ...mockStatus, ready: true };
await act(() => vi.advanceTimersByTimeAsync(2500));
expect(fetchStatus).toHaveBeenCalledTimes(2);
expect(screen.getByTestId('settings-search-coverage').textContent).toContain('Indexed 4 of 4');
await act(() => vi.advanceTimersByTimeAsync(2500));
expect(fetchStatus).toHaveBeenCalledTimes(3);
});
test('Saved feedback expires, clears when editing resumes, and timers stop on unmount', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false, maxBatchSize: 2 });
const view = render(<SearchSection />);
const input = screen.getByTestId('settings-search-max-batch-size');
await user.clear(input);
await user.type(input, '4');
vi.useFakeTimers();
fireEvent.keyDown(input, { key: 'Enter' });
const help = screen.getByTestId('settings-search-max-batch-size-help');
const message = screen.getByTestId('settings-search-max-batch-size-saved');
expect(message.textContent).toBe('Saved');
expect(help.textContent).toContain('Lower this');
expect(help.getAttribute('aria-live')).toBeNull();
expect(message.getAttribute('aria-live')).toBe('polite');
await act(() => vi.advanceTimersByTimeAsync(1500));
expect(message.textContent).toBe('');
expect(help.textContent).toContain('Lower this');
fireEvent.change(input, { target: { value: '5' } });
fireEvent.keyDown(input, { key: 'Enter' });
expect(message.textContent).toBe('Saved');
fireEvent.change(input, { target: { value: '6' } });
expect(message.textContent).toBe('');
fireEvent.keyDown(input, { key: 'Enter' });
view.unmount();
expect(vi.getTimerCount()).toBe(0);
});
test.each([
['settings-search-max-batch-size', 'Lower this'],
['settings-search-max-batch-chars', 'Limits the combined text'],
['settings-search-doc-timeout-seconds', 'How long OpenKnowledge waits'],
])('associates %s with stable help, status, and reset instructions', async (id, help) => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await openPerformanceTuning(user);
expect(describedTextOf(id)).toContain(help);
expect(describedTextOf(id)).toContain('Clear a field to restore its default value.');
expect(screen.getByTestId(id).getAttribute('aria-describedby')?.split(' ')).toContain(
`${id}-message`,
);
expect(screen.getByTestId(`${id}-help`).getAttribute('aria-live')).toBeNull();
const status = screen.getByTestId(`${id}-saved`);
expect(status.getAttribute('aria-live')).toBe('polite');
expect(status.textContent).toBe('');
});
test('clearing tuning fields resets them to the OpenKnowledge defaults', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false, maxBatchSize: 2 });
render(<SearchSection />);
const input = screen.getByTestId('settings-search-max-batch-size');
await user.clear(input);
await user.tab();
expect(calls).toEqual([
{ search: { semantic: { maxBatchSize: DEFAULT_EMBEDDINGS_MAX_BATCH_SIZE } } },
]);
expect((input as HTMLInputElement).value).toBe(String(DEFAULT_EMBEDDINGS_MAX_BATCH_SIZE));
});
test('clearing the timeout resets it to the default in milliseconds, shown in seconds', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false, docTimeoutMs: 120_000 });
render(<SearchSection />);
const input = screen.getByTestId('settings-search-doc-timeout-seconds');
await user.clear(input);
await user.tab();
expect(calls).toEqual([
{ search: { semantic: { docTimeoutMs: DEFAULT_EMBEDDINGS_DOC_TIMEOUT_MS } } },
]);
expect((input as HTMLInputElement).value).toBe(
String(DEFAULT_EMBEDDINGS_DOC_TIMEOUT_MS / 1000),
);
});
test('blurring an unchanged tuning field writes nothing to project-local config', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await openPerformanceTuning(user);
await user.click(screen.getByTestId('settings-search-max-batch-size'));
await user.tab();
await user.click(screen.getByTestId('settings-search-doc-timeout-seconds'));
await user.tab();
expect(calls).toEqual([]);
});
test('a sub-second timeout set outside the UI round-trips instead of erroring', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false, docTimeoutMs: 1500 });
render(<SearchSection />);
const input = screen.getByTestId('settings-search-doc-timeout-seconds');
expect((input as HTMLInputElement).value).toBe('1.5');
await user.click(input);
await user.tab();
expect(calls).toEqual([]);
expect(screen.queryByTestId('settings-search-doc-timeout-seconds-error')).toBeNull();
await user.clear(input);
await user.type(input, '2.5{Enter}');
expect(calls).toEqual([{ search: { semantic: { docTimeoutMs: 2500 } } }]);
});
test.each(['0', '-1', '1.5', '2049', 'not-a-number'])(
'rejects invalid tuning input %s with accessible inline feedback',
async (invalid) => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await openPerformanceTuning(user);
const input = screen.getByTestId('settings-search-max-batch-size');
await user.clear(input);
await user.type(input, `${invalid}{Enter}`);
expect(calls).toEqual([]);
expect(input.getAttribute('aria-invalid')).toBe('true');
expect(input.getAttribute('aria-describedby')?.split(' ')).toContain(
'settings-search-max-batch-size-message',
);
const message = screen.getByTestId('settings-search-max-batch-size-error');
expect(message.getAttribute('aria-live')).toBe('polite');
expect(message.textContent).toContain('whole number between 1 and 2,048');
},
);
test.each(['0', '-1', '0.0009', '600.001', '120000', 'not-a-number'])(
'rejects invalid timeout %s and explains the range in seconds',
async (invalid) => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await openPerformanceTuning(user);
const input = screen.getByTestId('settings-search-doc-timeout-seconds');
await user.clear(input);
await user.type(input, `${invalid}{Enter}`);
expect(calls).toEqual([]);
expect(input.getAttribute('aria-invalid')).toBe('true');
expect(describedTextOf('settings-search-doc-timeout-seconds')).toContain(
'seconds between 0.001 and 600',
);
},
);
test('rejects a character budget above its bound without writing config', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await openPerformanceTuning(user);
const input = screen.getByTestId('settings-search-max-batch-chars');
await user.clear(input);
await user.type(input, '16384001{Enter}');
expect(calls).toEqual([]);
expect(describedTextOf('settings-search-max-batch-chars')).toContain(
'whole number between 1 and 16,384,000',
);
});
test.each([
['en', 'settings-search-max-batch-chars', '16384001', '16,384,000'],
['fr', 'settings-search-max-batch-chars', '16384001', '16\u202f384\u202f000'],
['fr', 'settings-search-doc-timeout-seconds', '0', '0,001'],
])('formats the %s locale bounds in %s errors', async (locale, id, value, expected) => {
i18n.loadAndActivate({ locale, messages: {} });
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await openPerformanceTuning(user);
const input = screen.getByTestId(id);
await user.clear(input);
await user.type(input, `${value}{Enter}`);
expect(calls).toEqual([]);
expect(screen.getByTestId(`${id}-error`).textContent).toContain(expected);
});
test('tuning inputs remain disabled until the project-local binding has synced', () => {
mockProjectLocalBinding = null;
mockProjectLocalSynced = false;
mockProjectLocalConfig = configWithSemantic({ enabled: false, maxBatchSize: 2 });
render(<SearchSection />);
expect(
screen.getByTestId('settings-search-max-batch-size').getAttribute('disabled'),
).not.toBeNull();
});
test('external config changes reseed tuning drafts', async () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false, maxBatchSize: 2 });
const view = render(<SearchSection />);
expect((screen.getByTestId('settings-search-max-batch-size') as HTMLInputElement).value).toBe(
'2',
);
mockProjectLocalConfig = configWithSemantic({ enabled: false, maxBatchSize: 4 });
view.rerender(<SearchSection />);
await waitFor(() =>
expect((screen.getByTestId('settings-search-max-batch-size') as HTMLInputElement).value).toBe(
'4',
),
);
});
test('a tuning patch failure preserves the draft and exposes an inline live error', async () => {
const user = userEvent.setup();
const failBinding = {
...makeBinding().binding,
patch: () => ({ ok: false, error: { code: 'noop', message: 'disk unavailable' } }),
} as unknown as ConfigBinding;
mockProjectLocalBinding = failBinding;
mockProjectLocalConfig = configWithSemantic({ enabled: false, maxBatchSize: 2 });
render(<SearchSection />);
const input = screen.getByTestId('settings-search-max-batch-size') as HTMLInputElement;
await user.clear(input);
await user.type(input, '4{Enter}');
expect(input.value).toBe('4');
const error = screen.getByTestId('settings-search-max-batch-size-error');
expect(error.getAttribute('aria-live')).toBe('polite');
expect(error.textContent).toContain('Failed to update performance setting');
});
test('the disclosure starts open when a custom endpoint is already configured', () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({
enabled: false,
baseUrl: 'https://my-vllm.internal/v1',
});
render(<SearchSection />);
expect((screen.getByTestId('settings-search-base-url') as HTMLInputElement).value).toBe(
'https://my-vllm.internal/v1',
);
});
test('the disclosure starts open when only the model is overridden', () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false, model: 'nomic-embed-text' });
render(<SearchSection />);
expect((screen.getByTestId('settings-search-model') as HTMLInputElement).value).toBe(
'nomic-embed-text',
);
});
test('blurring the endpoint field writes the trimmed custom base URL after confirmation', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
const input = await openCustomEndpoint(user);
await user.clear(input);
await user.type(input, ' https://azure.example.com/openai/v1/ ');
await user.tab();
expect(calls).toEqual([]);
await confirmProviderChange(user);
expect(calls).toEqual([
{
search: {
semantic: { baseUrl: 'https://azure.example.com/openai/v1/', model: DEFAULT_MODEL },
},
},
]);
});
test('pressing Enter in the endpoint field commits the same way', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
const input = await openCustomEndpoint(user);
await user.clear(input);
await user.type(input, ' https://azure.example.com/openai/v1/ {Enter}');
await confirmProviderChange(user);
expect(calls).toEqual([
{
search: {
semantic: { baseUrl: 'https://azure.example.com/openai/v1/', model: DEFAULT_MODEL },
},
},
]);
});
test('a custom model is written as free text', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
await openCustomEndpoint(user);
const model = screen.getByTestId('settings-search-model');
await user.clear(model);
await user.type(model, 'nomic-embed-text{Enter}');
await confirmProviderChange(user);
expect(calls).toEqual([
{
search: { semantic: { baseUrl: DEFAULT_EMBEDDINGS_BASE_URL, model: 'nomic-embed-text' } },
},
]);
});
test('clearing the model field resets it to the default', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false, model: 'nomic-embed-text' });
render(<SearchSection />);
const model = screen.getByTestId('settings-search-model');
await user.clear(model);
await user.tab();
await confirmProviderChange(user);
expect(calls).toEqual([
{ search: { semantic: { baseUrl: DEFAULT_EMBEDDINGS_BASE_URL, model: DEFAULT_MODEL } } },
]);
});
test('cancelling the warning restores the previous values and writes nothing', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
const input = await openCustomEndpoint(user);
await user.clear(input);
await user.type(input, 'https://my-vllm.internal/v1{Enter}');
await user.click(await screen.findByRole('button', { name: 'Cancel' }));
expect(calls).toEqual([]);
await waitFor(() =>
expect((screen.getByTestId('settings-search-base-url') as HTMLInputElement).value).toBe(
DEFAULT_EMBEDDINGS_BASE_URL,
),
);
});
test('clearing the endpoint field resets it to the default OpenAI endpoint', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({
enabled: false,
baseUrl: 'https://azure.example.com/openai/v1',
});
render(<SearchSection />);
const input = screen.getByTestId('settings-search-base-url');
await user.clear(input);
await user.tab();
await confirmProviderChange(user);
expect(calls).toEqual([
{ search: { semantic: { baseUrl: DEFAULT_EMBEDDINGS_BASE_URL, model: DEFAULT_MODEL } } },
]);
});
test('a malformed URL is not flagged mid-typing, but errors on commit and blocks the write', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
const input = await openCustomEndpoint(user);
await user.clear(input);
await user.type(input, 'not-a-url');
expect(screen.queryByTestId('settings-search-base-url-error')).toBeNull();
await user.tab();
expect(screen.getByTestId('settings-search-base-url-error')).toBeDefined();
expect(input.getAttribute('aria-invalid')).toBe('true');
expect(screen.queryByTestId('settings-search-provider-confirm')).toBeNull();
expect(calls).toEqual([]);
});
test('committing an invalid URL via Enter also errors and blocks the write', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
const input = await openCustomEndpoint(user);
await user.clear(input);
await user.type(input, 'not-a-url{Enter}');
expect(screen.getByTestId('settings-search-base-url-error')).toBeDefined();
expect(input.getAttribute('aria-invalid')).toBe('true');
expect(calls).toEqual([]);
});
test('a plaintext non-loopback endpoint errors on commit and blocks the write', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
const input = await openCustomEndpoint(user);
await user.clear(input);
await user.type(input, 'http://azure.example.com/v1');
await user.tab();
expect(screen.getByTestId('settings-search-base-url-error')).toBeDefined();
expect(calls).toEqual([]);
});
test('an http loopback endpoint is accepted (no error) and written', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
const input = await openCustomEndpoint(user);
await user.clear(input);
await user.type(input, 'http://localhost:11434/v1');
await user.tab();
await confirmProviderChange(user);
expect(screen.queryByTestId('settings-search-base-url-error')).toBeNull();
expect(calls).toEqual([
{ search: { semantic: { baseUrl: 'http://localhost:11434/v1', model: DEFAULT_MODEL } } },
]);
});
test('after a failed commit, fixing the value clears the error live and writes on re-commit', async () => {
const user = userEvent.setup();
const { binding, calls } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: false });
render(<SearchSection />);
const input = await openCustomEndpoint(user);
await user.clear(input);
await user.type(input, 'nope');
await user.tab();
expect(screen.getByTestId('settings-search-base-url-error')).toBeDefined();
await user.clear(input);
await user.type(input, 'https://azure.example.com/openai/v1');
expect(screen.queryByTestId('settings-search-base-url-error')).toBeNull();
expect(input.getAttribute('aria-invalid')).toBe('false');
await user.tab();
await confirmProviderChange(user);
expect(calls).toEqual([
{
search: {
semantic: { baseUrl: 'https://azure.example.com/openai/v1', model: DEFAULT_MODEL },
},
},
]);
});
test('a successful connection test reports the detected vector size', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({
enabled: true,
baseUrl: 'https://my-vllm.internal/v1',
model: 'nomic-embed-text',
});
render(
<SearchSection
transport={{
setKey: async () => ({ ok: true }),
clearKey: async () => ({ ok: true }),
testConnection: async () => ({
ok: true,
endpoint: 'https://my-vllm.internal/v1',
model: 'nomic-embed-text',
dimensions: 1024,
}),
}}
/>,
);
await user.click(screen.getByTestId('settings-search-test-connection'));
const result = await screen.findByTestId('settings-search-test-ok');
expect(result.textContent).toContain('1024');
});
test('a failing connection test names the specific reason', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({
enabled: true,
baseUrl: 'https://my-vllm.internal/v1',
});
render(
<SearchSection
transport={{
setKey: async () => ({ ok: true }),
clearKey: async () => ({ ok: true }),
testConnection: async () => ({
ok: false,
endpoint: 'https://my-vllm.internal/v1',
model: 'text-embedding-3-small',
reason: 'http_error',
status: 401,
}),
}}
/>,
);
await user.click(screen.getByTestId('settings-search-test-connection'));
const result = await screen.findByTestId('settings-search-test-error');
expect(result.textContent).toContain('401');
});
test('a verdict for a stale endpoint says so instead of reporting it', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({
enabled: true,
baseUrl: 'https://my-vllm.internal/v1',
});
render(
<SearchSection
transport={{
setKey: async () => ({ ok: true }),
clearKey: async () => ({ ok: true }),
testConnection: async () => ({
ok: true,
endpoint: DEFAULT_EMBEDDINGS_BASE_URL,
model: 'text-embedding-3-small',
dimensions: 1536,
}),
}}
/>,
);
await user.click(screen.getByTestId('settings-search-test-connection'));
expect(await screen.findByTestId('settings-search-test-stale')).toBeDefined();
expect(screen.queryByTestId('settings-search-test-ok')).toBeNull();
});
test('the API key field is always visible (not buried in the disclosure)', () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: false,
keyNotRequired: false,
keySource: null,
keyHint: null,
ready: false,
capable: false,
embedded: 0,
total: 3,
};
render(<SearchSection />);
expect(screen.getByTestId('settings-search-key-input')).toBeDefined();
});
test('saving a key calls the transport and refreshes', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: false,
keyNotRequired: false,
keySource: null,
keyHint: null,
ready: false,
capable: false,
embedded: 0,
total: 3,
};
const setKey = vi.fn(async () => ({ ok: true }) as const);
render(
<SearchSection
transport={{
setKey,
clearKey: async () => ({ ok: true }),
testConnection: async () => null,
}}
/>,
);
const input = await screen.findByTestId('settings-search-key-input');
await waitFor(() => expect((input as HTMLInputElement).disabled).toBe(false));
await user.type(input, 'sk-my-key');
await user.click(screen.getByTestId('settings-search-key-save'));
expect(setKey).toHaveBeenCalledWith('sk-my-key');
});
test('pressing Enter in the key field saves (parity with endpoint/model)', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: false,
keyNotRequired: false,
keySource: null,
keyHint: null,
ready: false,
capable: false,
embedded: 0,
total: 3,
};
const setKey = vi.fn(async () => ({ ok: true }) as const);
render(
<SearchSection
transport={{
setKey,
clearKey: async () => ({ ok: true }),
testConnection: async () => null,
}}
/>,
);
const input = await screen.findByTestId('settings-search-key-input');
await waitFor(() => expect((input as HTMLInputElement).disabled).toBe(false));
await user.type(input, 'sk-enter-key{Enter}');
expect(setKey).toHaveBeenCalledWith('sk-enter-key');
});
test('a failed key save surfaces the error, does not clear the input', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: false,
keyNotRequired: false,
keySource: null,
keyHint: null,
ready: false,
capable: false,
embedded: 0,
total: 3,
};
render(
<SearchSection
transport={{
setKey: async () => ({ ok: false, error: 'disk full' }),
clearKey: async () => ({ ok: true }),
testConnection: async () => null,
}}
/>,
);
const input = await screen.findByTestId('settings-search-key-input');
await waitFor(() => expect((input as HTMLInputElement).disabled).toBe(false));
await user.type(input, 'sk-doomed');
await user.click(screen.getByTestId('settings-search-key-save'));
const err = await screen.findByTestId('settings-search-key-error');
expect(err.textContent).toContain('disk full');
expect((input as HTMLInputElement).value).toBe('sk-doomed');
});
test('a present key shows a redacted hint + Clear, never the key', async () => {
const user = userEvent.setup();
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({ enabled: true });
mockStatus = {
enabled: true,
keyPresent: true,
keyNotRequired: false,
keySource: 'project',
keyHint: '9xяz'.slice(-4),
ready: true,
capable: true,
embedded: 3,
total: 3,
};
const clearKey = vi.fn(async () => ({ ok: true }) as const);
render(
<SearchSection
transport={{
setKey: async () => ({ ok: true }),
clearKey,
testConnection: async () => null,
}}
/>,
);
expect(await screen.findByTestId('settings-search-key-hint')).toBeDefined();
await user.click(screen.getByTestId('settings-search-key-clear'));
expect(clearKey).toHaveBeenCalled();
});
test('a loopback endpoint shows the key as not required, and no needs-key nag', async () => {
const { binding } = makeBinding();
mockProjectLocalBinding = binding;
mockProjectLocalConfig = configWithSemantic({
enabled: true,
baseUrl: 'http://localhost:11434/v1',
});
mockStatus = {
enabled: true,
keyPresent: false,
keyNotRequired: true,
keySource: null,
keyHint: null,
ready: false,
capable: false,
embedded: 0,
total: 3,
};
render(<SearchSection />);
await waitFor(() =>
expect(screen.getByTestId('settings-search-key').textContent).toContain('Not required'),
);
expect(screen.queryByTestId('settings-search-needs-key')).toBeNull();
});
});