@leera.io/qa-runner 1.0.0

package/dist/src/drivers/web-playwright.js

@@ -0,0 +1,403 @@
+import { existsSync } from 'node:fs';
+import { mkdtemp } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { chromium } from 'playwright-core';
+import { DebugCollector } from '../debug.js';
+import { BROWSER_DEVICE_ID } from '../devices/types.js';
+import { resolveUrl } from '../template.js';
+import { clip, errorMessage, expectWithin, firstLine, matches, POLL_MS, render, requireTarget, verb, } from './common.js';
+import { Blocked, Unsupported, } from './driver.js';
+import { ariaRefSelector, refFromElementSnapshot, webScreen, webSnapshot } from './snapshot/aria.js';
+const NAVIGATION_TIMEOUT_MS = 30_000;
+/** Smaller than the viewport, which keeps a long case's video well under the upload limit. */
+const VIDEO_SIZE = { width: 1024, height: 576 };
+export const WEB_ACTIONS = [
+    'goto',
+    'click',
+    'hover',
+    'check',
+    'uncheck',
+    'fill',
+    'select_option',
+    'press',
+    'wait_for',
+    'wait',
+    'expect_visible',
+    'expect_hidden',
+    'expect_text',
+    'expect_url',
+    'expect_title',
+    'screenshot',
+];
+export function launchBrowser(options) {
+    return chromium.launch({
+        headless: options.headless,
+        ...(options.proxy ? { proxy: { server: options.proxy } } : {}),
+    });
+}
+/**
+ * Playwright's own ffmpeg, which `recordVideo` needs (`setup browsers` installs it with Chromium).
+ * Without it playwright-core 1.63 still opens the page, but every call on that page then waits
+ * forever, so video is only requested when ffmpeg is there. Null when it is not installed;
+ * undefined when this playwright-core no longer exposes its registry (video is then requested
+ * as before, and the unit test pinning this lookup fails on the upgrade).
+ */
+export function playwrightFfmpeg() {
+    let path;
+    try {
+        const core = createRequire(import.meta.url)('playwright-core/lib/coreBundle');
+        path = core.registry?.registry?.findExecutable?.('ffmpeg')?.executablePath?.('javascript');
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof path !== 'string' || !path)
+        return undefined;
+    return existsSync(path) ? path : null;
+}
+/** Warning logged when a job wants video but Playwright's ffmpeg is missing. */
+export const NO_FFMPEG_VIDEO = "video is not recorded: Playwright's ffmpeg is not installed (run `leera-qa-runner setup browsers`)";
+/** The Chromium executable Playwright would launch, or null when it is not installed. */
+export function chromiumExecutable() {
+    try {
+        const path = chromium.executablePath();
+        return path && existsSync(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** One browser shared by every web job of the process; relaunched when it disconnects. */
+export class BrowserPool {
+    browser = null;
+    launching = null;
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Wraps a browser someone else launched (tests). */
+    static of(browser) {
+        const pool = new BrowserPool({ headless: true });
+        pool.browser = browser;
+        return pool;
+    }
+    async get() {
+        if (this.browser?.isConnected())
+            return this.browser;
+        this.launching ??= launchBrowser(this.options)
+            .then((browser) => {
+            this.browser = browser;
+            return browser;
+        })
+            .finally(() => {
+            this.launching = null;
+        });
+        return this.launching;
+    }
+    async close() {
+        const browser = this.browser;
+        this.browser = null;
+        await browser?.close().catch(() => undefined);
+    }
+}
+export class WebPlaywrightDriver {
+    platform = 'web';
+    capabilities = {
+        actions: WEB_ACTIONS,
+        targets: ['role', 'label', 'placeholder', 'text', 'test_id', 'css'],
+        video: 'webm',
+    };
+    browser;
+    ctx;
+    context = null;
+    page = null;
+    collector = null;
+    video = null;
+    closed = false;
+    /** Set once a snapshot was taken, so `find` can report refs (they resolve against it). */
+    snapshotTaken = false;
+    constructor(browser, ctx) {
+        this.browser = browser;
+        this.ctx = ctx;
+    }
+    async launch() {
+        let recordVideo = this.ctx.video !== 'off';
+        if (recordVideo && playwrightFfmpeg() === null) {
+            this.ctx.log.warn(NO_FFMPEG_VIDEO);
+            recordVideo = false;
+        }
+        // A fresh context per job: no cookies, storage or cache carried over from the previous one.
+        this.context = await this.browser.newContext({
+            viewport: { width: 1366, height: 768 },
+            acceptDownloads: false,
+            ...(recordVideo ? { recordVideo: { dir: await mkdtemp(join(tmpdir(), 'qa-video-')), size: VIDEO_SIZE } } : {}),
+        });
+        const page = await this.context.newPage();
+        this.page = page;
+        // The video starts with the page, so step offsets are measured from here.
+        this.collector = new DebugCollector(Date.now(), this.ctx.redact);
+        this.collector.attach(page);
+        this.video = page.video();
+        page.setDefaultTimeout(this.ctx.timeouts.actionMs);
+        page.setDefaultNavigationTimeout(Math.max(this.ctx.timeouts.actionMs, NAVIGATION_TIMEOUT_MS));
+    }
+    run(action) {
+        return runWebAction(this.requirePage(), action, this.ctx.template, this.ctx.timeouts.actionMs);
+    }
+    /** Counts matches; after a snapshot also names the refs of the first 20 matches. */
+    find(target) {
+        return findOnPage(this.requirePage(), target, this.ctx.template, this.snapshotTaken);
+    }
+    async snapshot(options = {}) {
+        const snapshot = await webSnapshot(this.requirePage(), options);
+        this.snapshotTaken = true;
+        return snapshot;
+    }
+    screen() {
+        return webScreen(this.requirePage());
+    }
+    async tapAt(x, y) {
+        await this.requirePage().mouse.click(x, y);
+    }
+    async back() {
+        await this.requirePage().goBack({ timeout: this.ctx.timeouts.actionMs });
+    }
+    async home() {
+        const base = this.ctx.template.baseUrl;
+        if (!base)
+            throw new Unsupported('the environment has no base URL to go home to');
+        await this.requirePage().goto(base, { waitUntil: 'load', timeout: Math.max(this.ctx.timeouts.actionMs, NAVIGATION_TIMEOUT_MS) });
+    }
+    screenshot() {
+        return this.requirePage().screenshot({ type: 'png' });
+    }
+    source() {
+        return this.requirePage().content();
+    }
+    beginStep(index) {
+        this.collector?.begin(index);
+    }
+    debug(index) {
+        return this.collector?.for(index);
+    }
+    async stopRecording() {
+        // The video file is only complete once the context has closed.
+        await this.closeContext();
+        return this.video ? await this.video.path().catch(() => undefined) : undefined;
+    }
+    async dispose() {
+        await this.closeContext();
+    }
+    async closeContext() {
+        if (this.closed || !this.context)
+            return;
+        this.closed = true;
+        await this.context.close().catch(() => undefined);
+    }
+    requirePage() {
+        if (!this.page)
+            throw new Error('the page is not open');
+        return this.page;
+    }
+}
+export const webPlaywrightFactory = {
+    platform: 'web',
+    async availability(_host) {
+        const executable = chromiumExecutable();
+        if (!executable) {
+            return {
+                ok: false,
+                labels: [],
+                devices: [],
+                reasons: ['Chromium is not installed: run `leera-qa-runner setup browsers`'],
+            };
+        }
+        return {
+            ok: true,
+            labels: ['web-chromium'],
+            devices: [
+                {
+                    id: BROWSER_DEVICE_ID,
+                    platform: 'web',
+                    kind: 'host',
+                    name: 'Chromium',
+                    os_version: null,
+                    state: 'available',
+                    labels: ['web-chromium'],
+                    can_boot: false,
+                },
+            ],
+            reasons: [],
+        };
+    },
+    async create(ctx, shared) {
+        return new WebPlaywrightDriver(await shared.browsers.get(), ctx);
+    },
+};
+/**
+ * Counts a target's matches on a page; after a snapshot also names the refs of the first 20
+ * matches (web and Electron windows).
+ */
+export async function findOnPage(page, target, ctx, snapshotTaken) {
+    const locator = locate(page, target, ctx);
+    const count = await locator.count();
+    if (!snapshotTaken || count === 0)
+        return { count };
+    const refs = [];
+    for (let i = 0; i < Math.min(count, 20); i += 1) {
+        const yaml = await locator
+            .nth(i)
+            .ariaSnapshot({ mode: 'ai', depth: 1, timeout: 2_000 })
+            .catch(() => '');
+        const ref = refFromElementSnapshot(yaml);
+        if (ref)
+            refs.push(ref);
+    }
+    // An element's own snapshot replaces the page's ref table; elements keep their refs, so re-read it.
+    await page.ariaSnapshot({ mode: 'ai' }).catch(() => undefined);
+    return { count, refs };
+}
+/** Performs one web DSL action on a page (shared by the web and Electron drivers). */
+export async function runWebAction(page, action, ctx, defaultTimeout) {
+    const timeout = action.timeout_ms ?? defaultTimeout;
+    switch (action.type) {
+        case 'goto': {
+            const url = resolveUrl(render(action.url, ctx), ctx.baseUrl);
+            try {
+                await page.goto(url, { waitUntil: 'load', timeout: Math.max(timeout, NAVIGATION_TIMEOUT_MS) });
+            }
+            catch (error) {
+                if (errorMessage(error).includes('net::ERR_')) {
+                    throw new Blocked(`the environment could not be reached (${firstLine(error)})`);
+                }
+                throw error;
+            }
+            return {};
+        }
+        case 'click':
+            await (await find(page, action, ctx, timeout)).click({ timeout });
+            return {};
+        case 'hover':
+            await (await find(page, action, ctx, timeout)).hover({ timeout });
+            return {};
+        case 'check':
+            await (await find(page, action, ctx, timeout)).check({ timeout });
+            return {};
+        case 'uncheck':
+            await (await find(page, action, ctx, timeout)).uncheck({ timeout });
+            return {};
+        case 'fill':
+            await (await find(page, action, ctx, timeout)).fill(render(action.value, ctx), { timeout });
+            return {};
+        case 'select_option':
+            await (await find(page, action, ctx, timeout)).selectOption(render(action.value, ctx), { timeout });
+            return {};
+        case 'press': {
+            const key = action.key ?? '';
+            if (action.target)
+                await (await find(page, action, ctx, timeout)).press(key, { timeout });
+            else
+                await page.keyboard.press(key);
+            return {};
+        }
+        case 'wait_for':
+            await (await find(page, action, ctx, timeout)).waitFor({ state: 'visible', timeout });
+            return {};
+        case 'wait':
+            await sleep(Math.min(action.ms ?? 0, 30_000));
+            return {};
+        case 'expect_visible': {
+            const locator = await find(page, action, ctx, timeout);
+            await expectWithin(timeout, () => locator.isVisible(), 'to be visible');
+            return {};
+        }
+        case 'expect_hidden': {
+            const locator = locate(page, requireTarget(action), ctx);
+            await expectWithin(timeout, async () => !(await locator.isVisible()), 'to be hidden');
+            return {};
+        }
+        case 'expect_text': {
+            const locator = await find(page, action, ctx, timeout);
+            const expected = render(action.value, ctx);
+            let actual = '';
+            await expectWithin(timeout, async () => {
+                actual = (await locator.innerText({ timeout: 1_000 })).trim();
+                return matches(actual, expected, action.match);
+            }, () => `text to ${verb(action.match)} "${expected}", found "${clip(actual)}"`);
+            return {};
+        }
+        case 'expect_url': {
+            const expected = render(action.value, ctx);
+            await expectWithin(timeout, async () => matches(page.url(), expected, action.match), () => `the URL to ${verb(action.match)} "${expected}", found "${clip(page.url())}"`);
+            return {};
+        }
+        case 'expect_title': {
+            const expected = render(action.value, ctx);
+            let actual = '';
+            await expectWithin(timeout, async () => {
+                actual = await page.title();
+                return matches(actual, expected, action.match);
+            }, () => `the title to ${verb(action.match)} "${expected}", found "${clip(actual)}"`);
+            return {};
+        }
+        case 'screenshot':
+            return { screenshot: await page.screenshot({ type: 'png' }) };
+        default:
+            throw new Error(`unsupported action '${action.type}'`);
+    }
+}
+/** The primary target, or the first fallback that appears on the page before the timeout. */
+async function find(page, action, ctx, timeout) {
+    const target = requireTarget(action);
+    const primary = locate(page, target, ctx);
+    const candidates = [primary, ...(target.fallbacks ?? []).map((fallback) => locate(page, fallback, ctx))];
+    if (candidates.length === 1)
+        return primary;
+    const deadline = Date.now() + timeout;
+    for (;;) {
+        for (const candidate of candidates) {
+            if ((await candidate.count().catch(() => 0)) > 0)
+                return candidate;
+        }
+        if (Date.now() >= deadline)
+            return primary;
+        await sleep(POLL_MS);
+    }
+}
+function locate(page, target, ctx) {
+    const exact = target.exact;
+    let locator;
+    const ref = ariaRefSelector(target.locate);
+    if (ref) {
+        // A session ref: the element from the last snapshot itself.
+        return page.locator(ref);
+    }
+    if (target.role) {
+        locator = page.getByRole(target.role, {
+            ...(target.name ? { name: render(target.name, ctx) } : {}),
+            ...(exact === undefined ? {} : { exact }),
+        });
+    }
+    else if (target.label) {
+        locator = page.getByLabel(render(target.label, ctx), { exact });
+    }
+    else if (target.placeholder) {
+        locator = page.getByPlaceholder(render(target.placeholder, ctx), { exact });
+    }
+    else if (target.text) {
+        locator = page.getByText(render(target.text, ctx), { exact });
+    }
+    else if (target.test_id) {
+        locator = page.getByTestId(render(target.test_id, ctx));
+    }
+    else if (target.css) {
+        locator = page.locator(render(target.css, ctx));
+    }
+    else {
+        throw new Error('the target names no locator');
+    }
+    return target.nth === undefined ? locator : locator.nth(target.nth);
+}