sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/page-output.d.ts

@@ -0,0 +1,67 @@
+import type { ConsoleMessage } from '@playwright/test';
+export interface ConsoleLine {
+    type: string;
+    text: string;
+    /** Where the line was logged from, `''` when unknown. */
+    url: string;
+    /**
+     * The URLs of the call's stack frames, innermost first, async parents
+     * included; empty when not known.
+     */
+    frames: string[];
+    /** Logged from SourceMonkey's own JavaScript world (`USER_SCRIPT`), where only its code runs. */
+    extensionWorld?: boolean;
+    /**
+     * How many values were passed. Zero for the browser's own entries
+     * (a blocked request, a policy violation), which are not console
+     * calls at all.
+     */
+    argCount: number;
+}
+/**
+ * A line the prelude logs, which repeats a report the host already
+ * printed, so it's only `page`.
+ */
+export declare function isPreludeLine(text: string): boolean;
+/**
+ * Whose a console line is: the scripts', when it was logged from
+ * SourceMonkey's world or any frame of its stack is SourceMonkey's
+ * code (a script calling a page helper that logs), else the page's.
+ * The browser's own entries are always the page's. `ours`: what the
+ * manager's code URLs start with, when it isn't SourceMonkey.
+ */
+export declare function consoleSource(line: ConsoleLine, ours?: string): 'script' | 'page';
+/** `stack` is Playwright's for the error: the message, then its frames. */
+/** An error a script body threw, which the host printed already. */
+export declare function hostReportedError(stack: string, hostReports: boolean): boolean;
+/**
+ * Whose an uncaught error is (`stack`: the message, then its frames),
+ * or null for a script body's throw the host printed already.
+ */
+export declare function pageErrorSource(stack: string, hostReports: boolean, ours?: string): 'script' | 'page' | null;
+/**
+ * A console call's text, as `msg.text()` gives it but with each DOM
+ * node described (see NODE_TEXT_CHARS) and `%` directives applied
+ * (`formatConsoleArgs`). Every level goes through this,
+ * so `debug` and `error` lines read alike. A node that can't be read
+ * now keeps Playwright's text: its page gone, or not answering within
+ * NODE_LOOKUP_MS (a dialog open, paused in the debugger), since the
+ * page's later lines wait for this one.
+ */
+export declare function consoleText(msg: ConsoleMessage): Promise<string>;
+/**
+ * A console call's values as one line, the first one's `%` directives
+ * applied as the browser's console does: `%s`, `%d`, `%i`, `%f`, `%o`
+ * and `%O` take the next value in its place, `%c` takes the next value
+ * (its CSS) and shows nothing, and `%%` is a `%`. The values left over
+ * follow, space-separated. A string the page logged with `%` and no
+ * values to take reads as written.
+ */
+export declare function formatConsoleArgs(parts: string[]): string;
+/**
+ * `text` with each stack ref to SourceMonkey's own `sourcemonkey://`
+ * URLs decoded once, as the viewer's Log tab shows them: a file named
+ * `Video%20Speed%20Buttons.user.js` is in the URL as
+ * `Video%2520Speed%2520Buttons.user.js`. Other refs stay as they are.
+ */
+export declare function decodeOwnRefs(text: string): string;

package/lib/harness/page-output.js

