@itmetsam/samurai-framework 0.7.0 → 0.8.0

package/dist/steps/edit.d.ts

@@ -24,7 +24,8 @@ export type StepEdit = {
     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.
+ * Applies one edit and returns the new source. Only the touched statement changes, plus the test's parameters
+ * when the step reads a fixture (`env`, `secrets`) they don't have yet: everything else, formatting and
+ * comments included, stays byte for byte.
  */
 export declare function applyEdit(source: string, edit: StepEdit): string;

package/dist/steps/edit.js

@@ -1,3 +1,4 @@
+import ts from "typescript";
 import { stepToSource } from "./emit.js";
 import { parseSpec } from "./parse.js";
 const lineStart = (source, offset) => source.lastIndexOf("\n", offset - 1) + 1;
@@ -51,19 +52,77 @@ function removeStep(source, parsed, index) {
     const { anchor, end } = pickStep(parsed, index);
     return splice(source, lineStart(source, anchor), lineEnd(source, end), "");
 }
+/** The fixtures a step's statement reads */
+function fixturesOf(step) {
+    if (step.kind !== "fill" || step.value.kind === "literal")
+        return [];
+    return [step.value.kind === "env" ? "env" : "secrets"];
+}
+/** Adds the fixtures the step reads to the test's parameters, when they aren't there yet */
+function withFixtures(source, parsed, step) {
+    const { fixtures } = parsed;
+    if (!fixtures)
+        return source;
+    const missing = fixturesOf(step).filter((name) => !fixtures.names.includes(name));
+    if (missing.length === 0)
+        return source;
+    const list = missing.join(", ");
+    const text = fixtures.shape === "list"
+        ? `, ${list}`
+        : fixtures.shape === "empty"
+            ? ` ${list} `
+            : `{ ${list} }`;
+    return splice(source, fixtures.at, fixtures.at, text);
+}
+const usesGeneratedFile = (step) => (step.kind === "setInputFiles" || step.kind === "dropFiles") &&
+    step.files.some((file) => "generate" in file);
+const FRAMEWORK = "@itmetsam/samurai-framework";
+/** Adds `generatedFile` to the framework import (or a new one) unless the file already imports it under its own name */
+function withGeneratedFileImport(source) {
+    const file = ts.createSourceFile("spec.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    let frameworkImport;
+    for (const statement of file.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        if (!ts.isStringLiteral(statement.moduleSpecifier) ||
+            statement.moduleSpecifier.text !== FRAMEWORK)
+            continue;
+        const named = statement.importClause?.namedBindings;
+        if (!named || !ts.isNamedImports(named))
+            continue;
+        if (named.elements.some((e) => e.name.text === "generatedFile" &&
+            (!e.propertyName || e.propertyName.text === e.name.text)))
+            return source;
+        frameworkImport ??= named;
+    }
+    if (!frameworkImport || frameworkImport.elements.length === 0)
+        return `import { generatedFile } from "${FRAMEWORK}";\n${source}`;
+    const last = frameworkImport.elements[frameworkImport.elements.length - 1];
+    return splice(source, last.end, last.end, ", generatedFile");
+}
 /**
- * Applies one edit and returns the new source. Only the touched statement changes: everything else,
- * formatting and comments included, stays byte for byte.
+ * Applies one edit and returns the new source. Only the touched statement changes, plus the test's parameters
+ * when the step reads a fixture (`env`, `secrets`) they don't have yet: 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));
+            // The parameters come before the body: adding to them leaves the step's offsets valid
+            const next = withFixtures(splice(source, start, end, stepToSource(edit.step)), parsed, edit.step);
+            // Last: the import shifts every offset
+            return usesGeneratedFile(edit.step)
+                ? withGeneratedFileImport(next)
+                : next;
+        }
+        case "insert": {
+            const next = withFixtures(insertCode(source, parsed, edit.index, stepToSource(edit.step)), parsed, edit.step);
+            return usesGeneratedFile(edit.step)
+                ? withGeneratedFileImport(next)
+                : next;
         }
-        case "insert":
-            return insertCode(source, parsed, edit.index, stepToSource(edit.step));
         case "remove":
             return removeStep(source, parsed, edit.index);
         case "move": {

package/dist/steps/emit.d.ts

@@ -1,4 +1,6 @@
-import type { LocatorCall, LocatorSpec, Step, TextValue } from "./model.js";
+import type { FileEntry, LocatorCall, LocatorSpec, Step, TextValue } from "./model.js";
+/** The argument of `setInputFiles` / `dropFiles`: one entry bare, else an array */
+export declare function filesToSource(files: readonly FileEntry[]): string;
 export declare function callToSource(call: LocatorCall): string;
 export declare function locatorToSource({ chain, fallbacks }: LocatorSpec): string;
 export declare function valueToSource(value: TextValue): string;

package/dist/steps/emit.js

@@ -1,4 +1,20 @@
+import { formatSize, sizeFromSource } from "./files.js";
 const str = (value) => JSON.stringify(value);
+function fileEntryToSource(entry) {
+    if ("path" in entry)
+        return str(entry.path);
+    const { name, size, type, sizeSource } = entry.generate;
+    const sizeText = sizeSource !== undefined && sizeFromSource(sizeSource) === size
+        ? sizeSource
+        : str(formatSize(size));
+    return `generatedFile({ name: ${str(name)}, size: ${sizeText}${type === undefined ? "" : `, type: ${str(type)}`} })`;
+}
+/** The argument of `setInputFiles` / `dropFiles`: one entry bare, else an array */
+export function filesToSource(files) {
+    return files.length === 1
+        ? fileEntryToSource(files[0])
+        : `[${files.map(fileEntryToSource).join(", ")}]`;
+}
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 function textOptions(call) {
     const parts = [
@@ -73,6 +89,9 @@ export function stepToSource(step) {
             return `await page.waitForTimeout(${step.ms});`;
         case "screenshot":
             return `await page.screenshot({ name: ${str(step.name)}${step.fullPage ? ", fullPage: true" : ""} });`;
+        case "setInputFiles":
+        case "dropFiles":
+            return `await ${locatorToSource(step.locator)}.${step.kind}(${filesToSource(step.files)});`;
         case "custom":
             return step.code;
     }

package/dist/steps/files.d.ts

@@ -0,0 +1,8 @@
+/** Bytes for a size: a whole number of bytes, or a text like "60 MB", "1.5 GB", "512 KB" (powers of 1024) */
+export declare function parseSize(size: number | string): number | undefined;
+/** A size in the largest unit that gives a whole number: 62914560 → "60 MB", 1536 → "1536 B" */
+export declare function formatSize(bytes: number): string;
+/** A size for people: the largest unit it reaches, one decimal at most ("300 MB", "1.3 GB") */
+export declare function humanSize(bytes: number): string;
+/** The bytes a size's source text means: a number literal, or a quoted size text */
+export declare function sizeFromSource(text: string): number | undefined;

package/dist/steps/files.js

@@ -0,0 +1,33 @@
+const UNITS = { B: 1, KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 };
+/** Bytes for a size: a whole number of bytes, or a text like "60 MB", "1.5 GB", "512 KB" (powers of 1024) */
+export function parseSize(size) {
+    if (typeof size === "number")
+        return Number.isInteger(size) && size >= 0 ? size : undefined;
+    const match = /^\s*(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)\s*$/i.exec(size);
+    if (!match)
+        return undefined;
+    return Math.round(Number(match[1]) * UNITS[match[2].toUpperCase()]);
+}
+/** A size in the largest unit that gives a whole number: 62914560 → "60 MB", 1536 → "1536 B" */
+export function formatSize(bytes) {
+    for (const unit of ["GB", "MB", "KB"]) {
+        if (bytes >= UNITS[unit] && bytes % UNITS[unit] === 0)
+            return `${bytes / UNITS[unit]} ${unit}`;
+    }
+    return `${bytes} B`;
+}
+/** A size for people: the largest unit it reaches, one decimal at most ("300 MB", "1.3 GB") */
+export function humanSize(bytes) {
+    for (const unit of ["GB", "MB", "KB"]) {
+        if (bytes >= UNITS[unit])
+            return `${Math.round((bytes / UNITS[unit]) * 10) / 10} ${unit}`;
+    }
+    return `${bytes} B`;
+}
+/** The bytes a size's source text means: a number literal, or a quoted size text */
+export function sizeFromSource(text) {
+    if (/^\d+$/.test(text))
+        return parseSize(Number(text));
+    const quoted = /^(["'`])(.*)\1$/s.exec(text);
+    return quoted ? parseSize(quoted[2]) : undefined;
+}

package/dist/steps/index.d.ts

@@ -1,5 +1,6 @@
 export { parseSpec } from "./parse.js";
 export { applyEdit, type StepEdit } from "./edit.js";
-export { stepToSource, locatorToSource, callToSource, valueToSource, } from "./emit.js";
+export { stepToSource, locatorToSource, callToSource, filesToSource, valueToSource, } from "./emit.js";
+export { formatSize, humanSize, parseSize, sizeFromSource } from "./files.js";
 export { locatorFromSpec } from "./build.js";
-export type { Expectation, LocatorCall, LocatorSpec, ParsedStep, ParsedTest, Step, TextMatcher, TextValue, } from "./model.js";
+export type { Expectation, FileEntry, GeneratedFileSpec, LocatorCall, LocatorSpec, ParsedStep, ParsedTest, Step, TextMatcher, TextValue, } from "./model.js";

package/dist/steps/index.js

@@ -1,4 +1,5 @@
 export { parseSpec } from "./parse.js";
 export { applyEdit } from "./edit.js";
-export { stepToSource, locatorToSource, callToSource, valueToSource, } from "./emit.js";
+export { stepToSource, locatorToSource, callToSource, filesToSource, valueToSource, } from "./emit.js";
+export { formatSize, humanSize, parseSize, sizeFromSource } from "./files.js";
 export { locatorFromSpec } from "./build.js";

package/dist/steps/model.d.ts

@@ -59,6 +59,22 @@ export type Expectation = {
     matcher: "toHaveCount";
     expected: number;
 };
+/** A file generated when the step runs: seeded random bytes of `size`, never stored in the project */
+export interface GeneratedFileSpec {
+    name: string;
+    /** Bytes */
+    size: number;
+    /** MIME type; `dropFiles` gives it to the page, `setInputFiles` gets it from the name's extension */
+    type?: string;
+    /** How the size is written in the source (`"60 MB"`, `1048576`); written back while it still means `size` */
+    sizeSource?: string;
+}
+/** A file a step sets or drops: one stored in the project (relative to the project folder), or a generated one */
+export type FileEntry = {
+    path: string;
+} | {
+    generate: GeneratedFileSpec;
+};
 /** The restricted set of statements the recorder writes. Anything else in a test is a `custom` step */
 export type Step = {
     kind: "goto";
@@ -95,6 +111,18 @@ export type Step = {
     name: string;
     fullPage: boolean;
 }
+/** Sets the files of an `<input type=file>`; no files clears it */
+ | {
+    kind: "setInputFiles";
+    locator: LocatorSpec;
+    files: FileEntry[];
+}
+/** Drops files on an element, as dragging them from the desktop does */
+ | {
+    kind: "dropFiles";
+    locator: LocatorSpec;
+    files: FileEntry[];
+}
 /** A statement the codec does not understand, kept verbatim */
  | {
     kind: "custom";
@@ -117,4 +145,14 @@ export interface ParsedTest {
     /** Offset just after the `{` of the test body, and of its closing `}` */
     bodyStart: number;
     bodyEnd: number;
+    /**
+     * The fixtures the test's callback destructures, and the offset where another one goes: after the last one
+     * (`list`), inside an empty `{}` (`empty`) or inside the empty `()` of a callback without parameters (`none`).
+     * Undefined when the parameter can't take one: a plain identifier, or a rest element
+     */
+    fixtures?: {
+        names: string[];
+        at: number;
+        shape: "list" | "empty" | "none";
+    };
 }

package/dist/steps/parse.js

@@ -1,4 +1,5 @@
 import ts from "typescript";
+import { parseSize } from "./files.js";
 const TEXT_MATCHERS = ["toHaveText", "toContainText", "toHaveValue"];
 function stringOf(node) {
     return node &&
@@ -174,6 +175,77 @@ function readExpectation(matcher, args) {
     }
     return undefined;
 }
+/** `"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 */
+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];
+}
 /** The step a statement stands for, or undefined when it is outside the recorder's set */
 function readStep(statement) {
     if (!ts.isExpressionStatement(statement) ||
@@ -241,6 +313,13 @@ function readStep(statement) {
         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;
 }
 function parseStatement(source, statement, sourceFile) {
@@ -257,6 +336,28 @@ function parseStatement(source, statement, sourceFile) {
         anchor: comments?.[0]?.pos ?? start,
     };
 }
+function callbackFixtures(callback, sourceFile) {
+    const [first] = callback.parameters;
+    if (!first) {
+        const open = callback
+            .getChildren(sourceFile)
+            .find((child) => child.kind === ts.SyntaxKind.OpenParenToken);
+        return open ? { names: [], at: open.end, shape: "none" } : undefined;
+    }
+    const pattern = first.name;
+    if (!ts.isObjectBindingPattern(pattern))
+        return undefined;
+    if (pattern.elements.some((element) => element.dotDotDotToken))
+        return undefined;
+    const last = pattern.elements[pattern.elements.length - 1];
+    if (!last)
+        return { names: [], at: pattern.getStart(sourceFile) + 1, shape: "empty" };
+    return {
+        names: pattern.elements.map(({ propertyName, name }) => (propertyName ?? name).getText(sourceFile)),
+        at: last.end,
+        shape: "list",
+    };
+}
 function callbackBody(node) {
     return node &&
         (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
@@ -280,6 +381,7 @@ export function parseSpec(source) {
                     steps: body.statements.map((statement) => parseStatement(source, statement, sourceFile)),
                     bodyStart: body.getStart(sourceFile) + 1,
                     bodyEnd: body.end - 1,
+                    fixtures: callbackFixtures(node.arguments[1], sourceFile),
                 });
                 return;
             }

package/dist/types/config.d.ts

@@ -45,8 +45,8 @@ export interface SamuraiTestConfig {
    */
   srcDir?: string;
   /**
-   * The browser to use for all tests.
-   * Is overwritten by the 'browser' in a group's config
+   * The browser to use for all tests. Only "firefox" can launch today
+   * @default "firefox"
    */
   browser?: SupportedBrowser;
   /**
@@ -96,6 +96,11 @@ export interface SamuraiTestConfig {
    * @default "result/downloads"
    */
   downloadsDir?: string;
+  /**
+   * Folder, relative to the project folder, where recorded uploads are stored and committed with the tests
+   * @default "files"
+   */
+  filesDir?: string;
   /** How pages are opened */
   use?: {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.7.0",
+  "version": "0.8.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": {

package/dist/browser/file-paths.d.ts

@@ -1,4 +0,0 @@
-/** Absolute paths for `files` (relative ones resolve against the working directory) */
-export declare function resolveFiles(files: string | string[]): string[];
-/** Throws unless `file` is an existing regular file; `operation` names the caller in the message */
-export declare function assertIsFile(file: string, operation: string): Promise<void>;

package/dist/browser/file-paths.js

@@ -1,18 +0,0 @@
-import { stat } from "node:fs/promises";
-import path from "node:path";
-/** Absolute paths for `files` (relative ones resolve against the working directory) */
-export function resolveFiles(files) {
-    return (Array.isArray(files) ? files : [files]).map((file) => path.resolve(file));
-}
-/** Throws unless `file` is an existing regular file; `operation` names the caller in the message */
-export async function assertIsFile(file, operation) {
-    let info;
-    try {
-        info = await stat(file);
-    }
-    catch {
-        throw new Error(`${operation}(): file not found: ${file}`);
-    }
-    if (!info.isFile())
-        throw new Error(`${operation}(): not a file: ${file}`);
-}