~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
/**
* Shared Test Utilities
*
* Provides common functionality for UI tests:
* - Browser setup/teardown
* - Configuration management
* - Helper functions (delay, waitFor, screenshot)
* - Logging utilities
*/
const puppeteer = require('puppeteer');
const fs = require('fs');
const path = require('path');
const AuthHelper = require('../auth_helper');
const { getPuppeteerLaunchOptions } = require('../puppeteer_config');
// Centralized configuration - single source of truth
const config = {
baseUrl: process.env.BASE_URL || process.env.TEST_BASE_URL || 'http://127.0.0.1:5000',
isCI: process.env.CI === 'true',
headless: process.env.HEADLESS !== 'false',
screenshotDir: path.join(__dirname, '..', 'screenshots'),
resultsDir: path.join(__dirname, '..', 'test-results'),
timeout: parseInt(process.env.TEST_TIMEOUT, 10) || 30000,
slowMo: parseInt(process.env.SLOW_MO, 10) || 0,
};
// Default viewport settings
const viewports = {
desktop: { width: 1280, height: 800 },
mobile: { width: 375, height: 667, isMobile: true, hasTouch: true },
tablet: { width: 768, height: 1024, isMobile: true, hasTouch: true },
};
/**
* Initialize test environment with browser and optional authentication
*
* @param {Object} options - Setup options
* @param {boolean} [options.authenticate=true] - Whether to authenticate the user
* @param {boolean} [options.headless] - Override headless mode
* @param {Object} [options.viewport] - Viewport settings (or use 'desktop', 'mobile', 'tablet')
* @param {string} [options.username] - Custom username for authentication
* @param {string} [options.password] - Custom password for authentication
* @returns {Promise<Object>} Context object with browser, page, authHelper, config
*/
async function setupTest(options = {}) {
const launchOptions = getPuppeteerLaunchOptions({
headless: options.headless ?? config.headless,
slowMo: options.slowMo ?? config.slowMo,
});
const browser = await puppeteer.launch(launchOptions);
const page = await browser.newPage();
// Set viewport
let viewport = options.viewport;
if (typeof viewport === 'string' && viewports[viewport]) {
viewport = viewports[viewport];
}
await page.setViewport(viewport || viewports.desktop);
// Set default timeouts to avoid indefinite hangs in CI
const timeout = config.isCI ? 60000 : config.timeout;
page.setDefaultTimeout(timeout);
page.setDefaultNavigationTimeout(timeout);
// Create auth helper
const authHelper = new AuthHelper(page, config.baseUrl);
// Authenticate if requested (default: true)
if (options.authenticate !== false) {
const authTimeoutMs = config.isCI ? 120000 : 30000;
await withTimeout(
authHelper.ensureAuthenticated(options.username, options.password),
authTimeoutMs,
'authentication'
);
}
// Return context object
// Use authHelper.getPage() because ensureAuthenticated() may have created
// a fresh page if the original one hit a detached frame error
const finalPage = authHelper.getPage();
finalPage.setDefaultTimeout(timeout);
finalPage.setDefaultNavigationTimeout(timeout);
return {
browser,
page: finalPage,
authHelper,
config,
viewports,
};
}
/**
* Clean up test environment
*
* @param {Object} context - Context object from setupTest
*/
async function teardownTest(context) {
if (context && context.browser) {
await context.browser.close();
}
}
/**
* Take a screenshot with auto-directory creation
*
* @param {Object} page - Puppeteer page object
* @param {string} name - Screenshot name (without extension)
* @param {Object} [options] - Screenshot options
* @param {boolean} [options.fullPage=true] - Capture full page
* @returns {Promise<string>} Path to saved screenshot
*/
async function screenshot(page, name, options = {}) {
const dir = config.screenshotDir;
if (!fs.existsSync(dir)) {
fs.mkdirSync(dir, { recursive: true });
}
const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
const filename = `${name}_${timestamp}.png`;
const filepath = path.join(dir, filename);
await page.screenshot({
path: filepath,
fullPage: options.fullPage !== false,
...options,
});
return filepath;
}
/**
* Simple delay function
*
* @param {number} ms - Milliseconds to wait
* @returns {Promise<void>}
*/
const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
/**
* Run a promise with a timeout. If the promise doesn't resolve within
* the given time, it rejects with a TimeoutError. This prevents a single
* hung sub-test from blocking the entire test suite until the 300s
* process-level timeout kills it.
*
* @param {Promise} promise - The promise to race against the timeout
* @param {number} ms - Timeout in milliseconds (default: 30s CI, 15s local)
* @param {string} [label] - Description for the timeout error message
* @returns {Promise} The original promise result or a timeout rejection
*/
function withTimeout(promise, ms, label = 'operation') {
const timeoutMs = ms || (config.isCI ? 30000 : 15000);
return new Promise((resolve, reject) => {
const timer = setTimeout(() => {
reject(new Error(`Timeout: ${label} did not complete within ${timeoutMs / 1000}s`));
}, timeoutMs);
promise.then(
(val) => { clearTimeout(timer); resolve(val); },
(err) => { clearTimeout(timer); reject(err); }
);
});
}
/**
* Navigate to a page, skipping if already there.
*
* Many CI tests call page.goto() for the same URL in every test function.
* Each navigation takes 5-15s in CI, so 15 tests × 10s = 150s+ of pure
* navigation overhead. This helper skips the navigation when the page URL
* already matches, cutting test suite time significantly.
*
* @param {Object} page - Puppeteer page object
* @param {string} url - Full URL to navigate to
* @param {Object} [options] - Navigation options
* @returns {Promise<void>}
*/
async function navigateTo(page, url, options = {}) {
const currentUrl = page.url();
// Check if already on the target page (compare path, ignore query/hash)
const targetPath = new URL(url).pathname.replace(/\/$/, '');
try {
const currentPath = new URL(currentUrl).pathname.replace(/\/$/, '');
if (currentPath === targetPath) {
return null;
}
} catch {
// about:blank or invalid URL — need to navigate
}
const response = await page.goto(url, {
waitUntil: 'domcontentloaded',
timeout: config.isCI ? 60000 : config.timeout,
...options,
});
return response;
}
/**
* Run `fn` with a page in a new browser context, then close that context.
*
* Use this to check what a signed-out visitor gets. A new browser context
* starts with its own empty cookie jar, so its requests carry no session
* cookie and nothing the signed-in page does can add one. The signed-in page
* keeps its session, so the caller does not need to log in again afterwards.
*
* Clearing the signed-in page's cookies instead is racy. The server re-sends
* the session cookie on authenticated responses: for a login without
* "Remember me", which is how these tests sign in, DatabaseMiddleware
* re-stamps the session's expiry on each response it sends, so Starlette's
* SessionMiddleware sends the changed session again. A response to a request
* the page sent before the clear can therefore put the session cookie back.
*
* @param {Object} page - Any page of the browser to use
* @param {Function} fn - Async callback that receives the new page
* @returns {Promise<*>} The callback's result
*/
async function withFreshBrowserContext(page, fn) {
const context = await page.browser().createBrowserContext();
try {
const freshPage = await context.newPage();
const timeout = config.isCI ? 60000 : config.timeout;
freshPage.setDefaultTimeout(timeout);
freshPage.setDefaultNavigationTimeout(timeout);
return await fn(freshPage);
} finally {
// Best effort: a failed close must not hide fn's result or error.
await context.close().catch(() => {});
}
}
/**
* Wait for an element with better error messages
*
* @param {Object} page - Puppeteer page object
* @param {string} selector - CSS selector
* @param {Object} [options] - Wait options
* @param {number} [options.timeout] - Timeout in ms
* @param {boolean} [options.visible] - Wait for visible element
* @returns {Promise<boolean>}
*/
async function waitFor(page, selector, options = {}) {
const timeout = options.timeout || config.timeout;
try {
await page.waitForSelector(selector, {
timeout,
visible: options.visible,
});
return true;
} catch {
throw new Error(`Element "${selector}" not found after ${timeout}ms`);
}
}
/**
* Wait for element to become visible (using waitForFunction for reliability)
*
* @param {Object} page - Puppeteer page object
* @param {string} selector - CSS selector
* @param {number} [timeout] - Timeout in ms
* @returns {Promise<boolean>}
*/
async function waitForVisible(page, selector, timeout = 5000) {
try {
await page.waitForFunction(
(sel) => {
const el = document.querySelector(sel);
if (!el) return false;
const style = window.getComputedStyle(el);
return style.display !== 'none' && style.visibility !== 'hidden';
},
{ timeout },
selector
);
return true;
} catch {
return false;
}
}
/**
* Click an element and wait for navigation
*
* @param {Object} page - Puppeteer page object
* @param {string} selector - CSS selector to click
* @param {Object} [options] - Navigation options
* @returns {Promise<void>}
*/
async function clickAndWaitForNavigation(page, selector, options = {}) {
const waitUntil = options.waitUntil || 'domcontentloaded';
const timeout = options.timeout || config.timeout;
await Promise.all([
page.waitForNavigation({ waitUntil, timeout }),
page.click(selector),
]);
}
/**
* Get the value of an input element
*
* @param {Object} page - Puppeteer page object
* @param {string} selector - CSS selector
* @returns {Promise<string>}
*/
async function getInputValue(page, selector) {
return page.$eval(selector, el => el.value);
}
/**
* Clear and type into an input
*
* @param {Object} page - Puppeteer page object
* @param {string} selector - CSS selector
* @param {string} text - Text to type
* @returns {Promise<void>}
*/
async function clearAndType(page, selector, text) {
await page.click(selector, { clickCount: 3 });
await page.keyboard.press('Backspace');
await page.type(selector, text);
}
/**
* Find an action button on the current page by word-boundary keyword match
* against its text content, and optionally click it.
*
* Word boundaries (`\b`) keep the match from firing on substrings — e.g.
* the default keyword `new` matches "New Folder" but NOT "Back to News
* Feed" (where "news" merely contains "new"). The original substring
* matcher caused #4069.
*
* @param {import('puppeteer').Page} page
* @param {Object} [options]
* @param {string} [options.selectors] CSS selector list to scan.
* Default: `'button, a.btn, .btn'`.
* @param {string[]} [options.keywords] Lowercase words to match (combined
* into `\b(?:k1|k2|...)\b`). Default: `['create', 'new', 'add']`.
* @param {boolean} [options.click] If true, click the first match.
* @returns {Promise<{found: boolean, text?: string}>}
*/
async function findActionButton(page, options = {}) {
const {
selectors = 'button, a.btn, .btn',
keywords = ['create', 'new', 'add'],
click = false,
} = options;
return await page.evaluate((selectorsStr, keywordsArr, doClick) => {
const pattern = new RegExp(`\\b(?:${keywordsArr.join('|')})\\b`);
const buttons = Array.from(document.querySelectorAll(selectorsStr));
const match = buttons.find(b => pattern.test((b.textContent || '').toLowerCase()));
if (!match) return { found: false };
if (doClick) match.click();
return { found: true, text: match.textContent?.trim() };
}, selectors, keywords, click);
}
/**
* Expand the Settings section that owns a control, so it can be clicked.
*
* Settings sections start collapsed on EVERY viewport now (not just mobile):
* `initAccordions()` puts `.collapsed` on the section body and
* `.ldr-settings-section-body.collapsed { display: none }` in settings.css
* takes it out of the layout. A control inside one is present in the DOM —
* so `waitForSelector` (whose `visible` option defaults to false) still
* resolves — but it has no box, so `page.click()` / `elementHandle.click()`
* throws or lands on whatever is actually at those coordinates.
*
* Call this before interacting with any settings control. It finds the
* closest `.ldr-settings-section-body.collapsed` ancestor of the target and
* clicks that section's `.ldr-settings-section-header`, then waits for the
* body to lose `collapsed`. A target that is already visible, or that is not
* inside a section at all, is left alone.
*
* @param {import('puppeteer').Page} page
* @param {string|import('puppeteer').ElementHandle} target - CSS selector for
* the control, or an ElementHandle for it.
* @param {Object} [options]
* @param {number} [options.timeout] - Wait budget for the target and for the
* section to open. Defaults to the shared config timeout.
* @returns {Promise<string>} One of 'already-expanded' | 'expanded' |
* 'no-section' | 'no-header' | 'no-target' — for logging; callers that just
* want the control clickable can ignore it.
*/
async function expandSettingsSectionFor(page, target, options = {}) {
const timeout = options.timeout || config.timeout;
// Runs in page context with the target element as its argument.
const expandFor = (el) => {
if (!el) return 'no-target';
const body = el.closest('.ldr-settings-section-body');
if (!body) return 'no-section';
if (!body.classList.contains('collapsed')) return 'already-expanded';
// Resolve the header by node relationship / data-target equality
// instead of building a selector from body.id, which is derived from
// a server-supplied category name.
let header = body.previousElementSibling;
if (!header || !header.classList.contains('ldr-settings-section-header')) {
header = Array.from(document.querySelectorAll('.ldr-settings-section-header'))
.find(candidate => candidate.dataset.target === body.id) || null;
}
if (!header) return 'no-header';
header.click();
return 'expanded';
};
let outcome;
if (typeof target === 'string') {
await page.waitForSelector(target, { timeout });
outcome = await page.$eval(target, expandFor);
} else {
outcome = await page.evaluate(expandFor, target);
}
// Wait for the section to actually open. The click handler applies the
// class synchronously, but polling beats racing the DOM swap.
if (outcome === 'expanded') {
if (typeof target === 'string') {
await page.waitForFunction(
(sel) => {
const el = document.querySelector(sel);
if (!el) return false;
const body = el.closest('.ldr-settings-section-body');
return !body || !body.classList.contains('collapsed');
},
{ timeout },
target
);
} else {
await page.waitForFunction(
(el) => {
if (!el) return false;
const body = el.closest('.ldr-settings-section-body');
return !body || !body.classList.contains('collapsed');
},
{ timeout },
target
);
}
}
return outcome;
}
/**
* Expand every collapsed Settings section on the page.
*
* Sections start collapsed on every viewport now, and
* `.ldr-settings-section-body.collapsed { display: none }` hides everything
* inside them. Any check that filters by visibility — `offsetParent === null`,
* `getComputedStyle(el).display` — is therefore blind to whatever those
* bodies contain, so a suite that means "nothing on the settings page shows an
* error" has to open the sections before it counts, or it passes vacuously.
*
* Clicks each collapsed header in page context, i.e. the same gesture a user
* makes, so the accordion's own handler runs (and, as for a user, the
* expanded state is remembered in localStorage). A page with no settings
* sections is left alone.
*
* @param {import('puppeteer').Page} page
* @param {Object} [options]
* @param {number} [options.timeout] - Wait budget for the sections to open.
* Defaults to the shared config timeout.
* @returns {Promise<number>} How many sections were expanded.
*/
async function expandAllSettingsSections(page, options = {}) {
const timeout = options.timeout || config.timeout;
const expanded = await page.evaluate(() => {
let clicked = 0;
document.querySelectorAll('.ldr-settings-section-header').forEach(header => {
// Resolve the body the way initAccordions does, by id, rather than
// building a selector out of a server-derived category name.
const body = document.getElementById(header.dataset.target);
if (body && body.classList.contains('collapsed')) {
header.click();
clicked++;
}
});
return clicked;
});
if (expanded > 0) {
await page.waitForFunction(
() => document.querySelectorAll('.ldr-settings-section-body.collapsed').length === 0,
{ timeout }
);
}
return expanded;
}
// Console logging with colors (works in terminal)
const log = {
info: (msg) => console.log(`\x1b[36m[INFO] ${msg}\x1b[0m`),
success: (msg) => console.log(`\x1b[32m[PASS] ${msg}\x1b[0m`),
error: (msg) => console.log(`\x1b[31m[FAIL] ${msg}\x1b[0m`),
warning: (msg) => console.log(`\x1b[33m[WARN] ${msg}\x1b[0m`),
section: (msg) => console.log(`\x1b[34m\n=== ${msg} ===\x1b[0m`),
debug: (msg) => {
if (process.env.DEBUG) {
console.log(`\x1b[90m[DEBUG] ${msg}\x1b[0m`);
}
},
};
module.exports = {
config,
viewports,
setupTest,
teardownTest,
screenshot,
delay,
withTimeout,
navigateTo,
withFreshBrowserContext,
waitFor,
waitForVisible,
clickAndWaitForNavigation,
getInputValue,
clearAndType,
findActionButton,
expandSettingsSectionFor,
expandAllSettingsSections,
log,
};