sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/extension-host.js

@@ -0,0 +1,552 @@
+// The host of a run, or of the spec fixture's test: the real extension
+// runs the scripts, and this fills the host's reports, values and menus
+// (host.ts) from its events (extension-link.ts), and answers the run's
+// commands from it.
+//
+// - The run knows its scripts by their prepared ids; the extension by
+//   its own. `setPushed` maps one to the other.
+// - A tab is known by its `chrome.tabs` id once set up (`addTab`).
+//   Events from a tab the run is still setting up wait for it; others
+//   are not the run's.
+// - A tab's events come over the worker's connection, its navigations
+//   over the page's, and nothing orders the two. So an event from a
+//   top-frame document the attachment hasn't seen arrive yet waits for
+//   it: a report stamped before its document began would not count for
+//   it, and a menu command recorded then would be cleared by the
+//   navigation that follows. Only a top-frame event's document counts:
+//   an iframe's events carry the iframe's document, which no navigation
+//   of the tab's would ever match.
+// - The run reports only on its own tabs: events from others, and Log
+//   entries made in them, are left out.
+import { SM_ABANDONED_MSG, SM_ERROR_MSG, SM_MANUAL_MSG, SM_START_MSG, SM_SWAPPED_MSG } from '../runtime-messages.js';
+import { evalHookKey } from '../eval-hook.js';
+import { SKIP_REASON_SM_DEV } from '../sm-dev-protocol.js';
+import { remapStackText } from '../stack-link.js';
+import { decodeOwnRefs } from './page-output.js';
+import { HarnessHost, valueCodec, } from './host.js';
+import { frameNodes, matchFrameTrees } from './frames.js';
+// How long a tab's event waits for its document, or for the tab to be
+// set up, before it's handled anyway or dropped.
+const DOCUMENT_WAIT_MS = 3000;
+const SETUP_WAIT_MS = 10_000;
+export class ExtensionHost extends HarnessHost {
+    link;
+    printLog;
+    // The extension's script id by the run's, and back.
+    extensionIds = new Map();
+    runIds = new Map();
+    // Each pushed script's line layout, by the extension's id.
+    layouts = new Map();
+    tabs = new Map();
+    tabsByPage = new Map();
+    // Events from tabs the run is setting up, by tab id, with when they came.
+    early = new Map();
+    // The SourceMonkey-managed scripts the run has listed, by label (`E1`), and
+    // each one's label by its id, kept for the run.
+    others = new Map();
+    otherLabels = new Map();
+    // The newest Log entry's time seen for each pushed script, by the
+    // extension's id, so catching up after a restart prints only the rest.
+    logSeen = new Map();
+    // While catchUpLogs reads a Log back: the first entry heard live since.
+    liveFrom = new Map();
+    // The extension's notification id for each shown one, by request id,
+    // to click or close it.
+    notificationIds = new Map();
+    constructor(link, 
+    /**
+     * Logs a Log entry of one of the run's scripts (`scriptId`: the
+     * run's id), with the tab it was made in, if any.
+     */
+    printLog) {
+        super();
+        this.link = link;
+        this.printLog = printLog;
+        link.onEvent((event) => this.ingest(event));
+    }
+    /** The run's script `runId` is the extension's `extensionId`. */
+    setPushed(runId, extensionId) {
+        const before = this.extensionIds.get(runId);
+        if (before) {
+            this.runIds.delete(before);
+            this.layouts.delete(before);
+        }
+        this.extensionIds.set(runId, extensionId);
+        this.runIds.set(extensionId, runId);
+        // Entries from before the push (a replaced copy's) are no part of the run.
+        this.logSeen.set(extensionId, Math.max(this.logSeen.get(extensionId) ?? 0, Date.now()));
+    }
+    /**
+     * After the extension's worker restarted, logs the Log entries of the
+     * run's scripts made meanwhile, whose events were lost.
+     */
+    async catchUpLogs() {
+        for (const [extensionId, runId] of [...this.runIds]) {
+            // The gap is from the last entry seen to the first the new worker
+            // sends live while the Log is read, which is logged already.
+            const seen = this.logSeen.get(extensionId) ?? 0;
+            this.liveFrom.set(extensionId, Infinity);
+            const entries = await this.link.scriptLog(extensionId).catch(() => []);
+            const live = this.liveFrom.get(extensionId) ?? Infinity;
+            this.liveFrom.delete(extensionId);
+            for (const entry of entries)
+                if (entry.timestamp > seen && entry.timestamp < live)
+                    this.logEntry(extensionId, runId, entry);
+        }
+    }
+    // A Log entry of one of the run's scripts: logged when it was made in
+    // one of the run's tabs, or outside any (a `@require` that failed to
+    // load).
+    logEntry(extensionId, runId, entry) {
+        this.logSeen.set(extensionId, Math.max(this.logSeen.get(extensionId) ?? 0, entry.timestamp));
+        const tabId = entry.tabId;
+        if (tabId !== undefined && !this.tabs.has(tabId) && !this.early.has(tabId))
+            return;
+        const page = tabId === undefined ? undefined : this.tabs.get(tabId)?.page;
+        this.printLog({ scriptId: runId, name: this.nameOf(runId), level: entry.level, message: decodeOwnRefs(this.remapStack(entry.message)), page });
+    }
+    /** The extension's id for the run's script `runId`, once pushed. */
+    extensionIdOf(runId) {
+        return this.extensionIds.get(runId);
+    }
+    /** How the extension's script `extensionId` maps back to its files, if known. */
+    setLayout(extensionId, layout) {
+        if (layout)
+            this.layouts.set(extensionId, layout);
+        else
+            this.layouts.delete(extensionId);
+    }
+    // The extension runs the scripts under its own entry URLs, so their
+    // stack lines map by the layouts it reports (`setLayout`). Another
+    // manager maps its own.
+    remapStack(text) {
+        if (this.external)
+            return this.external.remap?.(text) ?? text;
+        return remapStackText(text, this.layouts.values());
+    }
+    /**
+     * The run's script whose code one of `urls` is (a stack frame's, or
+     * a stack's text), by the entry URLs the extension runs them under.
+     */
+    scriptOf(urls) {
+        for (const url of urls) {
+            for (const [extensionId, layout] of this.layouts) {
+                if (url.includes(layout.entryUrl))
+                    return this.runIds.get(extensionId);
+            }
+            const external = this.external?.idOf(url);
+            if (external !== undefined)
+                return this.runIds.get(external);
+        }
+        return undefined;
+    }
+    /**
+     * Under another manager (Violentmonkey, Tampermonkey), which reports
+     * nothing: how its code's URLs name scripts, by the manager's id
+     * (`setPushed`), what every URL it runs code under starts with, and
+     * how it maps stack lines it moved.
+     */
+    external;
+    get getsReports() {
+        return this.external === undefined;
+    }
+    /**
+     * `page` is the run's tab `tabId`. `loaded`: the tab already shows the
+     * document its first events are from (a tab adopted after it loaded),
+     * so they needn't wait for a navigation. `scriptsOff`: its claim runs
+     * no scripts (opened from a `--noscript` tab), to keep if restored.
+     */
+    addTab(page, tabId, loaded = false, scriptsOff = false) {
+        const state = {
+            page, seenStart: loaded ? -Infinity : page.documentStart(), queue: Promise.resolve(), frames: new Map(), documents: new Map(), unmatched: new Set(),
+        };
+        this.tabs.set(tabId, state);
+        this.tabsByPage.set(page, tabId);
+        this.link.holdTab(tabId, scriptsOff);
+        const early = this.early.get(tabId);
+        this.early.delete(tabId);
+        for (const event of early?.events ?? [])
+            this.enqueue(state, event);
+    }
+    /** A tab the run will set up: its events wait for `addTab`. */
+    expectTab(tabId) {
+        if (!this.tabs.has(tabId) && !this.early.has(tabId))
+            this.early.set(tabId, { at: Date.now(), events: [] });
+    }
+    tabIdOf(page) {
+        return this.tabsByPage.get(page);
+    }
+    async liveFrameDocuments(page) {
+        const tabId = this.tabsByPage.get(page);
+        const state = tabId === undefined ? undefined : this.tabs.get(tabId);
+        if (tabId === undefined || !state)
+            return null;
+        return this.matchFrames(tabId, state);
+    }
+    // Lists the tab's frames from the extension and matches them to the
+    // page's: the live iframe documents, each with its frame. When the
+    // listing fails (the worker restarting, say), the last answer stands:
+    // an empty one would show every frame's scripts as gone.
+    async matchFrames(tabId, state) {
+        const listed = await this.link.allFrames(tabId).catch(() => null);
+        if (!listed)
+            return state.documents;
+        const nodes = frameNodes(state.page.page, this.frameIds).map((n) => ({ key: n.frame, parent: n.parent === null ? null : n.frame.parentFrame(), url: n.url }));
+        const matched = new Map([...matchFrameTrees(listed, nodes, state.frames)].filter((e) => e[1] !== null));
+        // A frame left out this time only because its URL is between two
+        // (mid-navigation) keeps its match, so same-URL siblings don't swap.
+        const taken = new Set(matched.values());
+        for (const f of listed) {
+            const was = state.frames.get(f.frameId);
+            if (was && !matched.has(f.frameId) && !was.isDetached() && !taken.has(was))
+                matched.set(f.frameId, was);
+        }
+        state.frames = matched;
+        state.topDocument = listed.find((f) => f.frameId === 0)?.documentId;
+        const live = new Map();
+        for (const f of listed) {
+            const frame = matched.get(f.frameId);
+            if (frame)
+                live.set(f.documentId, frame);
+        }
+        state.documents = live;
+        return live;
+    }
+    // The frame number of the iframe document an event came from, for
+    // its line and menu label. A document new since the last match lists
+    // the frames again, and once more after a moment: Playwright can hear
+    // of a frame after the extension does. One that still matches none
+    // isn't looked for again.
+    async frameNumberOf(tabId, state, documentId) {
+        const known = state.documents.get(documentId);
+        if (known && !known.isDetached())
+            return this.frameIds.number(known);
+        if (state.unmatched.has(documentId) || documentId === state.topDocument)
+            return undefined;
+        for (const wait of [0, 200]) {
+            if (wait)
+                await new Promise((r) => setTimeout(r, wait));
+            const frame = (await this.matchFrames(tabId, state)).get(documentId);
+            if (frame)
+                return this.frameIds.number(frame);
+            // The top frame's, which names no frame.
+            if (documentId === state.topDocument)
+                return undefined;
+        }
+        state.unmatched.add(documentId);
+        return undefined;
+    }
+    detachPage(page) {
+        const tabId = this.tabsByPage.get(page);
+        if (tabId !== undefined) {
+            this.tabs.delete(tabId);
+            this.link.forgetTab(tabId);
+        }
+        this.tabsByPage.delete(page);
+        super.detachPage(page);
+    }
+    // The extension gives a test collection's scripts their run's hook,
+    // under the script's id there.
+    evalHook(scriptId) {
+        const id = this.extensionIds.get(scriptId);
+        return id ? { key: evalHookKey(this.link.runId), id } : null;
+    }
+    async valuesOf(scriptId) {
+        const id = this.extensionIds.get(scriptId);
+        return id ? this.extensionValues(id) : {};
+    }
+    // Into the extension, and the host's own copy, which `getValue` reads
+    // without a round trip (the fixture's `gm.get`). The tabs' own writes
+    // reach that copy as events.
+    async setValues(scriptId, values) {
+        const id = this.extensionIds.get(scriptId);
+        if (!id)
+            throw new Error('Internal error: The script was never pushed into the extension');
+        await this.writeExtensionValues(id, values);
+        await super.setValues(scriptId, values);
+    }
+    // A script's values by the extension's id, decoded.
+    async extensionValues(id) {
+        const { decodeValue } = valueCodec();
+        const wire = await this.link.values(id);
+        return Object.fromEntries(Object.entries(wire).map(([k, v]) => [k, decodeValue(v)]));
+    }
+    async writeExtensionValues(id, values) {
+        const { encodeValue } = valueCodec();
+        await this.link.writeValues(id, Object.entries(values).map(([key, v]) => (v === undefined ? { key, deleted: true } : { key, value: encodeValue(v) })));
+    }
+    // One object per script, brought up to date, so one picked earlier
+    // (`scripts E1`) shows what the latest listing found.
+    other(id, label, facts) {
+        const other = this.others.get(label) ?? {
+            label, name: '', collection: '', status: '',
+            values: () => this.extensionValues(id),
+            setValues: (values) => this.writeExtensionValues(id, values),
+        };
+        Object.assign(other, facts);
+        this.others.set(label, other);
+        return other;
+    }
+    /**
+     * The SourceMonkey-managed scripts, for the commands (`ConsoleContext.others`).
+     * `guarded`: `set` on one changes the person's real data.
+     */
+    otherScripts(guarded) {
+        return {
+            guarded,
+            byLabel: (label) => this.others.get(label),
+            onTab: async (tab) => {
+                const tabId = this.tabsByPage.get(tab.link);
+                if (tabId === undefined)
+                    return [];
+                const rows = await this.link.scriptsOnTab(tabId);
+                return rows.filter((row) => !this.runIds.has(row.id)).map((row) => {
+                    // SourceMonkey's own number for the script (`E12`), the same
+                    // in every run. An extension before protocol 1.1 numbers none,
+                    // and gets the run's own numbering, in the order first seen.
+                    let label = row.number !== undefined ? `E${row.number}` : this.otherLabels.get(row.id);
+                    if (!label)
+                        label = `E${this.otherLabels.size + 1}`;
+                    this.otherLabels.set(row.id, label);
+                    return this.other(row.id, label, { name: row.name, collection: row.collection, status: row.status });
+                });
+            },
+            installed: (id, label, name, collection) => this.other(id, label, { name, collection }),
+        };
+    }
+    async answerConnectPrompt(promptId, choice) {
+        return this.link.answerConnectPrompt(promptId, choice);
+    }
+    async clickNotification(requestId) {
+        const id = this.notificationIds.get(requestId);
+        return id ? this.link.clickNotification(id) : false;
+    }
+    async closeNotification(requestId) {
+        const id = this.notificationIds.get(requestId);
+        return id ? this.link.closeNotification(id) : false;
+    }
+    async runManualScript(page, scriptId) {
+        const tabId = this.tabsByPage.get(page);
+        const id = this.extensionIds.get(scriptId);
+        if (tabId === undefined || !id)
+            throw new Error('Internal error: sm-dev has no tab or script to run it in');
+        await this.link.runManualScript(tabId, id);
+    }
+    async fireMenuEntry(entry) {
+        const page = this.pageOf(entry);
+        const tabId = page && this.tabsByPage.get(page);
+        const id = this.extensionIds.get(entry.scriptId);
+        if (tabId === undefined || !id)
+            return false;
+        return this.link.fireMenu(tabId, id, entry.commandId, entry.documentId);
+    }
+    ingest(event) {
+        if (event.kind === 'log') {
+            const runId = this.runIds.get(event.scriptId);
+            if (!runId)
+                return;
+            const live = this.liveFrom.get(event.scriptId);
+            if (live !== undefined)
+                this.liveFrom.set(event.scriptId, Math.min(live, event.entry.timestamp));
+            // A report's own entry (started, threw, skipped) prints as the
+            // report, but counts as seen.
+            if (event.fromReport) {
+                this.logSeen.set(event.scriptId, Math.max(this.logSeen.get(event.scriptId) ?? 0, event.entry.timestamp));
+                return;
+            }
+            this.logEntry(event.scriptId, runId, event.entry);
+            return;
+        }
+        if (event.kind === 'tab-opened') {
+            this.recordOpenedTab(event);
+            return;
+        }
+        if (event.kind === 'tab-closed') {
+            const runId = this.runIds.get(event.scriptId);
+            const record = runId ? this.reports.tabs.find((t) => t.scriptId === runId && t.requestId === event.requestId) : undefined;
+            if (record)
+                record.closed = true;
+            return;
+        }
+        // A write with no tab is the run's own `set` (or another run's),
+        // which says so itself.
+        if (event.kind === 'values' && event.tabId === undefined)
+            return;
+        const tabId = event.tabId;
+        if (!this.runIds.has(event.scriptId))
+            return;
+        const state = this.tabs.get(tabId);
+        if (state) {
+            this.enqueue(state, event);
+            return;
+        }
+        const early = this.early.get(tabId);
+        if (!early)
+            return;
+        // A tab whose setup never finished doesn't hold events for good.
+        if (Date.now() - early.at > SETUP_WAIT_MS)
+            this.early.delete(tabId);
+        else
+            early.events.push(event);
+    }
+    enqueue(state, event) {
+        state.queue = state.queue.then(() => this.handleTabEvent(state, event)).catch(() => undefined);
+    }
+    async handleTabEvent(state, event) {
+        if ((event.kind === 'report' || event.kind === 'menu') && event.topFrame !== false && event.documentId && event.documentId !== state.documentId) {
+            // A new document: wait for the attachment to have entered one
+            // after the last, so what this records counts for it.
+            const deadline = Date.now() + DOCUMENT_WAIT_MS;
+            while (state.page.documentStart() <= state.seenStart && Date.now() < deadline) {
+                await new Promise((r) => setTimeout(r, 25));
+            }
+            state.documentId = event.documentId;
+            state.seenStart = state.page.documentStart();
+        }
+        const runId = this.runIds.get(event.scriptId);
+        if (!runId || !this.tabs.has(event.tabId))
+            return;
+        // What came from an iframe names its frame. A report or menu event
+        // says whether it did; the others name their document, which may
+        // be the top frame's. Looked up only for
+        // what's recorded, after the events that are dropped.
+        const documentId = 'documentId' in event ? event.documentId : undefined;
+        const inFrame = (event.kind === 'report' || event.kind === 'menu') ? event.topFrame === false
+            : documentId !== undefined && documentId !== state.documentId;
+        const frameNumber = async () => {
+            const n = inFrame && documentId ? await this.frameNumberOf(event.tabId, state, documentId) : undefined;
+            return n === undefined ? {} : { frameNumber: n };
+        };
+        if (event.kind === 'request' || event.kind === 'download' || event.kind === 'notification') {
+            // Its frame is looked up only for the event that makes its record.
+            await this.recordActivity(runId, state.page, event, frameNumber);
+            return;
+        }
+        if (event.kind === 'connect-prompt') {
+            this.recordConnectPrompt(runId, state.page, event);
+            return;
+        }
+        if (event.kind === 'values') {
+            this.recordValueWrites(state.page, runId, event.writes, await frameNumber());
+            return;
+        }
+        if (event.kind === 'menu') {
+            if (event.op === 'add')
+                this.registerMenu(state.page, runId, event.commandId, event.name ?? '', event.documentId || undefined, inFrame ? await frameNumber() : undefined);
+            else
+                this.unregisterMenu(state.page, runId, event.commandId, event.documentId || undefined);
+            return;
+        }
+        // A tab with its scripts turned off (`--noscript`) skips them on
+        // each load, as asked: nothing to say.
+        if (event.type === SM_ABANDONED_MSG && event.reason === SKIP_REASON_SM_DEV)
+            return;
+        const fields = {
+            scriptId: runId, name: event.name, url: event.url,
+            ...(inFrame ? { frame: true } : {}),
+            ...(event.documentId ? { documentId: event.documentId } : {}),
+            ...await frameNumber(),
+        };
+        if (event.type === SM_START_MSG || event.type === SM_SWAPPED_MSG) {
+            this.recordStart(state.page, fields);
+        }
+        else if (event.type === SM_ERROR_MSG) {
+            this.recordError(state.page, { ...fields, message: event.message ?? '', stack: event.stack ?? '' });
+        }
+        else if (event.type === SM_MANUAL_MSG) {
+            this.recordManual(state.page, fields);
+        }
+        else if (event.type === SM_ABANDONED_MSG) {
+            // With no decision, the why (`detail`, from protocol 1.4) rather
+            // than its token.
+            this.recordSkip(state.page, { ...fields, reason: event.detail?.replace(/\.+$/, '') || event.reason || 'skip' });
+        }
+    }
+    // A `GM_openInTab` of one of the run's scripts, from one of its tabs.
+    recordOpenedTab(event) {
+        const runId = event.scriptId === undefined ? undefined : this.runIds.get(event.scriptId);
+        const from = this.tabs.get(event.sourceTabId)?.page;
+        if (!runId || !from)
+            return;
+        const record = {
+            scriptId: runId, requestId: event.requestId ?? '', url: event.url, active: event.active === true, at: event.at, closed: false,
+        };
+        this.reports.tabs.push(record);
+        this.recordPages.set(record, from);
+        this.notify('tab', record);
+    }
+    // A connection prompt for one of the run's scripts: one record, which
+    // the answer fills in.
+    recordConnectPrompt(runId, page, event) {
+        let record = this.reports.connectPrompts.find((r) => r.promptId === event.promptId);
+        if (event.op === 'shown') {
+            if (record)
+                return;
+            record = {
+                scriptId: runId, name: this.nameOf(runId), promptId: event.promptId, host: event.host,
+                url: event.url ?? '', method: event.method ?? 'GET', at: event.at,
+            };
+            this.reports.connectPrompts.push(record);
+            this.recordPages.set(record, page);
+            this.notify('connect-prompt', record);
+            return;
+        }
+        if (!record || record.answer || record.closed)
+            return;
+        if (event.op === 'closed') {
+            record.closed = true;
+            return;
+        }
+        if (!event.answer)
+            return;
+        record.answer = event.answer;
+        this.notify('connect-prompt', record);
+    }
+    // A request, download or notification, recorded as the harness host
+    // records its own: one record each, filled in as it settles, and
+    // announced once it has (a notification as it shows).
+    async recordActivity(runId, page, event, frame) {
+        if (event.kind === 'request') {
+            let record = this.reports.requests.find((r) => r.id === event.id && r.scriptId === runId);
+            if (!record) {
+                record = { scriptId: runId, ...await frame(), id: event.id, url: event.url, method: event.method, at: event.at };
+                this.reports.requests.push(record);
+                this.recordPages.set(record, page);
+            }
+            if (!event.outcome)
+                return;
+            Object.assign(record, { outcome: event.outcome }, event.status !== undefined ? { status: event.status } : {}, event.error ? { error: event.error } : {});
+            this.notify('request', record);
+            return;
+        }
+        if (event.kind === 'download') {
+            let record = this.reports.downloads.find((r) => r.requestId === event.requestId && r.scriptId === runId);
+            if (!record) {
+                record = { scriptId: runId, ...await frame(), requestId: event.requestId, url: event.url, name: event.name, at: event.at };
+                this.reports.downloads.push(record);
+                this.recordPages.set(record, page);
+            }
+            if (!event.outcome)
+                return;
+            Object.assign(record, { outcome: event.outcome }, event.filename ? { filename: event.filename } : {}, event.error ? { error: event.error } : {});
+            this.notify('download', record);
+            return;
+        }
+        if (event.op === 'shown') {
+            const record = {
+                scriptId: runId, ...await frame(), requestId: event.requestId, text: event.text ?? '', title: event.title ?? '', at: event.at,
+            };
+            if (event.notificationId)
+                this.notificationIds.set(event.requestId, event.notificationId);
+            this.reports.notifications.push(record);
+            this.recordPages.set(record, page);
+            this.notify('notification', record);
+            return;
+        }
+        const record = this.reports.notifications.find((n) => n.requestId === event.requestId && n.scriptId === runId);
+        if (record)
+            record.event = event.op;
+        if (event.op === 'closed')
+            this.notificationIds.delete(event.requestId);
+    }
+}

