@itmetsam/samurai-framework 0.19.0 → 0.21.0

package/dist/steps/test-options.js

@@ -0,0 +1,158 @@
+import ts from "typescript";
+import { isIoName } from "../flows/core/steps.js";
+import { IDENTIFIER } from "./emit.js";
+import { stringOf } from "./parse/literals.js";
+import { indentOf, splice } from "./text.js";
+function keyOf(name) {
+    return ts.isIdentifier(name) || ts.isStringLiteral(name)
+        ? name.text
+        : undefined;
+}
+/** `{ name: "default", … }`; undefined for anything but string literals under plain keys */
+function readInputs(node) {
+    if (!ts.isObjectLiteralExpression(node))
+        return undefined;
+    const inputs = [];
+    for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property))
+            return undefined;
+        const name = keyOf(property.name);
+        const value = stringOf(property.initializer);
+        if (name === undefined || value === undefined)
+            return undefined;
+        inputs.push({ name, default: value });
+    }
+    return inputs;
+}
+/** `["name", …]`; undefined for anything but string literals */
+function readOutputs(node) {
+    if (!ts.isArrayLiteralExpression(node))
+        return undefined;
+    const names = node.elements.map(stringOf);
+    return names.every((name) => name !== undefined)
+        ? names
+        : undefined;
+}
+/**
+ * The options object of a test or describe call: a describe takes only `reason`, a test also `inputs` and
+ * `outputs`. Undefined when the object isn't a literal the codec can read, so the call is left unparsed. An
+ * empty list is left out, as the runtime leaves it out. A `reason` counts only for skip and fixme, and one that
+ * isn't a string literal is passed over, as before
+ */
+export function readTestOptions(node, kind, modifier) {
+    if (!ts.isObjectLiteralExpression(node))
+        return undefined;
+    const read = {};
+    for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property))
+            return undefined;
+        const key = keyOf(property.name);
+        const value = property.initializer;
+        if (key === "reason") {
+            const reason = stringOf(value);
+            if (reason !== undefined && (modifier === "skip" || modifier === "fixme"))
+                read.reason = reason;
+        }
+        else if (kind === "test" && key === "inputs") {
+            const inputs = readInputs(value);
+            if (!inputs)
+                return undefined;
+            if (inputs.length > 0)
+                read.inputs = inputs;
+        }
+        else if (kind === "test" && key === "outputs") {
+            const outputs = readOutputs(value);
+            if (!outputs)
+                return undefined;
+            if (outputs.length > 0)
+                read.outputs = outputs;
+        }
+        else
+            return undefined;
+    }
+    return read;
+}
+const str = (value) => JSON.stringify(value);
+function listToSource(key, list) {
+    if (key === "outputs")
+        return `[${list.map(str).join(", ")}]`;
+    const entries = list.map(({ name, default: value }) => `${IDENTIFIER.test(name) ? name : str(name)}: ${str(value)}`);
+    return `{ ${entries.join(", ")} }`;
+}
+const sameList = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/** Throws for a list the runtime's `test()` would reject: a name that isn't valid, a name twice, a default that isn't text */
+function checkList(key, list) {
+    const kind = key === "inputs" ? "input" : "output";
+    const seen = new Set();
+    for (const entry of list) {
+        const name = typeof entry === "string" ? entry : entry.name;
+        if (!isIoName(name))
+            throw new Error(`applyEdit(): ${kind} ${JSON.stringify(name)} is not a valid name`);
+        if (seen.has(name))
+            throw new Error(`applyEdit(): ${kind} "${name}" is listed twice`);
+        seen.add(name);
+        if (typeof entry !== "string" && typeof entry.default !== "string")
+            throw new Error(`applyEdit(): input "${name}" needs a string default`);
+    }
+}
+/** The options object at `range`, parsed on its own, with offsets mapped back into the source */
+function optionsObject(source, range) {
+    const file = ts.createSourceFile("options.ts", `(${source.slice(range.start, range.end)})`, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const statement = file.statements[0];
+    const object = statement.expression
+        .expression;
+    const at = (offset) => offset - 1 + range.start;
+    return object.properties.map((property) => {
+        const assignment = property;
+        return {
+            key: keyOf(assignment.name),
+            start: at(assignment.getStart(file)),
+            end: at(assignment.end),
+            valueStart: at(assignment.initializer.getStart(file)),
+            emptyList: (ts.isObjectLiteralExpression(assignment.initializer) &&
+                assignment.initializer.properties.length === 0) ||
+                (ts.isArrayLiteralExpression(assignment.initializer) &&
+                    assignment.initializer.elements.length === 0),
+        };
+    });
+}
+/**
+ * Sets one list of the test's options object: replaces it, adds it (making the object when there is none) or,
+ * for an empty list, removes it, and the whole object when nothing but empty lists would be left. The rest of
+ * the object, its layout and a `reason`, stays as it is; an unchanged list leaves the source as it is. Throws for
+ * names the runtime rejects, before writing
+ */
+export function declareList(source, parsed, key, list) {
+    checkList(key, list);
+    if (list.length > 0 && sameList(parsed[key], list))
+        return source;
+    const text = `${key}: ${listToSource(key, list)}`;
+    if (!parsed.options)
+        return list.length === 0
+            ? source
+            : splice(source, parsed.titleEnd, parsed.titleEnd, `, { ${text} }`);
+    const properties = optionsObject(source, parsed.options);
+    const index = properties.findIndex((property) => property.key === key);
+    const property = properties[index];
+    if (list.length === 0) {
+        // An empty list that is there still goes (the parse leaves it out), so an object of only empty lists is removed
+        if (!property)
+            return source;
+        const others = properties.filter((_, i) => i !== index);
+        if (others.every((other) => other.emptyList))
+            return splice(source, parsed.titleEnd, parsed.options.end, "");
+        return index > 0
+            ? splice(source, properties[index - 1].end, property.end, "")
+            : splice(source, property.start, properties[1].start, "");
+    }
+    if (property)
+        return splice(source, property.valueStart, property.end, listToSource(key, list));
+    const last = properties[properties.length - 1];
+    if (!last)
+        return splice(source, parsed.options.start, parsed.options.end, `{ ${text} }`);
+    const multiline = source
+        .slice(parsed.options.start, properties[0].start)
+        .includes("\n");
+    const separator = multiline ? `\n${indentOf(source, last.start)}` : " ";
+    return splice(source, last.end, last.end, `,${separator}${text}`);
+}

package/dist/steps/text.d.ts

@@ -0,0 +1,7 @@
+/** Offset of the first character of the line `offset` is on */
+export declare const lineStart: (source: string, offset: number) => number;
+/** Offset just after the newline that ends the line `offset` is on, or the end of the source */
+export declare function lineEnd(source: string, offset: number): number;
+/** The spaces and tabs that start the line `offset` is on */
+export declare const indentOf: (source: string, offset: number) => string;
+export declare function splice(source: string, from: number, to: number, text: string): string;

package/dist/steps/text.js

@@ -0,0 +1,12 @@
+/** Offset of the first character of the line `offset` is on */
+export const lineStart = (source, offset) => source.lastIndexOf("\n", offset - 1) + 1;
+/** Offset just after the newline that ends the line `offset` is on, or the end of the source */
+export function lineEnd(source, offset) {
+    const newline = source.indexOf("\n", offset);
+    return newline === -1 ? source.length : newline + 1;
+}
+/** The spaces and tabs that start the line `offset` is on */
+export const indentOf = (source, offset) => /^[ \t]*/.exec(source.slice(lineStart(source, offset)))[0];
+export function splice(source, from, to, text) {
+    return source.slice(0, from) + text + source.slice(to);
+}

package/dist/types/test.d.ts

@@ -1,5 +1,6 @@
 import type { Browser } from "../browser/browser.js";
 import type Page from "../browser/page.js";
+import type Locator from "../locator/locator.js";
 import type { SupportedBrowser } from "./browser.js";
 
 /** What a test function receives */
@@ -14,6 +15,19 @@ export interface TestFixtures {
   env: Readonly<Record<string, string | number | boolean>>;
   /** Secrets by name (SAMURAI_SECRET_<NAME>); reading an unset name throws */
   secrets: Readonly<Record<string, string>>;
+  /** The inputs the test declared: the value the run supplies, else the default; reading another name throws */
+  inputs: Readonly<Record<string, string>>;
+  /** Saves the text values the test declared as outputs */
+  outputs: TestOutputs;
+}
+
+/** The `outputs` fixture */
+export interface TestOutputs {
+  /**
+   * Waits up to the expect timeout for the element to have text and saves its trimmed text as output `name`.
+   * With `pattern`, waits until the text matches and saves the first capture group, else the whole match.
+   */
+  save(name: string, locator: Locator, pattern?: RegExp): Promise<void>;
 }
 
 export type TestCase = TestCaseBase;
@@ -27,6 +41,14 @@ export interface TestDetails {
   reason?: string;
 }
 
+/** The optional second argument of `test`, `test.only`, `test.skip` and `test.fixme` */
+export interface TestOptions extends TestDetails {
+  /** Named text values the test reads, each with the default it gets when nothing supplies one */
+  inputs?: Record<string, string>;
+  /** Names of the text values the test saves for later tests to use */
+  outputs?: string[];
+}
+
 /** Runs before or after each test of a suite, in the test's browser, with the test's fixtures */
 export type EachHook = (fixtures: TestFixtures) => Promise<void> | void;
 
@@ -64,6 +86,10 @@ export interface RegisteredTestCase extends TestCaseBase {
   modifier?: Modifier;
   /** The reason given with the `skip` or `fixme` that applies */
   reason?: string;
+  /** The inputs the test declared, with their defaults */
+  inputs?: Record<string, string>;
+  /** The names of the outputs the test declared */
+  outputs?: string[];
 }
 
 export interface TestCaseBase {
@@ -88,6 +114,10 @@ interface TestResultSuccess extends TestResultIdentity, TestRetries {
   logsDropped?: number;
   /** Named screenshots the test saved, relative to the result folder */
   screenshots?: { name: string; path: string }[];
+  /** The inputs the test declared, with the values this attempt read; absent when it declares none */
+  inputs?: Record<string, string>;
+  /** The outputs the test saved; absent when it declares none */
+  outputs?: Record<string, string>;
 }
 
 /** The error sits flat on the entry, as in the report: `message`, `type`, `stack`, and for assertions `expected` and `actual` */
@@ -98,6 +128,10 @@ interface TestResultFailed extends TestResultIdentity, TestError, TestRetries {
   logsDropped?: number;
   /** Named screenshots the test saved, relative to the result folder */
   screenshots?: { name: string; path: string }[];
+  /** The inputs the test declared, with the values this attempt read; absent when it declares none */
+  inputs?: Record<string, string>;
+  /** The outputs the test saved; absent when it declares none */
+  outputs?: Record<string, string>;
 }
 
 /** What a result says about the retries of its test; absent when it passed or failed on the first attempt */

package/dist/wait/output-sink.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Where one attempt of a test keeps the outputs it saves. Once closed it ignores what still arrives, so a
+ * capture that outlives its test (it timed out, or nobody awaited it) never lands in the next one.
+ */
+export interface OutputSink {
+    /** Whether the test declared `name` */
+    declares(name: string): boolean;
+    /** Keeps `value` under `name`; throws for a name the test did not declare, ignores it once closed */
+    set(name: string, value: string): void;
+    /** What was saved so far */
+    values(): Record<string, string>;
+}
+/** Opens the sink of an attempt that declared `declared`, closing any one still open */
+export declare function beginOutputs(declared: readonly string[]): OutputSink;
+/** The open sink, or none outside a test. A capture takes it when it starts and saves into that one */
+export declare function currentOutputSink(): OutputSink | undefined;
+/** Closes the open sink and returns what it holds */
+export declare function endOutputs(): Record<string, string>;
+/**
+ * Takes the open sink for a capture that starts now (`method` names the call in the errors) and returns the
+ * function that saves `value` under `name` into it. The sink is bound here: a value that arrives after the test
+ * ended goes to its own closed sink and is ignored.
+ */
+export declare function bindOutput(method: string, name: string): (value: string) => void;

package/dist/wait/output-sink.js

@@ -0,0 +1,59 @@
+/*
+ * The outputs a running test saves. It lives here, below `assert` and `locator`, because both save into it
+ * (`fill`, the text checks) and neither may import `runner`.
+ */
+class Sink {
+    constructor(declared) {
+        this.declared = declared;
+        this.saved = {};
+        this.closed = false;
+    }
+    declares(name) {
+        return this.declared.includes(name);
+    }
+    set(name, value) {
+        if (this.closed)
+            return;
+        if (!this.declares(name))
+            throw new Error(`output ${JSON.stringify(name)} is not declared`);
+        this.saved[name] = value;
+    }
+    values() {
+        return { ...this.saved };
+    }
+}
+/** The sink of the attempt that is running; one at a time, like the pending assertions */
+let current;
+/** Opens the sink of an attempt that declared `declared`, closing any one still open */
+export function beginOutputs(declared) {
+    if (current)
+        current.closed = true;
+    current = new Sink(declared);
+    return current;
+}
+/** The open sink, or none outside a test. A capture takes it when it starts and saves into that one */
+export function currentOutputSink() {
+    return current;
+}
+/** Closes the open sink and returns what it holds */
+export function endOutputs() {
+    const sink = current;
+    current = undefined;
+    if (!sink)
+        return {};
+    sink.closed = true;
+    return sink.values();
+}
+/**
+ * Takes the open sink for a capture that starts now (`method` names the call in the errors) and returns the
+ * function that saves `value` under `name` into it. The sink is bound here: a value that arrives after the test
+ * ended goes to its own closed sink and is ignored.
+ */
+export function bindOutput(method, name) {
+    const sink = current;
+    if (!sink)
+        throw new Error(`${method}: output can only be saved inside a test`);
+    if (!sink.declares(name))
+        throw new Error(`${method}: output ${JSON.stringify(name)} is not declared`);
+    return (value) => sink.set(name, value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {