@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/script/serialize.js

@@ -0,0 +1,207 @@
+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 */
+export class RemoteObject {
+    constructor(type, handle, 
+    /** The deserialized value, when the browser sent one and handles were kept */
+    value) {
+        this.type = type;
+        this.handle = handle;
+        this.value = value;
+    }
+}
+/**
+ * A channel the page function can call as `send(value)`; the browser delivers each value as a
+ * `script.message` event. Only meaningful as a preload script or function argument.
+ */
+export class ChannelArg {
+    constructor(channel) {
+        this.channel = channel;
+    }
+}
+/** Serializes `value` for `script.callFunction` arguments; throws TypeError for what cannot cross the wire */
+export function toLocalValue(value) {
+    return serialize(value, new Set(), 0);
+}
+function serialize(value, ancestors, depth) {
+    if (depth > MAX_DEPTH)
+        throw new TypeError("cannot serialize a value that is too deeply nested");
+    switch (typeof value) {
+        case "undefined":
+            return { type: "undefined" };
+        case "boolean":
+            return { type: "boolean", value };
+        case "string":
+            return { type: "string", value };
+        case "number":
+            return { type: "number", value: numberValue(value) };
+        case "bigint":
+            return { type: "bigint", value: value.toString() };
+        case "function":
+        case "symbol":
+            throw new TypeError(`cannot serialize ${typeof value}`);
+    }
+    if (value === null)
+        return { type: "null" };
+    if (value instanceof ChannelArg) {
+        // Nodes arrive as references only, which is all the recorder needs
+        return {
+            type: "channel",
+            value: {
+                channel: value.channel,
+                serializationOptions: { maxDomDepth: 0, maxObjectDepth: 4 },
+                ownership: "none",
+            },
+        };
+    }
+    if (value instanceof ElementHandle) {
+        return value.handle === undefined
+            ? { sharedId: value.sharedId }
+            : { sharedId: value.sharedId, handle: value.handle };
+    }
+    if (value instanceof Date)
+        return { type: "date", value: value.toISOString() };
+    if (value instanceof RegExp) {
+        return {
+            type: "regexp",
+            value: { pattern: value.source, flags: value.flags },
+        };
+    }
+    const object = value;
+    if (ancestors.has(object))
+        throw new TypeError("cannot serialize a circular structure");
+    ancestors.add(object);
+    try {
+        const next = (item) => serialize(item, ancestors, depth + 1);
+        if (Array.isArray(object))
+            return { type: "array", value: object.map(next) };
+        if (object instanceof Set)
+            return { type: "set", value: [...object].map(next) };
+        if (object instanceof Map) {
+            return {
+                type: "map",
+                value: [...object].map(([key, item]) => [
+                    typeof key === "string" ? key : next(key),
+                    next(item),
+                ]),
+            };
+        }
+        const prototype = Object.getPrototypeOf(object);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(`cannot serialize ${prototype.constructor?.name ?? "object"}`);
+        }
+        return {
+            type: "object",
+            value: Object.entries(object).map(([key, item]) => [key, next(item)]),
+        };
+    }
+    finally {
+        ancestors.delete(object);
+    }
+}
+function numberValue(value) {
+    if (Number.isNaN(value))
+        return "NaN";
+    if (value === Infinity)
+        return "Infinity";
+    if (value === -Infinity)
+        return "-Infinity";
+    if (Object.is(value, -0))
+        return "-0";
+    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);
+}
+function deserialize(value, known, options) {
+    const loose = value;
+    switch (value.type) {
+        case "undefined":
+            return undefined;
+        case "null":
+            return null;
+        case "string":
+        case "boolean":
+            return value.value;
+        case "number":
+            return specialNumber(value.value);
+        case "bigint":
+            return BigInt(value.value);
+        case "date":
+            return new Date(value.value);
+        case "regexp": {
+            const { pattern, flags } = loose.value;
+            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) {
+        case "array":
+        case "set":
+        case "object":
+        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;
+        }
+    }
+    return new RemoteObject(value.type, loose.handle);
+}
+function specialNumber(value) {
+    switch (value) {
+        case "NaN":
+            return NaN;
+        case "Infinity":
+            return Infinity;
+        case "-Infinity":
+            return -Infinity;
+        case "-0":
+            return -0;
+        default:
+            return Number(value);
+    }
+}

package/dist/steps/build.d.ts

@@ -0,0 +1,5 @@
+import type Locator from "../locator/locator.js";
+import type Page from "../browser/page.js";
+import type { LocatorSpec } from "./model.js";
+/** The locator a step's `LocatorSpec` stands for, with its fallbacks */
+export declare function locatorFromSpec(page: Page, spec: LocatorSpec): Locator;