@@ -0,0 +1,139 @@
+// Whose the page's console lines and uncaught errors are: the run's
+// scripts' (the `script` log source) or the page's own (`page`). A
+// busy site logs plenty of its own (blocked trackers, failed ads) that
+// would bury the scripts' lines, so the stream shows only `script`
+// unless asked. See docs/sm-dev-logs.md.
+// Also how a console line reads when it logs a DOM node.
+import { ROOT } from '../script-source-url.js';
+import { displayRefText, parseStackRefs } from '../stack-link.js';
+// Every URL SourceMonkey runs code under: the scripts, and its own
+// prelude, bridge and GM runtime, whose failures are ours to show too.
+const OURS = `${ROOT}/`;
+// A script's main body, `<ROOT>/<folder>/<name>.user.js`, as a stack
+// frame (`:line:col` follows). The extension concatenates `@require`s
+// into it, so their frames carry this URL too.
+const SCRIPT_BODY_FRAME = new RegExp(`${ROOT.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')}/[^/\\s]+/[^/\\s]+\\.user\\.js:`);
+/**
+ * A line the prelude logs, which repeats a report the host already
+ * printed, so it's only `page`.
+ */
+export function isPreludeLine(text) {
+    return text.startsWith('[SourceMonkey]');
+}
+/**
+ * Whose a console line is: the scripts', when it was logged from
+ * SourceMonkey's world or any frame of its stack is SourceMonkey's
+ * code (a script calling a page helper that logs), else the page's.
+ * The browser's own entries are always the page's. `ours`: what the
+ * manager's code URLs start with, when it isn't SourceMonkey.
+ */
+export function consoleSource(line, ours = OURS) {
+    if (line.argCount === 0)
+        return 'page';
+    if (line.extensionWorld)
+        return 'script';
+    return [line.url, ...line.frames].some((url) => url.startsWith(ours)) ? 'script' : 'page';
+}
+/** `stack` is Playwright's for the error: the message, then its frames. */
+/** An error a script body threw, which the host printed already. */
+export function hostReportedError(stack, hostReports) {
+    return hostReports && SCRIPT_BODY_FRAME.test(stack);
+}
+/**
+ * Whose an uncaught error is (`stack`: the message, then its frames),
+ * or null for a script body's throw the host printed already.
+ */
+export function pageErrorSource(stack, hostReports, ours = OURS) {
+    if (hostReportedError(stack, hostReports))
+        return null;
+    // A thrown or rejected non-Error value (`Promise.reject('nope')`)
+    // has no frames, so there's no telling from its stack. The run looks
+    // at where it was thrown (`stacklessIsScripts` in run.ts).
+    if (!/\n\s+at /.test(stack))
+        return 'script';
+    return stack.includes(ours) ? 'script' : 'page';
+}
+// How a node logged to the console reads: its opening tag, as in
+// `<div id="x" class="a b">`, rather than Playwright's `JSHandle@node`.
+// Cut at this length, attribute values first.
+const NODE_TEXT_CHARS = 120;
+const NODE_LOOKUP_MS = 1000;
+/**
+ * A console call's text, as `msg.text()` gives it but with each DOM
+ * node described (see NODE_TEXT_CHARS) and `%` directives applied
+ * (`formatConsoleArgs`). Every level goes through this,
+ * so `debug` and `error` lines read alike. A node that can't be read
+ * now keeps Playwright's text: its page gone, or not answering within
+ * NODE_LOOKUP_MS (a dialog open, paused in the debugger), since the
+ * page's later lines wait for this one.
+ */
+export async function consoleText(msg) {
+    const parts = await Promise.all(msg.args().map(async (arg) => {
+        const node = arg.asElement();
+        if (!node)
+            return arg.toString();
+        let timer;
+        const late = new Promise((resolve) => { timer = setTimeout(() => resolve(arg.toString()), NODE_LOOKUP_MS); });
+        try {
+            return await Promise.race([node.evaluate(describeNode, NODE_TEXT_CHARS), late]);
+        }
+        catch {
+            return arg.toString();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }));
+    return formatConsoleArgs(parts);
+}
+/**
+ * A console call's values as one line, the first one's `%` directives
+ * applied as the browser's console does: `%s`, `%d`, `%i`, `%f`, `%o`
+ * and `%O` take the next value in its place, `%c` takes the next value
+ * (its CSS) and shows nothing, and `%%` is a `%`. The values left over
+ * follow, space-separated. A string the page logged with `%` and no
+ * values to take reads as written.
+ */
+export function formatConsoleArgs(parts) {
+    if (parts.length < 2 || !parts[0].includes('%'))
+        return parts.join(' ');
+    let next = 1;
+    const first = parts[0].replace(/%([sdifoOc%])/g, (whole, kind) => {
+        if (kind === '%')
+            return '%';
+        if (next >= parts.length)
+            return whole;
+        const value = parts[next++];
+        if (kind === 'c')
+            return '';
+        if (kind === 'd' || kind === 'i')
+            return String(parseInt(value, 10));
+        if (kind === 'f')
+            return String(parseFloat(value));
+        return value;
+    });
+    return [first, ...parts.slice(next)].join(' ');
+}
+// Runs in the page.
+function describeNode(node, limit) {
+    const cut = (s, n) => (s.length > n ? `${s.slice(0, n)}...` : s);
+    if (node.nodeType === Node.TEXT_NODE)
+        return `#text ${JSON.stringify(cut(node.textContent ?? '', 40))}`;
+    if (!(node instanceof Element))
+        return node.nodeName;
+    const attrs = Array.from(node.attributes, (a) => (a.value === '' ? a.name : `${a.name}="${cut(a.value, 40)}"`));
+    const tag = node.tagName.toLowerCase();
+    const open = `<${[tag, ...attrs].join(' ')}>`;
+    return open.length > limit ? `${open.slice(0, limit - 4)}...>` : open;
+}
+/**
+ * `text` with each stack ref to SourceMonkey's own `sourcemonkey://`
+ * URLs decoded once, as the viewer's Log tab shows them: a file named
+ * `Video%20Speed%20Buttons.user.js` is in the URL as
+ * `Video%2520Speed%2520Buttons.user.js`. Other refs stay as they are.
+ */
+export function decodeOwnRefs(text) {
+    if (!text.includes(`${ROOT}/`))
+        return text;
+    return parseStackRefs(text).map((run) => (run.kind === 'ref' ? displayRefText(run.text, run.url) : run.text)).join('');
+}

package/lib/harness/page-watch.d.ts

@@ -0,0 +1,171 @@
+import type { Frame, Page } from '@playwright/test';
+import type { HarnessHost, PageLink } from './host.js';
+import type { PreparedScript } from './prepare.js';
+import type { InjectionWorld } from '../script-world.js';
+/** What `activity` reads from a page, for `wait`. */
+export interface PageActivity {
+    readyState: string;
+    /** Milliseconds since the DOM last changed. */
+    sinceDom: number;
+    /** The element that changed last, as `div#id.class`. */
+    lastChanged: string;
+}
+/** A request the page has in flight, and for how long. */
+export interface PendingRequest {
+    url: string;
+    ms: number;
+}
+/** What an expression `evaluate` ran threw, as opposed to evaluate failing. */
+export declare class ScriptThrew extends Error {
+}
+/**
+ * A script's own scope, for `eval` in a script: the world it runs in, and
+ * where its eval hook is kept there (see src/eval-hook.ts).
+ */
+export interface ScriptScope {
+    world: InjectionWorld;
+    key: string;
+    id: string;
+}
+/** `evaluate` found no eval hook for the script: it hasn't run in this document. */
+export declare class NoEvalHook extends Error {
+}
+/** `evaluate` found no document to run in: the page stayed between documents. */
+export declare class NoDocument extends Error {
+}
+export interface AttachOptions {
+    /**
+     * The extension's origin (`chrome-extension://<id>`), which names the
+     * world its scripts run in, for `eval` in a script.
+     */
+    watchOnly: {
+        extensionOrigin: string;
+    };
+}
+export interface InjectOptions {
+    /**
+     * The script runs in the current document too, not only from the
+     * next navigation: one the tab already showed when it was set up.
+     */
+    immediately?: boolean;
+}
+/**
+ * One page watched for a host. Create with `attachPage`, then record the
+ * scripts its tab runs with `inject`.
+ */
+export declare class PageAttachment implements PageLink {
+    readonly page: Page;
+    readonly host: HarnessHost;
+    private readonly cdp;
+    private readonly options;
+    private readonly injected;
+    private disposing;
+    private closed;
+    private mainFrameId;
+    private readonly documents;
+    private currentDocument;
+    private readonly contexts;
+    private frameSessions?;
+    private readonly requests;
+    private lastRequestEnd;
+    private readonly onRequest;
+    private readonly onRequestEnd;
+    private readonly onClose;
+    private constructor();
+    static create(page: Page, host: HarnessHost, options: AttachOptions): Promise<PageAttachment>;
+    private install;
+    /**
+     * When the main frame entered its current document, by the host's
+     * clock, as reports are stamped. Changes only when a new document
+     * loads, not on a same-document (hash or `pushState`) navigation.
+     */
+    documentStart(): number;
+    /**
+     * Resolves once the page has run the tasks it already had queued, and
+     * the console lines they printed have arrived. A round trip through
+     * Playwright's own session, as those lines are, so none comes after
+     * it. Then one through the attachment's session, so the events it
+     * was sent meanwhile have arrived too. For a
+     * command to end after what it set off in the page, such as a menu
+     * handler, or a script body, which runs after its start report.
+     */
+    drain(): Promise<void>;
+    /**
+     * Resolves once the events the attachment's session had already been
+     * sent have arrived: a navigation's new document. Playwright's own
+     * session can run ahead of it.
+     */
+    caughtUp(): Promise<void>;
+    private enterDocument;
+    /**
+     * The page's document state and its DOM's last change, for `wait`.
+     * Null when there is no document to ask. Can wait on a page busy in
+     * a long script, so the caller bounds it.
+     */
+    activity(): Promise<PageActivity | null>;
+    /**
+     * Resolves once the page's main thread has a moment with nothing to
+     * do (`requestIdleCallback`), or after `maxMs`.
+     */
+    idle(maxMs: number): Promise<void>;
+    /** The page's requests in flight, and milliseconds since one last ended. */
+    network(): {
+        pending: PendingRequest[];
+        sinceLast: number;
+    };
+    url(): string;
+    private scriptsContext;
+    private contextFor;
+    /**
+     * Evaluates `expression` in the main frame, or in `frame` (one of the
+     * page's iframes), in the page's own world or one script's own
+     * scope, for `eval`. Resolves to the result as a
+     * line to print; rejects with a `ScriptThrew` for what the expression
+     * threw, a `NoEvalHook` for a script that hasn't run here, a
+     * `NoDocument` for a frame that has gone, or an error of the
+     * evaluation's own (the page gone, say).
+     */
+    evaluate(expression: string, world: 'page' | ScriptScope, documentWaitMs?: number, frame?: Frame): Promise<string>;
+    private topContexts;
+    /**
+     * The CDP target id of an iframe in a process of its own, for a raw
+     * CDP client; undefined for one in its parent's (see frame-sessions.ts).
+     */
+    frameTargetId(frame: Frame): Promise<string | undefined>;
+    /** An iframe's CDP frame id in the session that covers it, if found. */
+    frameCdpId(frame: Frame): Promise<string | undefined>;
+    private frameContexts;
+    private documentReady;
+    private evaluateInScript;
+    private evaluated;
+    private describe;
+    /**
+     * Records a script the tab runs. Re-recording the same script
+     * replaces it.
+     */
+    inject(prepared: PreparedScript, options?: InjectOptions): Promise<void>;
+    /** The tab no longer runs a script, from its next navigation. */
+    remove(scriptId: string): Promise<void>;
+    injectedScripts(): PreparedScript[];
+    /**
+     * The scripts the current document runs, and so hears from: recorded
+     * before it started, or run in it at once. One added later (a `load`
+     * into a tab a dialog kept from reloading) waits for the next load.
+     */
+    scriptsInDocument(): PreparedScript[];
+    /**
+     * When the main frame first entered its current document. Unlike
+     * `documentStart`, the same after the back/forward cache restores it,
+     * when its scripts don't run again.
+     */
+    documentFirstStart(): number;
+    /** Stop watching, and drop the CDP session. */
+    dispose(): Promise<void>;
+}
+/**
+ * The page's CDP target id (the `id` in `/json/list`, and what CDP's
+ * `Target.*` calls take), or null when it can't be read, as once the
+ * page has closed.
+ */
+export declare function targetIdOf(page: Page): Promise<string | null>;
+export declare function attachPage(page: Page, host: HarnessHost, options: AttachOptions): Promise<PageAttachment>;