package/lib/harness/extension-launch.d.ts

@@ -0,0 +1,67 @@
+import type { BrowserContext } from '@playwright/test';
+import { type ManagerName } from './managers.js';
+export declare const EXTENSION_DIR: string;
+export interface ExtensionLaunchOptions {
+    /** The debugging port, which must be free. Chrome picks one when not given. */
+    port?: number;
+    /** A visible window. Hidden otherwise. */
+    headed?: boolean;
+    /** Without sound (the default), or with it when false. */
+    muted?: boolean;
+    /** More Chrome flags. */
+    args?: string[];
+    /**
+     * Chrome's own download manager saves downloads here, rather than
+     * Playwright's, which hides their real names and paths from
+     * `chrome.downloads`.
+     */
+    downloadsDir?: string;
+    /**
+     * Another Playwright client drives the browser, over `endpoint`. The
+     * launch's own client then leaves the pages' dialogs to it; otherwise
+     * it would dismiss them first.
+     */
+    connectedElsewhere?: boolean;
+    /** The manager to load in place of SourceMonkey, already fetched. */
+    manager?: ManagerName;
+    /**
+     * Keep Chrome's back/forward cache, which Playwright turns off by
+     * default. Tests of pages restored from it ask for it.
+     */
+    backForwardCache?: boolean;
+}
+export interface LaunchedExtensionBrowser {
+    /** The launched browser's CDP endpoint, for a client to connect to. */
+    endpoint: string;
+    /** The launch's own Playwright context: the browser's default one. */
+    context: BrowserContext;
+    /** The temp profile, deleted by `close`. */
+    profile: string;
+    /** Closes the browser and deletes its profile. */
+    close(): Promise<void>;
+}
+/**
+ * Launches Chromium with SourceMonkey loaded, or `options.manager`.
+ * Throws an error saying why when it can't. It has one blank tab,
+ * opened after the warm-up (see `warmUp`), for a run's first tab.
+ */
+export declare function launchExtensionBrowser(options?: ExtensionLaunchOptions): Promise<LaunchedExtensionBrowser>;
+/**
+ * Installs a script and removes it again, before the run opens its tab.
+ *
+ * - In a fresh profile, a tab opened before the extension's first script
+ *   install can't message the extension, even after a reload: a script
+ *   that runs there reports that it couldn't read its stored GM values.
+ *   Only a tab in a new renderer process (another site) recovers.
+ * - The run pushes its scripts after its tab is open, so it needs a tab
+ *   opened after this. See TODO.md.
+ */
+export declare function warmUp(context: BrowserContext): Promise<void>;
+/**
+ * Readies a new profile for SourceMonkey (Preferences, first run done),
+ * for a browser started with `extensionArgs`. Also for a test's own
+ * browser, launched outside Playwright.
+ */
+export declare function prepareProfile(profile: string, downloadsDir?: string): Promise<void>;
+/** The Chrome flags that load the package's SourceMonkey (or the extension in `dir`), and only it. */
+export declare function extensionArgs(dir?: string): string[];