package/dist/steps/build.js

@@ -0,0 +1,38 @@
+function fromCalls(page, calls) {
+    const [first, ...rest] = calls;
+    if (!first)
+        throw new Error("A locator needs at least one call");
+    const apply = (target, call) => {
+        const text = {
+            ...(call.method !== "locator" &&
+                call.method !== "getByCss" &&
+                call.method !== "getByTestId" &&
+                call.method !== "getByRole" && {
+                ...(call.match !== undefined && { match: call.match }),
+                ...(call.ignoreCase !== undefined && { ignoreCase: call.ignoreCase }),
+            }),
+        };
+        switch (call.method) {
+            case "locator":
+                return target.locator(call.xpath);
+            case "getByCss":
+                return target.getByCss(call.css);
+            case "getByText":
+                return target.getByText(call.text, text);
+            case "getByLabel":
+                return target.getByLabel(call.text, text);
+            case "getByRole":
+                return target.getByRole(call.role, call.name === undefined ? undefined : { name: call.name });
+            case "getByTestId":
+                return target.getByTestId(call.testId);
+        }
+    };
+    return rest.reduce((locator, call) => apply(locator, call), apply(page, first));
+}
+/** The locator a step's `LocatorSpec` stands for, with its fallbacks */
+export function locatorFromSpec(page, spec) {
+    const primary = fromCalls(page, spec.chain);
+    return spec.fallbacks.length === 0
+        ? primary
+        : primary.withFallbacks(...spec.fallbacks.map((chain) => fromCalls(page, chain)));
+}

package/dist/steps/edit.d.ts

@@ -0,0 +1,30 @@
+import type { Step } from "./model.js";
+export type StepEdit = {
+    op: "replace";
+    test: number;
+    index: number;
+    step: Step;
+}
+/** `index` may equal the number of steps, to append */
+ | {
+    op: "insert";
+    test: number;
+    index: number;
+    step: Step;
+} | {
+    op: "remove";
+    test: number;
+    index: number;
+}
+/** Moves a step so it ends up at position `to` */
+ | {
+    op: "move";
+    test: number;
+    from: number;
+    to: number;
+};
+/**
+ * Applies one edit and returns the new source. Only the touched statement changes: everything else,
+ * formatting and comments included, stays byte for byte.
+ */
+export declare function applyEdit(source: string, edit: StepEdit): string;

package/dist/steps/edit.js

@@ -0,0 +1,80 @@
+import { stepToSource } from "./emit.js";
+import { parseSpec } from "./parse.js";
+const lineStart = (source, offset) => source.lastIndexOf("\n", offset - 1) + 1;
+function lineEnd(source, offset) {
+    const newline = source.indexOf("\n", offset);
+    return newline === -1 ? source.length : newline + 1;
+}
+const indentOf = (source, offset) => /^[ \t]*/.exec(source.slice(lineStart(source, offset)))[0];
+function pickTest(source, test) {
+    const found = parseSpec(source)[test];
+    if (!found)
+        throw new RangeError(`There is no test ${test} in this file`);
+    return found;
+}
+function pickStep(parsed, index) {
+    const step = parsed.steps[index];
+    if (!step)
+        throw new RangeError(`Test "${parsed.name}" has no step ${index}`);
+    return step;
+}
+function splice(source, from, to, text) {
+    return source.slice(0, from) + text + source.slice(to);
+}
+/** Inserts statement text so it becomes step `index`, copying the indentation of the steps around it */
+function insertCode(source, parsed, index, code) {
+    if (index < 0 || index > parsed.steps.length) {
+        throw new RangeError(`Cannot insert at step ${index}: test "${parsed.name}" has ${parsed.steps.length}`);
+    }
+    const before = parsed.steps[index];
+    if (before) {
+        // Goes above the step's own comments, which belong to it
+        const at = lineStart(source, before.anchor);
+        return splice(source, at, at, `${indentOf(source, before.start)}${code}\n`);
+    }
+    const last = parsed.steps[parsed.steps.length - 1];
+    if (last) {
+        const indent = indentOf(source, last.start);
+        const next = lineEnd(source, last.end);
+        // After the last statement's line, so a trailing comment stays with it
+        if (next <= parsed.bodyEnd && source[next - 1] === "\n")
+            return splice(source, next, next, `${indent}${code}\n`);
+        return splice(source, last.end, last.end, `\n${indent}${code}`);
+    }
+    // Empty body: indent one level deeper than the line that closes it
+    const closing = indentOf(source, parsed.bodyEnd);
+    const rest = source.slice(parsed.bodyStart, parsed.bodyEnd);
+    const tail = rest.includes("\n") ? "" : `\n${closing}`;
+    return splice(source, parsed.bodyStart, parsed.bodyStart, `\n${closing}  ${code}${tail}`);
+}
+function removeStep(source, parsed, index) {
+    const { anchor, end } = pickStep(parsed, index);
+    return splice(source, lineStart(source, anchor), lineEnd(source, end), "");
+}
+/**
+ * Applies one edit and returns the new source. Only the touched statement changes: everything else,
+ * formatting and comments included, stays byte for byte.
+ */
+export function applyEdit(source, edit) {
+    const parsed = pickTest(source, edit.test);
+    switch (edit.op) {
+        case "replace": {
+            const { start, end } = pickStep(parsed, edit.index);
+            return splice(source, start, end, stepToSource(edit.step));
+        }
+        case "insert":
+            return insertCode(source, parsed, edit.index, stepToSource(edit.step));
+        case "remove":
+            return removeStep(source, parsed, edit.index);
+        case "move": {
+            const { start, end } = pickStep(parsed, edit.from);
+            if (edit.to < 0 || edit.to >= parsed.steps.length)
+                throw new RangeError(`Cannot move to step ${edit.to}`);
+            if (edit.to === edit.from)
+                return source;
+            const code = source.slice(start, end);
+            const removed = removeStep(source, parsed, edit.from);
+            return insertCode(removed, pickTest(removed, edit.test), edit.to, code);
+        }
+    }
+}

