learningcircuit--local-deep-research/tests/ui_tests/test_lib/test_utils.js

/**
 * 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;
}

/**
 * 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);
}

// 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,
    waitFor,
    waitForVisible,
    clickAndWaitForNavigation,
    getInputValue,
    clearAndType,
    findActionButton,
    log,
};