Skip to content

~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.

18.8 KB
Raw Blame
/**
 * 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,
};