package/dist/steps/emit.d.ts

@@ -0,0 +1,6 @@
+import type { LocatorCall, LocatorSpec, Step, TextValue } from "./model.js";
+export declare function callToSource(call: LocatorCall): string;
+export declare function locatorToSource({ chain, fallbacks }: LocatorSpec): string;
+export declare function valueToSource(value: TextValue): string;
+/** The statement for a step, on one line */
+export declare function stepToSource(step: Step): string;

package/dist/steps/emit.js

@@ -0,0 +1,73 @@
+const str = (value) => JSON.stringify(value);
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+function textOptions(call) {
+    const parts = [
+        call.match !== undefined && `match: ${str(call.match)}`,
+        call.ignoreCase !== undefined && `ignoreCase: ${call.ignoreCase}`,
+    ].filter(Boolean);
+    return parts.length ? `, { ${parts.join(", ")} }` : "";
+}
+export function callToSource(call) {
+    switch (call.method) {
+        case "locator":
+            return `locator(${str(call.xpath)})`;
+        case "getByCss":
+            return `getByCss(${str(call.css)})`;
+        case "getByText":
+        case "getByLabel":
+            return `${call.method}(${str(call.text)}${textOptions(call)})`;
+        case "getByRole":
+            return `getByRole(${str(call.role)}${call.name === undefined ? "" : `, { name: ${str(call.name)} }`})`;
+        case "getByTestId":
+            return `getByTestId(${str(call.testId)})`;
+    }
+}
+const chainToSource = (chain) => ["page", ...chain.map(callToSource)].join(".");
+export function locatorToSource({ chain, fallbacks }) {
+    const primary = chainToSource(chain);
+    return fallbacks.length === 0
+        ? primary
+        : `${primary}.withFallbacks(${fallbacks.map(chainToSource).join(", ")})`;
+}
+export function valueToSource(value) {
+    if (value.kind === "literal")
+        return str(value.value);
+    const object = value.kind === "env" ? "env" : "secrets";
+    return IDENTIFIER.test(value.name)
+        ? `${object}.${value.name}`
+        : `${object}[${str(value.name)}]`;
+}
+function matcherToSource(expected) {
+    return typeof expected === "string"
+        ? str(expected)
+        : `/${expected.regex.source}/${expected.regex.flags}`;
+}
+function expectationToSource(expectation) {
+    switch (expectation.matcher) {
+        case "toBeVisible":
+            return "toBeVisible()";
+        case "toHaveAttribute":
+            return `toHaveAttribute(${str(expectation.name)}, ${matcherToSource(expectation.expected)})`;
+        case "toHaveCount":
+            return `toHaveCount(${expectation.expected})`;
+        default:
+            return `${expectation.matcher}(${matcherToSource(expectation.expected)})`;
+    }
+}
+/** The statement for a step, on one line */
+export function stepToSource(step) {
+    switch (step.kind) {
+        case "goto":
+            return `await page.goto(${str(step.url)});`;
+        case "click":
+            return `await ${locatorToSource(step.locator)}.click();`;
+        case "fill":
+            return `await ${locatorToSource(step.locator)}.fill(${valueToSource(step.value)});`;
+        case "expect":
+            return `await expect(${locatorToSource(step.locator)})${step.not ? ".not" : ""}.${expectationToSource(step.expectation)};`;
+        case "waitForNetworkIdle":
+            return "await page.waitForNetworkIdle();";
+        case "custom":
+            return step.code;
+    }
+}

