@itmetsam/samurai-framework 0.10.0 → 0.12.0

package/dist/script/call-function.js

@@ -1,4 +1,3 @@
-import { BiDiError } from "../transport/bidi-error.js";
 import { fromRemoteValue, toLocalValue } from "./serialize.js";
 /** How much of a function's source `ScriptError` keeps */
 const SOURCE_PREVIEW = 200;
@@ -37,10 +36,8 @@ export function toFunctionDeclaration(fn) {
 /** Calls `fn` in the page with serialized arguments and returns its deserialized result */
 export async function callFunction(connector, context, fn, args = [], options = {}) {
     const functionDeclaration = toFunctionDeclaration(fn);
-    const ownership = options.ownership ?? "none";
     // Serialize first: a bad argument must fail before anything is sent
     const serialized = args.map(toLocalValue);
-    const thisValue = "thisArg" in options ? toLocalValue(options.thisArg) : undefined;
     const result = await connector.send("script.callFunction", {
         functionDeclaration,
         awaitPromise: options.awaitPromise ?? true,
@@ -48,24 +45,10 @@ export async function callFunction(connector, context, fn, args = [], options =
             ? { context }
             : { context, sandbox: options.sandbox },
         ...(serialized.length > 0 && { arguments: serialized }),
-        resultOwnership: ownership,
-        ...(thisValue !== undefined && { this: thisValue }),
+        resultOwnership: "none",
     });
     if (result.type === "exception") {
         throw new ScriptError(result.exceptionDetails.text, functionDeclaration, result.exceptionDetails.stackTrace);
     }
-    return fromRemoteValue(result.result, { keepHandles: ownership === "root" });
-}
-/** Releases handles obtained with `ownership: "root"`; a handle that is already gone is fine */
-export async function disown(connector, context, handles) {
-    if (handles.length === 0)
-        return;
-    try {
-        await connector.send("script.disown", { handles, target: { context } });
-    }
-    catch (err) {
-        if (err instanceof BiDiError && err.code === "no such handle")
-            return;
-        throw err;
-    }
+    return fromRemoteValue(result.result);
 }

package/dist/script/element-handle.d.ts

@@ -5,6 +5,5 @@
  */
 export declare class ElementHandle {
     readonly sharedId: string;
-    readonly handle?: string | undefined;
-    constructor(sharedId: string, handle?: string | undefined);
+    constructor(sharedId: string);
 }

package/dist/script/element-handle.js

@@ -4,8 +4,7 @@
  * Internal: user code keeps using `Locator`.
  */
 export class ElementHandle {
-    constructor(sharedId, handle) {
+    constructor(sharedId) {
         this.sharedId = sharedId;
-        this.handle = handle;
     }
 }

package/dist/script/serialize.d.ts

@@ -1,15 +1,10 @@
 import type { ArgumentValue, RemoteValue } from "../types/bidi-modules/script.js";
 /** A value passed to a page function */
 export type Arg = unknown;
-/** A remote value that cannot be copied to plain JS (function, window, promise, …), kept by type and handle */
+/** A remote value that cannot be copied to plain JS (function, window, promise, …), kept by its type */
 export declare class RemoteObject {
     readonly type: string;
-    readonly handle?: string | undefined;
-    /** The deserialized value, when the browser sent one and handles were kept */
-    readonly value?: unknown | undefined;
-    constructor(type: string, handle?: string | undefined, 
-    /** The deserialized value, when the browser sent one and handles were kept */
-    value?: unknown | undefined);
+    constructor(type: string);
 }
 /**
  * A channel the page function can call as `send(value)`; the browser delivers each value as a
@@ -21,9 +16,5 @@ export declare class ChannelArg {
 }
 /** Serializes `value` for `script.callFunction` arguments; throws TypeError for what cannot cross the wire */
 export declare function toLocalValue(value: Arg): ArgumentValue;
-export interface DeserializeOptions {
-    /** Return objects that carry a handle as `RemoteObject`s (with `.value`), so the caller can disown them later */
-    keepHandles?: boolean;
-}
 /** Converts a remote value to plain JS; what cannot be copied becomes a `RemoteObject` */
-export declare function fromRemoteValue(value: RemoteValue, options?: DeserializeOptions): unknown;
+export declare function fromRemoteValue(value: RemoteValue): unknown;

package/dist/script/serialize.js

@@ -1,14 +1,10 @@
 import { ElementHandle } from "./element-handle.js";
 /** Deepest nesting `toLocalValue` accepts; a second guard next to cycle detection */
 const MAX_DEPTH = 100;
-/** A remote value that cannot be copied to plain JS (function, window, promise, …), kept by type and handle */
+/** A remote value that cannot be copied to plain JS (function, window, promise, …), kept by its type */
 export class RemoteObject {
-    constructor(type, handle, 
-    /** The deserialized value, when the browser sent one and handles were kept */
-    value) {
+    constructor(type) {
         this.type = type;
-        this.handle = handle;
-        this.value = value;
     }
 }
 /**
@@ -55,11 +51,8 @@ function serialize(value, ancestors, depth) {
             },
         };
     }
-    if (value instanceof ElementHandle) {
-        return value.handle === undefined
-            ? { sharedId: value.sharedId }
-            : { sharedId: value.sharedId, handle: value.handle };
-    }
+    if (value instanceof ElementHandle)
+        return { sharedId: value.sharedId };
     if (value instanceof Date)
         return { type: "date", value: value.toISOString() };
     if (value instanceof RegExp) {
@@ -112,10 +105,10 @@ function numberValue(value) {
     return value;
 }
 /** Converts a remote value to plain JS; what cannot be copied becomes a `RemoteObject` */
-export function fromRemoteValue(value, options = {}) {
-    return deserialize(value, new Map(), options);
+export function fromRemoteValue(value) {
+    return deserialize(value, new Map());
 }
-function deserialize(value, known, options) {
+function deserialize(value, known) {
     const loose = value;
     switch (value.type) {
         case "undefined":
@@ -136,60 +129,58 @@ function deserialize(value, known, options) {
             return new RegExp(pattern, flags);
         }
         case "node":
-            return new ElementHandle(loose.sharedId ?? "", loose.handle);
-    }
-    const nested = (item) => deserialize(item, known, options);
-    const remember = (result) => {
-        if (loose.internalId !== undefined)
-            known.set(loose.internalId, result);
-        return result;
-    };
-    const backReference = () => loose.internalId !== undefined && known.has(loose.internalId)
-        ? { found: true, value: known.get(loose.internalId) }
-        : undefined;
-    let result;
-    switch (value.type) {
+            return new ElementHandle(loose.sharedId ?? "");
         case "array":
         case "set":
         case "object":
+        case "map":
+            // A collection cut off by the serialization depth has no copy to make
+            return (deserializeCollection(value, known) ?? new RemoteObject(value.type));
+    }
+    return new RemoteObject(value.type);
+}
+/**
+ * An array, set, map or object. A back reference (a value seen before, by `internalId`) gives the copy made
+ * earlier; `undefined` means the browser cut the collection off.
+ */
+function deserializeCollection(value, known) {
+    const { value: items, internalId } = value;
+    if (items === undefined)
+        return internalId !== undefined && known.has(internalId)
+            ? known.get(internalId)
+            : undefined;
+    // Registered before the items are read, so an item that points back at its container finds it
+    const remember = (copy) => {
+        if (internalId !== undefined)
+            known.set(internalId, copy);
+        return copy;
+    };
+    const nested = (item) => deserialize(item, known);
+    const key = (raw) => typeof raw === "string" ? raw : nested(raw);
+    switch (value.type) {
+        case "array": {
+            const list = remember([]);
+            items.forEach((item) => list.push(nested(item)));
+            return list;
+        }
+        case "set": {
+            const set = remember(new Set());
+            items.forEach((item) => set.add(nested(item)));
+            return set;
+        }
         case "map": {
-            const reference = backReference();
-            if (reference && loose.value === undefined)
-                return reference.value;
-            if (loose.value === undefined)
-                break; // cut off by the serialization depth
-            if (value.type === "array") {
-                const list = remember([]);
-                loose.value.forEach((item) => list.push(nested(item)));
-                result = list;
-            }
-            else if (value.type === "set") {
-                const set = remember(new Set());
-                loose.value.forEach((item) => set.add(nested(item)));
-                result = set;
-            }
-            else {
-                const entries = loose.value;
-                const key = (raw) => typeof raw === "string" ? raw : nested(raw);
-                if (value.type === "map") {
-                    const map = remember(new Map());
-                    entries.forEach(([k, item]) => map.set(key(k), nested(item)));
-                    result = map;
-                }
-                else {
-                    const object = remember({});
-                    entries.forEach(([k, item]) => {
-                        object[String(key(k))] = nested(item);
-                    });
-                    result = object;
-                }
-            }
-            return options.keepHandles && loose.handle !== undefined
-                ? new RemoteObject(value.type, loose.handle, result)
-                : result;
+            const map = remember(new Map());
+            items.forEach(([k, item]) => map.set(key(k), nested(item)));
+            return map;
+        }
+        default: {
+            const object = remember({});
+            items.forEach(([k, item]) => {
+                object[String(key(k))] = nested(item);
+            });
+            return object;
         }
     }
-    return new RemoteObject(value.type, loose.handle);
 }
 function specialNumber(value) {
     switch (value) {

package/dist/steps/parse/call.d.ts

@@ -0,0 +1,3 @@
+import ts from "typescript";
+import type { LocatorSpec } from "../model.js";
+export declare function readLocator(node: ts.Expression): LocatorSpec | undefined;

package/dist/steps/parse/call.js

@@ -0,0 +1,81 @@
+import ts from "typescript";
+import { readObject, stringOf } from "./literals.js";
+function readCall(method, args) {
+    const first = stringOf(args[0]);
+    if (first === undefined)
+        return undefined;
+    switch (method) {
+        case "locator":
+            return args.length === 1 ? { method, xpath: first } : undefined;
+        case "getByCss":
+            return args.length === 1 ? { method, css: first } : undefined;
+        case "getByTestId":
+            return args.length === 1 ? { method, testId: first } : undefined;
+        case "getByText":
+        case "getByLabel": {
+            if (args.length > 2)
+                return undefined;
+            const options = args.length === 2 ? readObject(args[1], ["match", "ignoreCase"]) : {};
+            if (!options)
+                return undefined;
+            const { match, ignoreCase } = options;
+            if ((match !== undefined && match !== "full" && match !== "partial") ||
+                (ignoreCase !== undefined && typeof ignoreCase !== "boolean")) {
+                return undefined;
+            }
+            return {
+                method,
+                text: first,
+                ...(match !== undefined && { match: match }),
+                ...(ignoreCase !== undefined && { ignoreCase: ignoreCase }),
+            };
+        }
+        case "getByRole": {
+            if (args.length > 2)
+                return undefined;
+            const options = args.length === 2 ? readObject(args[1], ["name"]) : {};
+            if (!options ||
+                (options.name !== undefined && typeof options.name !== "string"))
+                return undefined;
+            return {
+                method,
+                role: first,
+                ...(options.name !== undefined && { name: options.name }),
+            };
+        }
+        default:
+            return undefined;
+    }
+}
+/** `page.a(…).b(…)` as calls in order; undefined when it is anything else */
+function readChain(node) {
+    const calls = [];
+    let current = node;
+    while (ts.isCallExpression(current)) {
+        if (!ts.isPropertyAccessExpression(current.expression))
+            return undefined;
+        const call = readCall(current.expression.name.text, current.arguments);
+        if (!call)
+            return undefined;
+        calls.unshift(call);
+        current = current.expression.expression;
+    }
+    return ts.isIdentifier(current) && current.text === "page" && calls.length > 0
+        ? calls
+        : undefined;
+}
+export function readLocator(node) {
+    if (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.name.text === "withFallbacks") {
+        const chain = readChain(node.expression.expression);
+        const fallbacks = node.arguments.map(readChain);
+        if (!chain ||
+            node.arguments.length === 0 ||
+            fallbacks.some((fallback) => !fallback))
+            return undefined;
+        return { chain, fallbacks: fallbacks };
+    }
+    const chain = readChain(node);
+    return chain && { chain, fallbacks: [] };
+}

package/dist/steps/parse/expectation.d.ts

@@ -0,0 +1,5 @@
+import ts from "typescript";
+import type { Expectation, TextValue } from "../model.js";
+/** `env.NAME`, `env["NAME"]`, `secrets.NAME`, `secrets["NAME"]` or a string literal */
+export declare function readValue(node: ts.Expression | undefined): TextValue | undefined;
+export declare function readExpectation(matcher: string, args: readonly ts.Expression[]): Expectation | undefined;

package/dist/steps/parse/expectation.js

@@ -0,0 +1,71 @@
+import ts from "typescript";
+import { stringOf } from "./literals.js";
+const TEXT_MATCHERS = ["toHaveText", "toContainText", "toHaveValue"];
+/** `env.NAME`, `env["NAME"]`, `secrets.NAME`, `secrets["NAME"]` or a string literal */
+export function readValue(node) {
+    if (!node)
+        return undefined;
+    const literal = stringOf(node);
+    if (literal !== undefined)
+        return { kind: "literal", value: literal };
+    let object;
+    let name;
+    if (ts.isPropertyAccessExpression(node)) {
+        object = node.expression;
+        name = node.name.text;
+    }
+    else if (ts.isElementAccessExpression(node)) {
+        object = node.expression;
+        name = stringOf(node.argumentExpression);
+    }
+    else
+        return undefined;
+    if (name === undefined || !ts.isIdentifier(object))
+        return undefined;
+    if (object.text === "env")
+        return { kind: "env", name };
+    if (object.text === "secrets")
+        return { kind: "secret", name };
+    return undefined;
+}
+function readTextMatcher(node) {
+    if (!node)
+        return undefined;
+    const literal = stringOf(node);
+    if (literal !== undefined)
+        return literal;
+    if (ts.isRegularExpressionLiteral(node)) {
+        const end = node.text.lastIndexOf("/");
+        return {
+            regex: {
+                source: node.text.slice(1, end),
+                flags: node.text.slice(end + 1),
+            },
+        };
+    }
+    return undefined;
+}
+export function readExpectation(matcher, args) {
+    if (matcher === "toBeVisible")
+        return args.length === 0 ? { matcher } : undefined;
+    if (matcher === "toHaveCount") {
+        const [count] = args;
+        return args.length === 1 && count && ts.isNumericLiteral(count)
+            ? { matcher, expected: Number(count.text) }
+            : undefined;
+    }
+    if (matcher === "toHaveAttribute") {
+        const name = stringOf(args[0]);
+        const expected = readTextMatcher(args[1]);
+        return args.length === 2 && name !== undefined && expected !== undefined
+            ? { matcher, name, expected }
+            : undefined;
+    }
+    if (TEXT_MATCHERS.includes(matcher)) {
+        const expected = readTextMatcher(args[0]);
+        return args.length === 1 && expected !== undefined
+            ? { matcher: matcher, expected }
+            : undefined;
+    }
+    return undefined;
+}

package/dist/steps/parse/file-entry.d.ts

@@ -0,0 +1,4 @@
+import ts from "typescript";
+import type { FileEntry } from "../model.js";
+/** One file entry, or an array of them */
+export declare function readFiles(node: ts.Expression | undefined): FileEntry[] | undefined;

package/dist/steps/parse/file-entry.js

@@ -0,0 +1,74 @@
+import ts from "typescript";
+import { parseSize } from "../files.js";
+import { stringOf } from "./literals.js";
+/** `"path"` or `generatedFile({ name, size, type? })`; undefined for anything else */
+function readFileEntry(node) {
+    const path = stringOf(node);
+    if (path !== undefined)
+        return { path };
+    if (!ts.isCallExpression(node) ||
+        !ts.isIdentifier(node.expression) ||
+        node.expression.text !== "generatedFile" ||
+        node.arguments.length !== 1 ||
+        !ts.isObjectLiteralExpression(node.arguments[0]))
+        return undefined;
+    let name;
+    let type;
+    let size;
+    let sizeSource;
+    for (const property of node.arguments[0].properties) {
+        if (!ts.isPropertyAssignment(property))
+            return undefined;
+        const value = property.initializer;
+        switch (property.name.getText()) {
+            case "name":
+                name = stringOf(value);
+                if (name === undefined)
+                    return undefined;
+                break;
+            case "type":
+                type = stringOf(value);
+                if (type === undefined)
+                    return undefined;
+                break;
+            case "size": {
+                const text = stringOf(value);
+                size =
+                    text !== undefined
+                        ? parseSize(text)
+                        : ts.isNumericLiteral(value)
+                            ? parseSize(Number(value.text))
+                            : undefined;
+                if (size === undefined)
+                    return undefined;
+                sizeSource = value.getText();
+                break;
+            }
+            default:
+                return undefined;
+        }
+    }
+    if (name === undefined || size === undefined)
+        return undefined;
+    return {
+        generate: {
+            name,
+            size,
+            ...(type !== undefined && { type }),
+            ...(sizeSource !== undefined && { sizeSource }),
+        },
+    };
+}
+/** One file entry, or an array of them */
+export function readFiles(node) {
+    if (!node)
+        return undefined;
+    if (ts.isArrayLiteralExpression(node)) {
+        const entries = node.elements.map(readFileEntry);
+        return entries.every((entry) => entry !== undefined)
+            ? entries
+            : undefined;
+    }
+    const entry = readFileEntry(node);
+    return entry && [entry];
+}

package/dist/steps/parse/literals.d.ts

@@ -0,0 +1,4 @@
+import ts from "typescript";
+export declare function stringOf(node: ts.Node | undefined): string | undefined;
+/** `{ key: literal, … }` with only the allowed keys, or undefined when it has anything else */
+export declare function readObject(node: ts.Node | undefined, allowed: readonly string[]): Record<string, string | boolean> | undefined;

package/dist/steps/parse/literals.js

@@ -0,0 +1,28 @@
+import ts from "typescript";
+export function stringOf(node) {
+    return node &&
+        (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        ? node.text
+        : undefined;
+}
+/** `{ key: literal, … }` with only the allowed keys, or undefined when it has anything else */
+export function readObject(node, allowed) {
+    if (!node || !ts.isObjectLiteralExpression(node))
+        return undefined;
+    const result = {};
+    for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property) ||
+            !allowed.includes(property.name.getText()))
+            return undefined;
+        const value = stringOf(property.initializer);
+        if (value !== undefined)
+            result[property.name.getText()] = value;
+        else if (property.initializer.kind === ts.SyntaxKind.TrueKeyword)
+            result[property.name.getText()] = true;
+        else if (property.initializer.kind === ts.SyntaxKind.FalseKeyword)
+            result[property.name.getText()] = false;
+        else
+            return undefined;
+    }
+    return result;
+}

package/dist/steps/parse/step.d.ts

@@ -0,0 +1,4 @@
+import ts from "typescript";
+import type { Step } from "../model.js";
+/** The step a statement stands for, or undefined when it is outside the recorder's set */
+export declare function readStep(statement: ts.Statement): Step | undefined;

package/dist/steps/parse/step.js

@@ -0,0 +1,81 @@
+import ts from "typescript";
+import { readLocator } from "./call.js";
+import { readExpectation, readValue } from "./expectation.js";
+import { readFiles } from "./file-entry.js";
+import { readObject, stringOf } from "./literals.js";
+/** The step a statement stands for, or undefined when it is outside the recorder's set */
+export function readStep(statement) {
+    if (!ts.isExpressionStatement(statement) ||
+        !ts.isAwaitExpression(statement.expression))
+        return undefined;
+    const call = statement.expression.expression;
+    if (!ts.isCallExpression(call) ||
+        !ts.isPropertyAccessExpression(call.expression))
+        return undefined;
+    const { expression: target, name } = call.expression;
+    const args = call.arguments;
+    if (ts.isIdentifier(target) && target.text === "page") {
+        if (name.text === "goto" && args.length === 1) {
+            const url = stringOf(args[0]);
+            return url === undefined ? undefined : { kind: "goto", url };
+        }
+        if (name.text === "waitForNetworkIdle" && args.length === 0)
+            return { kind: "waitForNetworkIdle" };
+        if (name.text === "waitForTimeout" &&
+            args.length === 1 &&
+            ts.isNumericLiteral(args[0])) {
+            const ms = Number(args[0].text);
+            return Number.isInteger(ms) ? { kind: "waitForTimeout", ms } : undefined;
+        }
+        if (name.text === "screenshot" && args.length === 1) {
+            const options = readObject(args[0], ["name", "fullPage"]);
+            if (!options || typeof options.name !== "string")
+                return undefined;
+            if (options.fullPage !== undefined &&
+                typeof options.fullPage !== "boolean")
+                return undefined;
+            return {
+                kind: "screenshot",
+                name: options.name,
+                fullPage: options.fullPage === true,
+            };
+        }
+        return undefined;
+    }
+    // expect(locator).matcher(…) and expect(locator).not.matcher(…)
+    const negated = ts.isPropertyAccessExpression(target) && target.name.text === "not";
+    const subject = negated
+        ? target.expression
+        : target;
+    if (ts.isCallExpression(subject) &&
+        ts.isIdentifier(subject.expression) &&
+        subject.expression.text === "expect" &&
+        subject.arguments.length === 1) {
+        const locator = readLocator(subject.arguments[0]);
+        const expectation = readExpectation(name.text, args);
+        return locator && expectation
+            ? { kind: "expect", locator, not: negated, expectation }
+            : undefined;
+    }
+    const locator = readLocator(target);
+    if (!locator)
+        return undefined;
+    if (name.text === "click" && args.length === 0)
+        return { kind: "click", locator };
+    if (name.text === "press" && args.length === 1) {
+        const key = stringOf(args[0]);
+        return key === undefined ? undefined : { kind: "press", locator, key };
+    }
+    if (name.text === "fill" && args.length === 1) {
+        const value = readValue(args[0]);
+        return value ? { kind: "fill", locator, value } : undefined;
+    }
+    if ((name.text === "setInputFiles" || name.text === "dropFiles") &&
+        args.length === 1) {
+        const files = readFiles(args[0]);
+        return files
+            ? { kind: name.text, locator, files }
+            : undefined;
+    }
+    return undefined;
+}