@itmetsam/samurai-framework 0.5.0 → 0.7.0

package/dist/project/config-edit.js

@@ -0,0 +1,218 @@
+import ts from "typescript";
+/** The config can't be edited in place, e.g. it builds its object from variables or spreads */
+export class ConfigEditError extends Error {
+}
+const KEY = /^[A-Za-z_$][\w$]*$/;
+const keyText = (key) => (KEY.test(key) ? key : JSON.stringify(key));
+function emit(value, indent, unit) {
+    if (typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        const inner = indent + unit;
+        return `[\n${value.map((v) => `${inner}${emit(v, inner, unit)},`).join("\n")}\n${indent}]`;
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return "{}";
+    const inner = indent + unit;
+    return `{\n${entries
+        .map(([k, v]) => `${inner}${keyText(k)}: ${emit(v, inner, unit)},`)
+        .join("\n")}\n${indent}}`;
+}
+function nameOf(prop) {
+    if (!ts.isPropertyAssignment(prop) &&
+        !ts.isShorthandPropertyAssignment(prop)) {
+        return undefined;
+    }
+    const n = prop.name;
+    return ts.isIdentifier(n) ||
+        ts.isStringLiteral(n) ||
+        ts.isNoSubstitutionTemplateLiteral(n)
+        ? n.text
+        : undefined;
+}
+/** The object `defineConfig({...})` or `export default {...}` is given */
+function rootObject(sf) {
+    for (const statement of sf.statements) {
+        if (!ts.isExportAssignment(statement))
+            continue;
+        let node = statement.expression;
+        for (;;) {
+            if (ts.isParenthesizedExpression(node) ||
+                ts.isSatisfiesExpression(node) ||
+                ts.isAsExpression(node)) {
+                node = node.expression;
+            }
+            else
+                break;
+        }
+        if (ts.isCallExpression(node) &&
+            node.arguments[0] &&
+            ts.isObjectLiteralExpression(node.arguments[0])) {
+            return node.arguments[0];
+        }
+        if (ts.isObjectLiteralExpression(node))
+            return node;
+    }
+    throw new ConfigEditError("samurai.config.ts doesn't export a plain object (defineConfig({ … })), so it can't be edited here.");
+}
+const lineIndent = (source, pos) => {
+    const start = source.lastIndexOf("\n", pos - 1) + 1;
+    return /^[ \t]*/.exec(source.slice(start))[0];
+};
+function unitOf(source, obj) {
+    const first = obj.properties[0];
+    if (first) {
+        const inner = lineIndent(source, first.getStart());
+        const outer = lineIndent(source, obj.getStart());
+        if (inner.length > outer.length)
+            return inner.slice(outer.length);
+    }
+    return "  ";
+}
+function insertProperty(source, obj, key, value) {
+    const unit = unitOf(source, obj);
+    const outer = lineIndent(source, obj.getStart());
+    const inner = outer + unit;
+    const multiline = obj.getText().includes("\n");
+    const prop = `${keyText(key)}: ${emit(value, inner, unit)}`;
+    const last = obj.properties[obj.properties.length - 1];
+    if (!last) {
+        return {
+            start: obj.getStart(),
+            end: obj.end,
+            text: `{\n${inner}${prop},\n${outer}}`,
+        };
+    }
+    const trailing = obj.properties.hasTrailingComma
+        ? /^\s*,/.exec(source.slice(last.end))
+        : null;
+    if (!multiline) {
+        return trailing
+            ? {
+                start: last.end + trailing[0].length,
+                end: last.end + trailing[0].length,
+                text: ` ${keyText(key)}: ${emit(value, outer, unit)},`,
+            }
+            : {
+                start: last.end,
+                end: last.end,
+                text: `, ${keyText(key)}: ${emit(value, outer, unit)}`,
+            };
+    }
+    return trailing
+        ? {
+            start: last.end + trailing[0].length,
+            end: last.end + trailing[0].length,
+            text: `\n${inner}${prop},`,
+        }
+        : { start: last.end, end: last.end, text: `,\n${inner}${prop}` };
+}
+function removeProperty(source, prop) {
+    const s = prop.getStart();
+    let e = prop.end;
+    const comma = /^[ \t]*,/.exec(source.slice(e));
+    if (comma)
+        e += comma[0].length;
+    const lineStart = source.lastIndexOf("\n", s - 1) + 1;
+    const aloneBefore = /^[ \t]*$/.test(source.slice(lineStart, s));
+    const rest = /^[ \t]*(\r?\n)/.exec(source.slice(e));
+    if (aloneBefore && rest)
+        return { start: lineStart, end: e + rest[0].length, text: "" };
+    const space = /^[ \t]*/.exec(source.slice(e))[0];
+    return { start: s, end: e + space.length, text: "" };
+}
+/**
+ * Sets (or with `undefined`, removes) one value in samurai.config.ts, addressed by its path, e.g.
+ * ["environments", "staging", "baseURL"]. Only that property's text changes; missing objects on the way are
+ * created. Throws ConfigEditError when the file isn't shaped so that this is safe.
+ */
+export function editConfig(source, path, value) {
+    if (path.length === 0)
+        throw new ConfigEditError("No setting given.");
+    const sf = ts.createSourceFile("samurai.config.ts", source, ts.ScriptTarget.Latest, true);
+    let obj = rootObject(sf);
+    for (let i = 0; i < path.length; i++) {
+        const key = path[i];
+        const prop = obj.properties.find((p) => nameOf(p) === key);
+        const isLast = i === path.length - 1;
+        if (prop && !ts.isPropertyAssignment(prop)) {
+            throw new ConfigEditError(`"${key}" in samurai.config.ts isn't a plain value (shorthand or spread), so it can't be edited here.`);
+        }
+        if (isLast) {
+            let splice;
+            if (value === undefined) {
+                if (!prop)
+                    return source;
+                splice = removeProperty(source, prop);
+            }
+            else if (prop && ts.isPropertyAssignment(prop)) {
+                const init = prop.initializer;
+                const unit = unitOf(source, obj);
+                splice = {
+                    start: init.getStart(),
+                    end: init.end,
+                    text: emit(value, lineIndent(source, prop.getStart()), unit),
+                };
+            }
+            else {
+                splice = insertProperty(source, obj, key, value);
+            }
+            return (source.slice(0, splice.start) + splice.text + source.slice(splice.end));
+        }
+        if (!prop) {
+            if (value === undefined)
+                return source;
+            // Build the rest of the path as one nested object and add it here
+            let nested = value;
+            for (let j = path.length - 1; j > i; j--)
+                nested = { [path[j]]: nested };
+            const splice = insertProperty(source, obj, key, nested);
+            return (source.slice(0, splice.start) + splice.text + source.slice(splice.end));
+        }
+        if (!ts.isObjectLiteralExpression(prop.initializer)) {
+            throw new ConfigEditError(`"${key}" in samurai.config.ts isn't a plain object, so it can't be edited here.`);
+        }
+        obj = prop.initializer;
+    }
+    return source;
+}
+/** The text of one property (`staging: { … }`), indentation removed, for showing a part of the file; undefined when missing */
+export function propertyText(source, path) {
+    const sf = ts.createSourceFile("samurai.config.ts", source, ts.ScriptTarget.Latest, true);
+    let obj;
+    try {
+        obj = rootObject(sf);
+    }
+    catch {
+        return undefined;
+    }
+    for (let i = 0; i < path.length; i++) {
+        const prop = obj.properties.find((p) => nameOf(p) === path[i]);
+        if (!prop)
+            return undefined;
+        if (i === path.length - 1) {
+            const indent = lineIndent(source, prop.getStart());
+            return prop
+                .getText()
+                .split("\n")
+                .map((line, n) => n === 0
+                ? line
+                : line.startsWith(indent)
+                    ? line.slice(indent.length)
+                    : line.trimStart())
+                .join("\n");
+        }
+        if (!ts.isPropertyAssignment(prop) ||
+            !ts.isObjectLiteralExpression(prop.initializer))
+            return undefined;
+        obj = prop.initializer;
+    }
+    return undefined;
+}
+/** Whether the property at this path exists in the file's source, walking the same object literals `editConfig` does */
+export function hasConfigPath(source, path) {
+    return propertyText(source, path) !== undefined;
+}

package/dist/project/index.d.ts

@@ -0,0 +1,3 @@
+export { ConfigEditError, editConfig, hasConfigPath, propertyText, type ConfigValue, } from "./config-edit.js";
+export { addVariable, ExistsError, VARIABLE_NAME } from "./variables.js";
+export { isGitIgnored, SECRET_NAME, setSecret } from "./secrets-file.js";

package/dist/project/index.js

@@ -0,0 +1,3 @@
+export { ConfigEditError, editConfig, hasConfigPath, propertyText, } from "./config-edit.js";
+export { addVariable, ExistsError, VARIABLE_NAME } from "./variables.js";
+export { isGitIgnored, SECRET_NAME, setSecret } from "./secrets-file.js";

package/dist/project/secrets-file.d.ts

@@ -0,0 +1,8 @@
+export declare const SECRET_NAME: RegExp;
+/** Whether .gitignore covers this file: its name, or `.env*` / `.env.*` */
+export declare function isGitIgnored(projectDir: string, file: string): Promise<boolean>;
+/**
+ * Sets SAMURAI_SECRET_<name> in .env.<environment>, replacing its line or adding one. The value is masked
+ * in this process's logs from then on, as a secret loaded from the file would be
+ */
+export declare function setSecret(projectDir: string, environment: string, name: string, value: string): Promise<void>;

package/dist/project/secrets-file.js

@@ -0,0 +1,69 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { registerSecret } from "../config/mask.js";
+const PREFIX = "SAMURAI_SECRET_";
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]*$/;
+const ENVIRONMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+function envFile(projectDir, environment) {
+    // The name ends up in a file name: keep it to plain characters
+    if (!ENVIRONMENT.test(environment))
+        throw new Error(`"${environment}" isn't a valid environment name.`);
+    return path.join(projectDir, `.env.${environment}`);
+}
+function checkName(name) {
+    if (!SECRET_NAME.test(name))
+        throw new Error("Use letters, digits and _; a secret is UPPER_SNAKE_CASE.");
+}
+/**
+ * dotenv value: bare when that is safe, else in the quotes that need no escaping. Node's parser, which the
+ * framework reads these files with, can't escape a quote inside a quote, so the quote kind is picked to not
+ * occur in the value.
+ */
+function formatValue(value) {
+    if (/^[A-Za-z0-9_./:@%+=-]*$/.test(value))
+        return value;
+    if (!value.includes("'") && !/[\r\n]/.test(value))
+        return `'${value}'`;
+    if (!value.includes("`"))
+        return `\`${value}\``;
+    if (!value.includes('"') && !value.includes("\\") && !/[\r\n]/.test(value))
+        return `"${value}"`;
+    throw new Error("This value has both ' and ` characters (and more), which a .env file can't hold. Set it as a SAMURAI_SECRET_* environment variable instead.");
+}
+const lineFor = (name) => new RegExp(`^[ \\t]*(?:export[ \\t]+)?${PREFIX}${name}[ \\t]*=`);
+/** Whether .gitignore covers this file: its name, or `.env*` / `.env.*` */
+export async function isGitIgnored(projectDir, file) {
+    try {
+        const text = await readFile(path.join(projectDir, ".gitignore"), "utf8");
+        return text.split(/\r?\n/).some((l) => {
+            const line = l.trim().replace(/^\//, "");
+            return line === file || line === ".env*" || line === ".env.*";
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Sets SAMURAI_SECRET_<name> in .env.<environment>, replacing its line or adding one. The value is masked
+ * in this process's logs from then on, as a secret loaded from the file would be
+ */
+export async function setSecret(projectDir, environment, name, value) {
+    checkName(name);
+    if (value === "")
+        throw new Error("A secret can't be empty. Remove it instead.");
+    if (/\r|\n/.test(value) && !value.trim())
+        throw new Error("A secret can't be only line breaks.");
+    const file = envFile(projectDir, environment);
+    const text = existsSync(file) ? await readFile(file, "utf8") : "";
+    const lines = text === "" ? [] : text.replace(/\n$/, "").split("\n");
+    const line = `${PREFIX}${name}=${formatValue(value)}`;
+    const at = lines.findIndex((l) => lineFor(name).test(l));
+    if (at >= 0)
+        lines[at] = line;
+    else
+        lines.push(line);
+    await writeFile(file, lines.join("\n") + "\n", { mode: 0o600 });
+    registerSecret(name, value);
+}

package/dist/project/variables.d.ts

@@ -0,0 +1,6 @@
+/** The name is already set in that environment */
+export declare class ExistsError extends Error {
+}
+export declare const VARIABLE_NAME: RegExp;
+/** Adds a variable to one environment in samurai.config.ts; only that property's text changes */
+export declare function addVariable(projectDir: string, environment: string, name: string, value: string): Promise<void>;

package/dist/project/variables.js

@@ -0,0 +1,17 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { editConfig, hasConfigPath } from "./config-edit.js";
+/** The name is already set in that environment */
+export class ExistsError extends Error {
+}
+export const VARIABLE_NAME = /^[A-Za-z_$][\w$]*$/;
+/** Adds a variable to one environment in samurai.config.ts; only that property's text changes */
+export async function addVariable(projectDir, environment, name, value) {
+    if (!VARIABLE_NAME.test(name))
+        throw new Error("Use letters, digits and _, starting with a letter.");
+    const file = path.join(projectDir, "samurai.config.ts");
+    const source = await readFile(file, "utf8");
+    if (hasConfigPath(source, ["environments", environment, "variables", name]))
+        throw new ExistsError(`"${name}" already exists`);
+    await writeFile(file, editConfig(source, ["environments", environment, "variables", name], value));
+}

package/dist/recorder/candidates.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Declarations that turn an element into locator candidates (test id, role and name, label, text, css and
+ * an absolute xpath), plus `inToolbar(event)`, which is true for events from the recorder toolbar. A string
+ * of plain declarations, interpolated into the capture script (page realm) and the toolbar script
+ * (sandbox realm), so no transpiler helper can end up in it.
+ */
+export declare const CANDIDATES_JS: string;

package/dist/recorder/candidates.js

@@ -0,0 +1,118 @@
+/**
+ * Declarations that turn an element into locator candidates (test id, role and name, label, text, css and
+ * an absolute xpath), plus `inToolbar(event)`, which is true for events from the recorder toolbar. A string
+ * of plain declarations, interpolated into the capture script (page realm) and the toolbar script
+ * (sandbox realm), so no transpiler helper can end up in it.
+ */
+export const CANDIDATES_JS = String.raw `
+const norm = (text) => String(text == null ? "" : text).replace(/\s+/g, " ").trim();
+const textOf = (node) => norm(node.innerText != null ? node.innerText : node.textContent);
+const NO_ROLE_TYPES = ["hidden", "password", "file", "color", "date", "datetime-local", "month", "time", "week"];
+const TEXT_TYPES = ["", "text", "email", "search", "tel", "url", "password", "number"];
+
+const roleOf = (el) => {
+  const explicit = norm(el.getAttribute("role")).split(" ")[0];
+  if (explicit) return explicit;
+  const tag = el.tagName.toLowerCase();
+  if (tag === "a") return el.hasAttribute("href") ? "link" : undefined;
+  if (tag === "button" || tag === "summary") return "button";
+  if (tag === "select") return el.multiple || el.size > 1 ? "listbox" : "combobox";
+  if (tag === "textarea") return "textbox";
+  if (/^h[1-6]$/.test(tag)) return "heading";
+  if (tag === "img") return "img";
+  if (tag === "input") {
+    const type = (el.getAttribute("type") || "text").toLowerCase();
+    if (NO_ROLE_TYPES.indexOf(type) >= 0) return undefined;
+    if (type === "checkbox" || type === "radio") return type;
+    if (type === "button" || type === "submit" || type === "reset" || type === "image") return "button";
+    if (type === "range") return "slider";
+    if (type === "number") return "spinbutton";
+    if (type === "search") return "searchbox";
+    return "textbox";
+  }
+  return undefined;
+};
+
+const labelTexts = (el) => {
+  const texts = [];
+  if (el.labels) for (const label of el.labels) texts.push(textOf(label));
+  const by = el.getAttribute("aria-labelledby");
+  if (by) {
+    for (const id of by.split(/\s+/)) {
+      const named = id && document.getElementById(id);
+      if (named) texts.push(textOf(named));
+    }
+  }
+  const own = el.getAttribute("aria-label");
+  if (own) texts.push(norm(own));
+  return texts.filter(Boolean);
+};
+
+const nameOf = (el, role) => {
+  const labelled = labelTexts(el)[0];
+  if (labelled) return labelled;
+  const tag = el.tagName.toLowerCase();
+  if (tag === "input") {
+    const type = (el.getAttribute("type") || "").toLowerCase();
+    return type === "submit" || type === "button" || type === "reset" ? norm(el.value) : "";
+  }
+  if (tag === "img") return norm(el.getAttribute("alt"));
+  if (role === "textbox" || role === "combobox" || role === "listbox") return "";
+  return textOf(el) || norm(el.getAttribute("title"));
+};
+
+const plain = (value) => value.indexOf('"') < 0 && value.indexOf("\\") < 0;
+
+const xpathOf = (el) => {
+  const parts = [];
+  for (let node = el; node && node.nodeType === 1; node = node.parentElement) {
+    let index = 1;
+    for (let sibling = node.previousElementSibling; sibling; sibling = sibling.previousElementSibling) {
+      if (sibling.tagName === node.tagName) index++;
+    }
+    parts.unshift(node.tagName.toLowerCase() + "[" + index + "]");
+  }
+  return "/" + parts.join("/");
+};
+
+const candidatesOf = (el) => {
+  const found = [];
+  const tag = el.tagName.toLowerCase();
+  const testId = el.getAttribute("data-testid");
+  if (testId) found.push({ method: "getByTestId", testId });
+  const role = roleOf(el);
+  if (role) {
+    const name = nameOf(el, role);
+    if (name && name.length <= 80) found.push({ method: "getByRole", role, name });
+  }
+  const label = labelTexts(el)[0];
+  if (label && label.length <= 80 && el.labels !== undefined) found.push({ method: "getByLabel", text: label });
+  const text = textOf(el);
+  if (text && text.length <= 60 && tag !== "input" && tag !== "textarea" && tag !== "select") {
+    found.push({ method: "getByText", text });
+  }
+  if (el.id && /^[A-Za-z][\w-]*$/.test(el.id) && !/\d{3,}/.test(el.id)) found.push({ method: "getByCss", css: "#" + el.id });
+  const name = el.getAttribute("name");
+  if (name && plain(name)) found.push({ method: "getByCss", css: tag + '[name="' + name + '"]' });
+  const placeholder = el.getAttribute("placeholder");
+  if (placeholder && plain(placeholder)) found.push({ method: "getByCss", css: tag + '[placeholder="' + placeholder + '"]' });
+  found.push({ method: "locator", xpath: xpathOf(el) });
+  return found;
+};
+
+const isTextEntry = (el) => {
+  const tag = el.tagName.toLowerCase();
+  if (tag === "textarea") return true;
+  if (tag === "input") return TEXT_TYPES.indexOf((el.getAttribute("type") || "").toLowerCase()) >= 0;
+  return Boolean(el.isContentEditable);
+};
+
+const INTERACTIVE = "a[href],button,input,select,textarea,label,summary,[role=button],[role=link],[role=checkbox],[role=radio],[role=tab],[role=menuitem],[role=option],[role=switch]";
+const interactiveAt = (target) => {
+  const found = target.closest(INTERACTIVE) || target;
+  return found.tagName === "LABEL" && found.control ? found.control : found;
+};
+const TOOLBAR_TAG = "SAMURAI-RECORDER-TOOLBAR";
+const inToolbar = (event) =>
+  event.composedPath().some((node) => node && node.tagName === TOOLBAR_TAG);
+`;

package/dist/recorder/capture.d.ts

@@ -1,6 +1,9 @@
 /**
  * Function declaration installed as a preload script, called as `(send)` where `send` is the recorder's
- * channel. Reports what the tester does in the top-level document:
+ * channel. `send` stays in this closure and is never put on the page's window, so a page script cannot
+ * report anything. A second run in a document that was recorded before (a new recording) adds its own
+ * listeners; those of the earlier run go quiet, as their run is no longer the current one.
+ * Reports what the tester does in the top-level document:
  *
  * - `{ type: "click", target, candidates, textEntry }`: a click, retargeted to the nearest interactive
  *   element (a label click reports its control; the click the browser forwards to the control is dropped).
@@ -18,3 +21,7 @@
 export declare const CAPTURE_SOURCE: string;
 /** Run in every loaded document to stop its capture script reporting and swallowing Alt+clicks */
 export declare const CAPTURE_OFF = "() => { window[Symbol.for(\"samurai.recorder.off\")] = true; }";
+/** Run in every loaded document to pause its capture script (the toolbar's Pause, and while it types a value) */
+export declare const CAPTURE_MUTE = "() => { window[Symbol.for(\"samurai.recorder.muted\")] = true; }";
+/** Run in every loaded document to resume what `CAPTURE_MUTE` paused */
+export declare const CAPTURE_UNMUTE = "() => { window[Symbol.for(\"samurai.recorder.muted\")] = false; }";