package/dist/steps/index.d.ts

@@ -0,0 +1,5 @@
+export { parseSpec } from "./parse.js";
+export { applyEdit, type StepEdit } from "./edit.js";
+export { stepToSource, locatorToSource, callToSource, valueToSource, } from "./emit.js";
+export { locatorFromSpec } from "./build.js";
+export type { Expectation, LocatorCall, LocatorSpec, ParsedStep, ParsedTest, Step, TextMatcher, TextValue, } from "./model.js";

package/dist/steps/index.js

@@ -0,0 +1,4 @@
+export { parseSpec } from "./parse.js";
+export { applyEdit } from "./edit.js";
+export { stepToSource, locatorToSource, callToSource, valueToSource, } from "./emit.js";
+export { locatorFromSpec } from "./build.js";

package/dist/steps/model.d.ts

@@ -0,0 +1,103 @@
+/** One call of a locator expression, as written in a spec: `page.getByRole("button", { name: "Save" })` */
+export type LocatorCall = {
+    method: "locator";
+    xpath: string;
+} | {
+    method: "getByCss";
+    css: string;
+} | {
+    method: "getByText";
+    text: string;
+    match?: "full" | "partial";
+    ignoreCase?: boolean;
+} | {
+    method: "getByLabel";
+    text: string;
+    match?: "full" | "partial";
+    ignoreCase?: boolean;
+} | {
+    method: "getByRole";
+    role: string;
+    name?: string;
+} | {
+    method: "getByTestId";
+    testId: string;
+};
+/** A chain of locator calls on `page`, and the locators `withFallbacks` falls back to, most preferred first */
+export interface LocatorSpec {
+    chain: LocatorCall[];
+    fallbacks: LocatorCall[][];
+}
+/** A text to type or compare with */
+export type TextValue = {
+    kind: "literal";
+    value: string;
+} | {
+    kind: "env";
+    name: string;
+} | {
+    kind: "secret";
+    name: string;
+};
+/** What an assertion expects of text: a string or a regular expression */
+export type TextMatcher = string | {
+    regex: {
+        source: string;
+        flags: string;
+    };
+};
+export type Expectation = {
+    matcher: "toBeVisible";
+} | {
+    matcher: "toHaveText" | "toContainText" | "toHaveValue";
+    expected: TextMatcher;
+} | {
+    matcher: "toHaveAttribute";
+    name: string;
+    expected: TextMatcher;
+} | {
+    matcher: "toHaveCount";
+    expected: number;
+};
+/** The restricted set of statements the recorder writes. Anything else in a test is a `custom` step */
+export type Step = {
+    kind: "goto";
+    url: string;
+} | {
+    kind: "click";
+    locator: LocatorSpec;
+} | {
+    kind: "fill";
+    locator: LocatorSpec;
+    value: TextValue;
+} | {
+    kind: "expect";
+    locator: LocatorSpec;
+    not: boolean;
+    expectation: Expectation;
+} | {
+    kind: "waitForNetworkIdle";
+}
+/** A statement the codec does not understand, kept verbatim */
+ | {
+    kind: "custom";
+    code: string;
+};
+/** A step and where its statement sits in the source */
+export interface ParsedStep {
+    step: Step;
+    /** Offset of the statement's first character (after leading comments) */
+    start: number;
+    end: number;
+    /** Offset where the statement's own lines begin, leading comments included */
+    anchor: number;
+}
+export interface ParsedTest {
+    /** describe titles, then the test title */
+    titlePath: string[];
+    name: string;
+    steps: ParsedStep[];
+    /** Offset just after the `{` of the test body, and of its closing `}` */
+    bodyStart: number;
+    bodyEnd: number;
+}

package/dist/steps/model.js

@@ -0,0 +1 @@
+export {};

package/dist/steps/parse.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedTest } from "./model.js";
+/** The tests in a spec file, with their steps and where each statement sits */
+export declare function parseSpec(source: string): ParsedTest[];