@itmetsam/samurai-framework 0.7.0 → 0.8.0

package/README.md

@@ -20,16 +20,32 @@ test("Visitor can sign in", async ({ page, env, secrets }) => {
 - **Semantic locators.** By role, label, text, test id, CSS or XPath, with ordered fallbacks.
 - **Environments and secrets.** One test file runs against `dev`, `staging` or `production`; secrets come from the environment or a `.env.<name>` file and are masked in logs and reports.
 - **Network control.** Mock, block or modify requests; wait for requests, responses and network idle; read response bodies.
+- **Flows.** Chain tests and groups into a graph with conditions, variables, waits and HTTP requests, and run it from the command line or CI (see [Flows](docs/flows.md)).
 - **Recorder building blocks.** Specs are parsed into steps and edited back with minimal diffs, and an engine records what a person does in the browser. A toolbar in the recorded page adds assertions, variables and secrets, waits, screenshots and pause (see [Steps and the recorder](docs/recorder.md)). The Electron app that ties them together lives in a separate repository (see the [roadmap](docs/roadmap.md)).
 
 > **Status:** early. Firefox only. See [what is still open](docs/roadmap.md).
 
 ## Getting started
 
+### In your own project
+
+The package is published on npm as [`@itmetsam/samurai-framework`](https://www.npmjs.com/package/@itmetsam/samurai-framework). In an empty folder:
+
+```sh
+npx -p @itmetsam/samurai-framework samurai init   # config, an example test, .env.example, .gitignore
+npm install
+npx samurai browsers install firefox             # once per machine
+npx samurai run
+```
+
+Specs and the config then import from `@itmetsam/samurai-framework` instead of the relative paths used below. See [Command line](docs/cli.md).
+
+The rest of this section works in a checkout of this repository.
+
 ### 1. Requirements
 
-- [Node.js](https://nodejs.org) 26 or newer and [Bun](https://bun.sh) 1.3 or newer (CI uses these versions)
-- Firefox, downloaded by the framework: run `npx samurai browsers install firefox` once in a project (`bun run dev browsers install firefox` in this checkout; see [Which browser runs](docs/pages-and-browsers.md#which-browser-runs)). The Firefox installed on the machine is not used.
+- [Node.js](https://nodejs.org) 24 or newer (`engines` in `package.json`; CI uses 26) and, to work on the framework, [Bun](https://bun.sh) 1.3 or newer
+- Firefox, downloaded by the framework: run `bun run dev browsers install firefox` once in this checkout (`npx samurai browsers install firefox` in a project; see [Which browser runs](docs/pages-and-browsers.md#which-browser-runs)). The Firefox installed on the machine is not used.
 
 ### 2. Install
 
@@ -86,9 +102,9 @@ bun run dev --env production   # another environment (or SAMURAI_ENV=production)
 bun run dev --timeout 60000    # per-test timeout in ms; also --expect-timeout
 ```
 
-Once the package is installed in a project, `samurai run` does the same with a readable summary and a proper exit code, and `samurai init` scaffolds a new project (see [Command line](docs/cli.md)).
+`bun run dev` is `samurai run` straight from the sources, so it takes the same options (`--grep`, `--file`, `--group`, `--headless`, `--json`, …) and the other commands too (`bun run dev list`, `bun run dev browsers install firefox`). See [Command line](docs/cli.md).
 
-A browser window opens for each test and closes when the test ends. The result is written to `result/report.json` (status, duration and error per test); nothing summarises it on the console yet. The process exits with code 0 when every test passed and 1 otherwise (`--headless` hides the window; on CI it is the default, see [Configuration](docs/configuration.md#headless)). Framework logs go to the console and `logs/`.
+A browser window opens for each test and closes when the test ends (`--headless` hides it; on CI it is the default, see [Configuration](docs/configuration.md#headless)). Each test's result is printed as it finishes, followed by a summary, and the full report is written to `result/report.json`. The process exits with code 0 when every test passed, 1 otherwise and 2 for a usage or configuration error. Framework logs go to stderr and `logs/`.
 
 > `src/tests/index.spec.ts` is an example that submits a real contact form. Delete it or replace it before running everything.
 
@@ -100,6 +116,7 @@ A project can also keep flows in `flows/*.flow.json` (edited in the Samurai app)
 
 ```sh
 cp .env.example .env.staging
+# then add a line per secret, e.g.
 # SAMURAI_SECRET_TEST_PASSWORD=...
 ```
 
@@ -118,19 +135,21 @@ Read it in a test as `secrets.TEST_PASSWORD`. Real environment variables win ove
 | [Environments and secrets](docs/environments-and-secrets.md) | Per-environment settings, variables, secrets and masking                                              |
 | [Command line](docs/cli.md)                                  | `samurai run`, `list`, `record` and `init`, options, output, exit codes, `--json`                     |
 | [Flows](docs/flows.md)                                       | `samurai flow list`, `check` and `run`: graphs of tests, groups and steps, reports, CI                |
+| [Writing a step](docs/steps.md)                              | `defineStep`: flow steps of your own, the built-in steps                                              |
 | [Running tests and reports](docs/running-and-reports.md)     | What a run does, `report.json`, page logs, timeouts                                                   |
 | [Steps and the recorder](docs/recorder.md)                   | The step codec, the recording engine and the recorder toolbar                                         |
 | [Embedding the framework](docs/embedding.md)                 | Using the package from another app (such as the Electron UI): build, entry points, `runTests`, events |
 | [Contributing](docs/contributing.md)                         | Project layout, running the framework's own tests, conventions                                        |
 | [Roadmap](docs/roadmap.md)                                   | What is built and what is still open                                                                  |
 
-Design notes for every feature live in [`docs/superpowers/specs`](docs/superpowers/specs).
+The [documentation index](docs/README.md) lists every guide and design note by topic. Design notes for every feature live in [`docs/superpowers/specs`](docs/superpowers/specs).
 
 ## Scripts
 
 | Command                | Does                                            |
 | ---------------------- | ----------------------------------------------- |
-| `bun run dev`          | Runs the test suite (`tsx src/index.ts`)        |
+| `bun run dev`          | `samurai` from the sources (`tsx src/index.ts`) |
 | `bun run test`         | Unit tests of the framework (no browser needed) |
 | `bun run test:browser` | Browser tests of the framework (needs Firefox)  |
+| `bun run test:cli`     | Tests of the `samurai` command (build first)    |
 | `bun run build`        | Typechecks and compiles to `dist/`              |

package/dist/api.d.ts

@@ -3,3 +3,4 @@ export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
 export { defineStep, type StepDefinition, type StepResult, type StepRunInput, } from "./flows/steps/index.js";
 export type { TestFixtures } from "./types/test.js";
+export { generatedFile, type GeneratedFile, type FileInput, } from "./browser/generated-files.js";

package/dist/api.js

@@ -2,3 +2,4 @@ export { test, describe } from "./runner/registry.js";
 export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
 export { defineStep, } from "./flows/steps/index.js";
+export { generatedFile, } from "./browser/generated-files.js";

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

@@ -1,6 +1,7 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
 import type { FileDialogInfo } from "../types/bidi-modules/input.js";
 import type { ContextTree } from "./context-tree.js";
+import { type FileInput } from "./generated-files.js";
 /**
  * A native file picker the page asked for (a click on an `<input type=file>` or its label). Nothing appears on screen:
  * answer it with `setFiles()`.
@@ -12,10 +13,10 @@ export declare class FileChooser {
     /** Whether the input lets the user pick several files */
     isMultiple(): boolean;
     /**
-     * Picks the files (an empty list picks none). Paths resolve against the working directory and must exist on the
-     * machine the browser runs on.
+     * Picks the files (an empty list picks none). Relative paths resolve against the project folder and must exist on
+     * the machine the browser runs on; `generatedFile(…)` is accepted too.
      */
-    setFiles(files: string | string[]): Promise<void>;
+    setFiles(files: FileInput | FileInput[]): Promise<void>;
 }
 interface EventMap {
     filechooser: [FileChooser];

package/dist/browser/file-chooser.js

@@ -1,6 +1,6 @@
 import EventEmitter from "node:events";
 import logger from "../logger/index.js";
-import { assertIsFile, resolveFiles } from "./file-paths.js";
+import { resolveFileInputs } from "./generated-files.js";
 /**
  * A native file picker the page asked for (a click on an `<input type=file>` or its label). Nothing appears on screen:
  * answer it with `setFiles()`.
@@ -15,16 +15,15 @@ export class FileChooser {
         return this.info.multiple;
     }
     /**
-     * Picks the files (an empty list picks none). Paths resolve against the working directory and must exist on the
-     * machine the browser runs on.
+     * Picks the files (an empty list picks none). Relative paths resolve against the project folder and must exist on
+     * the machine the browser runs on; `generatedFile(…)` is accepted too.
      */
     async setFiles(files) {
-        const sharedId = this.info.element?.sharedId;
+        const sharedId = this.info.element
+            ?.sharedId;
         if (!sharedId)
             throw new Error("file chooser has no element reference");
-        const paths = resolveFiles(files);
-        for (const file of paths)
-            await assertIsFile(file, "setFiles");
+        const paths = await resolveFileInputs(files, "setFiles");
         if (paths.length > 1 && !this.info.multiple) {
             throw new Error("file chooser does not accept multiple files");
         }
@@ -61,7 +60,9 @@ export class FileChooserTracker {
         const tracker = new FileChooserTracker(connector, tree, contextId);
         connector.onEvent("input.fileDialogOpened", tracker.onOpened);
         try {
-            tracker.subscription = await connector.subscribe(["input.fileDialogOpened"]);
+            tracker.subscription = await connector.subscribe([
+                "input.fileDialogOpened",
+            ]);
         }
         catch (err) {
             connector.offEvent("input.fileDialogOpened", tracker.onOpened);

package/dist/browser/generated-files.d.ts

@@ -0,0 +1,30 @@
+declare const GENERATED: unique symbol;
+/** A file `setInputFiles` and `dropFiles` write when the step runs, instead of one stored in the project */
+export interface GeneratedFile {
+    readonly [GENERATED]: true;
+    readonly name: string;
+    /** Bytes */
+    readonly size: number;
+    readonly type?: string;
+}
+/** What `setInputFiles` and `dropFiles` take: a path (relative to the project folder) or a generated file */
+export type FileInput = string | GeneratedFile;
+/**
+ * A file of `size` written when the step runs: seeded random bytes, the same in every run and not
+ * compressible, under `result/files/`, removed when the run ends. For upload limits and load tests.
+ * `size` is bytes or a text with a unit (`"60 MB"`, `"1.5 GB"`; powers of 1024). `type` is the MIME type
+ * `dropFiles` gives the page; for `setInputFiles` the browser takes it from the name's extension.
+ * @example
+ *  await page.getByLabel("Upload").setInputFiles(generatedFile({ name: "huge.pdf", size: "60 MB" }));
+ */
+export declare function generatedFile(options: {
+    name: string;
+    size: number | string;
+    type?: string;
+}): GeneratedFile;
+export declare const isGeneratedFile: (value: unknown) => value is GeneratedFile;
+/** Removes this run's generated files (`withProject` calls it when the run ends) */
+export declare function removeGeneratedFiles(): Promise<void>;
+/** Absolute paths for `setInputFiles` / `dropFiles`: generated files are written, project files must exist */
+export declare function resolveFileInputs(files: FileInput | FileInput[], operation: string): Promise<string[]>;
+export {};

package/dist/browser/generated-files.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { projectDir } from "../config/config.js";
+import { parseSize } from "../steps/files.js";
+const GENERATED = Symbol.for("samurai.generatedFile");
+const CHUNK = 1024 * 1024;
+/**
+ * A file of `size` written when the step runs: seeded random bytes, the same in every run and not
+ * compressible, under `result/files/`, removed when the run ends. For upload limits and load tests.
+ * `size` is bytes or a text with a unit (`"60 MB"`, `"1.5 GB"`; powers of 1024). `type` is the MIME type
+ * `dropFiles` gives the page; for `setInputFiles` the browser takes it from the name's extension.
+ * @example
+ *  await page.getByLabel("Upload").setInputFiles(generatedFile({ name: "huge.pdf", size: "60 MB" }));
+ */
+export function generatedFile(options) {
+    const size = parseSize(options.size);
+    if (size === undefined)
+        throw new Error(`generatedFile(): size must be a number of bytes or a text like "60 MB", got ${JSON.stringify(options.size)}`);
+    const name = path.basename(String(options.name ?? ""));
+    if (name === "" || name === "." || name === "..")
+        throw new Error(`generatedFile(): name must be a file name, got ${JSON.stringify(options.name)}`);
+    return Object.freeze({
+        [GENERATED]: true,
+        name,
+        size,
+        ...(options.type !== undefined && { type: options.type }),
+    });
+}
+export const isGeneratedFile = (value) => typeof value === "object" &&
+    value !== null &&
+    value[GENERATED] === true;
+let folder;
+const written = new Map();
+/** xorshift32, seeded from the name and size */
+function seedOf(file) {
+    const seed = createHash("sha256")
+        .update(`${file.size}:${file.name}`)
+        .digest()
+        .readUInt32LE(0);
+    return seed === 0 ? 1 : seed;
+}
+async function write(target, size, seed) {
+    const handle = await open(target, "w");
+    try {
+        const chunk = Buffer.alloc(CHUNK);
+        let state = seed;
+        for (let done = 0; done < size; done += CHUNK) {
+            for (let i = 0; i < CHUNK; i += 4) {
+                state ^= state << 13;
+                state ^= state >>> 17;
+                state ^= state << 5;
+                state >>>= 0;
+                chunk.writeUInt32LE(state, i);
+            }
+            await handle.write(chunk, 0, Math.min(CHUNK, size - done));
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** The generated file on disk; written once per run for the same name and size */
+function generatedPath(file) {
+    folder ??= path.join(projectDir(), "result", "files");
+    const key = `${file.size}/${file.name}`;
+    let pending = written.get(key);
+    if (!pending) {
+        const dir = folder;
+        pending = (async () => {
+            const target = path.join(dir, key);
+            await mkdir(path.dirname(target), { recursive: true });
+            await write(target, file.size, seedOf(file));
+            return target;
+        })();
+        written.set(key, pending);
+        pending.catch(() => written.delete(key));
+    }
+    return pending;
+}
+/** Removes this run's generated files (`withProject` calls it when the run ends) */
+export async function removeGeneratedFiles() {
+    const dir = folder;
+    folder = undefined;
+    const pending = [...written.values()];
+    written.clear();
+    await Promise.allSettled(pending);
+    if (dir)
+        await rm(dir, { recursive: true, force: true });
+}
+/** Absolute paths for `setInputFiles` / `dropFiles`: generated files are written, project files must exist */
+export async function resolveFileInputs(files, operation) {
+    const paths = [];
+    for (const file of Array.isArray(files) ? files : [files]) {
+        if (isGeneratedFile(file)) {
+            paths.push(await generatedPath(file));
+            continue;
+        }
+        if (typeof file !== "string")
+            throw new TypeError(`${operation}(): expected a path or generatedFile(…), got ${typeof file}`);
+        const absolute = path.resolve(projectDir(), file);
+        let info;
+        try {
+            info = await stat(absolute);
+        }
+        catch {
+            throw new Error(path.isAbsolute(file)
+                ? `${operation}(): file not found: ${absolute}`
+                : `${operation}(): ${file.replace(/\\/g, "/")} doesn't exist in the project`);
+        }
+        if (!info.isFile())
+            throw new Error(`${operation}(): not a file: ${absolute}`);
+        paths.push(absolute);
+    }
+    return paths;
+}

package/dist/browser/page.d.ts

@@ -46,6 +46,16 @@ interface PageEvents extends NetworkEvents {
     pageerror: [PageError];
 }
 export type PageEventName = keyof PageEvents;
+/** Events `page.waitForEvent` can wait for */
+export type WaitableEventName = "download" | "filechooser" | "request" | "response";
+export interface WaitForEventOptions<T> {
+    /** Only an event this accepts counts */
+    predicate?: (item: T) => boolean;
+    /** Time (ms) to wait. @default config `navigation.timeout`, then 30000 */
+    timeout?: number;
+    /** Runs once the wait is set up; what it causes cannot be missed */
+    trigger?: () => Promise<unknown>;
+}
 export default class Page {
     private biDiConnector;
     private id;
@@ -297,6 +307,15 @@ export default class Page {
         timeout?: number;
         trigger?: () => Promise<unknown>;
     }): Promise<FileChooser>;
+    /**
+     * Playwright-style wait for one page event: `download`, `filechooser`, `request` or `response`. Same as the named
+     * `waitFor…` method, with an optional predicate (a function, or `predicate` in the options). Call it before the event
+     * is caused, or pass `trigger`, which runs once the wait is set up.
+     * @example
+     *  const chooser = await page.waitForEvent("filechooser", { trigger: () => page.getByText("Upload file").click() });
+     *  await chooser.setFiles("./myfile.pdf");
+     */
+    waitForEvent<E extends WaitableEventName>(event: E, optionsOrPredicate?: ((item: PageEvents[E][0]) => boolean) | WaitForEventOptions<PageEvents[E][0]>): Promise<PageEvents[E][0]>;
     /**
      * Starts keeping response bodies, which is what makes `response.body()` possible: the browser only keeps a body
      * when this ran before the request started. `page.on("response")` and `waitForResponse` call it; config

package/dist/browser/page.js

@@ -784,6 +784,36 @@ export default class Page {
         await this.startFileChooserTracking();
         return this.waitForPageEvent("filechooser", () => true, options, (timeout) => new FileChooserTimeoutError(timeout));
     }
+    /**
+     * Playwright-style wait for one page event: `download`, `filechooser`, `request` or `response`. Same as the named
+     * `waitFor…` method, with an optional predicate (a function, or `predicate` in the options). Call it before the event
+     * is caused, or pass `trigger`, which runs once the wait is set up.
+     * @example
+     *  const chooser = await page.waitForEvent("filechooser", { trigger: () => page.getByText("Upload file").click() });
+     *  await chooser.setFiles("./myfile.pdf");
+     */
+    async waitForEvent(event, optionsOrPredicate = {}) {
+        const { predicate, ...options } = typeof optionsOrPredicate === "function"
+            ? { predicate: optionsOrPredicate }
+            : optionsOrPredicate;
+        const accepts = (predicate ?? (() => true));
+        switch (event) {
+            case "request":
+                return this.waitForRequest(accepts, options);
+            case "response":
+                return this.waitForResponse(accepts, options);
+            case "download":
+                this.assertOpen();
+                await this.startDownloadTracking();
+                return this.waitForPageEvent("download", accepts, options, (timeout) => new DownloadWaitTimeoutError(timeout));
+            case "filechooser":
+                this.assertOpen();
+                await this.startFileChooserTracking();
+                return this.waitForPageEvent("filechooser", accepts, options, (timeout) => new FileChooserTimeoutError(timeout));
+            default:
+                throw new Error(`page.waitForEvent() does not support "${String(event)}": use page.on()`);
+        }
+    }
     /**
      * Starts keeping response bodies, which is what makes `response.body()` possible: the browser only keeps a body
      * when this ran before the request started. `page.on("response")` and `waitForResponse` call it; config

package/dist/cli/main.d.ts

@@ -1,4 +1,4 @@
-export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n  samurai flow <command>      List, check and run the flows in ./flows (see below)\n  samurai browsers [command]  List, install and remove the browsers SAMURAI launches\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --group <name>              Only the tests of this group of the config's groups\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one.\n                              Default: the config's use.headless, else headless when CI is set\n  --port <n>                  Browser debugging port (default 9223)\n\nOptions for record (also --env, --port, --json):\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.\n\nsamurai flow:\n  list                        The flows in ./flows\n  check [<flow>...]           Check flows without running them\n  run <flow>... | --all       Run flows; each writes result/flows/<id>.json\n  Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported\n  Run `samurai flow` alone for the details.\n\nsamurai browsers:\n  list                        The pinned browsers and every build in the cache (the default)\n  install [firefox|chrome|all]\n                              Download the pinned builds (default: all)\n  uninstall <name> [--build <id>] | --unused\n\nRun it in the project folder, the one holding samurai.config.ts.\n";
+export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n  samurai flow <command>      List, check and run the flows in ./flows (see below)\n  samurai browsers [command]  List, install and remove the browsers SAMURAI launches\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --group <name>              Only the tests of this group of the config's groups\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one.\n                              Default: the config's use.headless, else headless when CI is set\n  --port <n>                  Browser debugging port (default 9223)\n\nOptions for record (also --env, --port, --json, --headless, --no-headless):\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.\n\nsamurai flow:\n  list                        The flows in ./flows\n  check [<flow>...]           Check flows without running them\n  run <flow>... | --all       Run flows; each writes result/flows/<id>.json\n  Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported\n  Run `samurai flow` alone for the details.\n\nsamurai browsers:\n  list                        The pinned browsers and every build in the cache (the default)\n  install [firefox|chrome|all]\n                              Download the pinned builds (default: all)\n  uninstall <name> [--build <id>] | --unused\n\nRun it in the project folder, the one holding samurai.config.ts.\n";
 export interface Io {
     out: (text: string) => void;
     err: (text: string) => void;

package/dist/cli/main.js

@@ -31,7 +31,7 @@ Options for run:
                               Default: the config's use.headless, else headless when CI is set
   --port <n>                  Browser debugging port (default 9223)
 
-Options for record (also --env, --port, --json):
+Options for record (also --env, --port, --json, --headless, --no-headless):
   --new <title>               Add a test with this title (creates the spec file if needed)
   --test <name|index>         Record into this test; not needed when the file has one
   --at <n>                    Insert from step n (default: after the last step)
@@ -114,6 +114,7 @@ export async function main(argv, io) {
                 ...(values.new !== undefined && { create: values.new }),
                 ...(at !== undefined && { at }),
                 ...(values.url !== undefined && { url: values.url }),
+                ...(flags.headless !== undefined && { headless: flags.headless }),
                 ...(flags.port !== undefined && { port: flags.port }),
                 ...(io.signal && { signal: io.signal }),
                 onStarted: () => {
@@ -132,22 +133,36 @@ export async function main(argv, io) {
                         io.out(state === "paused" ? "Paused\n" : "Recording\n");
                     }
                 },
+                onMissingFile: (_file, text) => {
+                    if (!values.json)
+                        io.out(`${text}\n`);
+                },
                 onEvent: (event) => {
                     if (values.json)
                         return void io.out(`${JSON.stringify(event)}\n`);
-                    if (event.op === "insert")
-                        io.out(`  + ${stepToSource(event.step)}\n`);
-                    else
-                        io.out(`  ~ ${stepToSource(event.step)}\n`);
+                    if (event.op === "remove") {
+                        count--;
+                        return void io.out(`  - step ${event.index + 1} (the click that opened the file picker)\n`);
+                    }
+                    io.out(`  ${event.op === "insert" ? "+" : "~"} ${stepToSource(event.step)}\n`);
                     if (event.op === "insert")
                         count++;
                 },
             });
             if (!values.json) {
                 io.out(`\nRecorded ${count} ${count === 1 ? "step" : "steps"} into "${result.test}" in ${result.file}\n`);
-                if (result.secrets.length > 0) {
-                    io.out(`Set ${result.secrets.map((name) => `SAMURAI_SECRET_${name}`).join(", ")} (environment variable or .env.<environment>) before running it.\n`);
+                if (result.unsetSecrets.length > 0) {
+                    io.out(`Set ${result.unsetSecrets.map((name) => `SAMURAI_SECRET_${name}`).join(", ")} (environment variable or .env.<environment>) before running it.\n`);
+                }
+                if (result.missingFiles.length > 0) {
+                    io.out(`Add ${result.missingFiles.map((f) => f.path).join(", ")} before running it (or use generatedFile).\n`);
                 }
+                const hasFiles = result.files.length + result.missingFiles.length > 0;
+                const folder = result.filesFolder === "" ? "." : result.filesFolder;
+                if (hasFiles && result.filesIgnored)
+                    io.out(`${folder}/ is ignored by git; CI won't have these files.\n`);
+                if (hasFiles && result.firstFiles)
+                    io.out(`Recorded files are stored in ${folder}/ and committed with your tests.\n`);
             }
             return 0;
         }

package/dist/locator/locator.d.ts

@@ -3,6 +3,7 @@ import type { BrowsingContext, ElementRectangle } from "../types/bidi-modules/br
 import { type HelperInstaller } from "../script/helpers.js";
 import { ElementHandle } from "../script/element-handle.js";
 import { type ElementScreenshotOptions } from "../browser/screenshot.js";
+import { type FileInput } from "../browser/generated-files.js";
 import { type WaitForState } from "./element-state.js";
 import { type Selector, type TextOptions } from "./selector.js";
 export type { WaitForState } from "./element-state.js";
@@ -116,14 +117,25 @@ export default class Locator {
      */
     clickRect(rect: Pick<ElementRectangle, "x" | "y" | "width" | "height">): Promise<void>;
     /**
-     * Sets the files of an `<input type=file>` (an empty list clears them); the browser fires `input` and `change`.
-     * Paths are resolved against the working directory and must exist on the machine the browser runs on.
+     * Sets the files of an `<input type=file>`; `[]` clears it. Paths are relative to the project folder (absolute
+     * ones are used as they are); `generatedFile(…)` writes a file of a given size when the step runs.
      * Waits for the input to be attached and enabled; it need not be visible, file inputs are often hidden behind a label.
      * @example
-     *  await page.locator("input[@type='file']").setInputFiles("./fixtures/avatar.png");
-     *  await page.locator("input[@type='file']").setInputFiles([]);
+     *  await page.getByLabel("Avatar").setInputFiles("files/avatar.png");
+     *  await page.getByLabel("Upload").setInputFiles(generatedFile({ name: "huge.pdf", size: "60 MB" }));
      */
-    setInputFiles(files: string | string[], options?: {
+    setInputFiles(files: FileInput | FileInput[], options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Drops files on the element, as dragging them from the desktop does: `dragenter`, `dragover` and `drop`
+     * with a `DataTransfer` holding the files. Takes what `setInputFiles` takes. The events are synthetic
+     * (`isTrusted` is false); a page that only accepts trusted drops ignores them.
+     * Waits for the element to be attached and visible.
+     * @example
+     *  await page.getByTestId("dropzone").dropFiles(["files/a.png", "files/b.png"]);
+     */
+    dropFiles(files: FileInput | FileInput[], options?: {
         timeout?: number;
     }): Promise<void>;
     /**

package/dist/locator/locator.js

@@ -3,7 +3,7 @@ import { callFunction, ScriptError } from "../script/call-function.js";
 import { CALL_PROBE, HELPER_SANDBOX, HELPERS_MISSING, } from "../script/helpers.js";
 import { ElementHandle } from "../script/element-handle.js";
 import { takeScreenshot, } from "../browser/screenshot.js";
-import { assertIsFile, resolveFiles } from "../browser/file-paths.js";
+import { isGeneratedFile, resolveFileInputs, } from "../browser/generated-files.js";
 import { resolveTimeout, waitUntil, WaitTimeoutError, } from "../wait/wait-until.js";
 import { ActionTimeoutError } from "./action-timeout-error.js";
 import { allPass, DETACHED_STATE, evaluateChecks, parseElementState, PROBE_ELEMENT, } from "./element-state.js";
@@ -27,6 +27,31 @@ const FILE_INPUT_INFO = `(el) => ({
   multiple: Boolean(el.multiple),
 })`;
 const FILE_INPUT_CHECKS = ["attached", "enabled"];
+const DROP_CHECKS = ["attached", "visible"];
+/** The sandbox `dropFiles` builds its files in */
+const DROP_SANDBOX = "samurai-drop";
+const DROP_KEY = `globalThis[Symbol.for("samurai.drop")]`;
+const DROP_INPUT = `() => {
+  const input = document.createElement("input");
+  input.type = "file";
+  input.multiple = true;
+  ${DROP_KEY} = input;
+  return input;
+}`;
+/** Fires dragenter, dragover and drop at the element's centre with the input's files (retyped where asked) */
+const DROP_EVENTS = `(el, types) => {
+  const input = ${DROP_KEY};
+  delete ${DROP_KEY};
+  const data = new DataTransfer();
+  Array.from(input.files).forEach((file, i) => {
+    data.items.add(types[i] ? new File([file], file.name, { type: types[i], lastModified: file.lastModified }) : file);
+  });
+  const box = el.getBoundingClientRect();
+  const at = { clientX: box.left + box.width / 2, clientY: box.top + box.height / 2 };
+  for (const type of ["dragenter", "dragover", "drop"]) {
+    el.dispatchEvent(new DragEvent(type, Object.assign({ bubbles: true, cancelable: true, composed: true, dataTransfer: data }, at)));
+  }
+}`;
 const SCREENSHOT_CHECKS = ["attached", "visible"];
 const CLICK_CHECKS = [
     "attached",
@@ -410,17 +435,15 @@ export default class Locator {
         });
     }
     /**
-     * Sets the files of an `<input type=file>` (an empty list clears them); the browser fires `input` and `change`.
-     * Paths are resolved against the working directory and must exist on the machine the browser runs on.
+     * Sets the files of an `<input type=file>`; `[]` clears it. Paths are relative to the project folder (absolute
+     * ones are used as they are); `generatedFile(…)` writes a file of a given size when the step runs.
      * Waits for the input to be attached and enabled; it need not be visible, file inputs are often hidden behind a label.
      * @example
-     *  await page.locator("input[@type='file']").setInputFiles("./fixtures/avatar.png");
-     *  await page.locator("input[@type='file']").setInputFiles([]);
+     *  await page.getByLabel("Avatar").setInputFiles("files/avatar.png");
+     *  await page.getByLabel("Upload").setInputFiles(generatedFile({ name: "huge.pdf", size: "60 MB" }));
      */
     async setInputFiles(files, options) {
-        const paths = resolveFiles(files);
-        for (const file of paths)
-            await assertIsFile(file, "setInputFiles");
+        const paths = await resolveFileInputs(files, "setInputFiles");
         await this.waitForActionable("setInputFiles", FILE_INPUT_CHECKS, { scroll: false, hitTest: false }, options?.timeout === undefined ? undefined : { timeout: options.timeout });
         const missing = () => new Error(`Failed to locate element ${this.selector}. Details: no element matches`);
         const el = await this.resolveOne();
@@ -450,6 +473,31 @@ export default class Locator {
             files: paths,
         });
     }
+    /**
+     * Drops files on the element, as dragging them from the desktop does: `dragenter`, `dragover` and `drop`
+     * with a `DataTransfer` holding the files. Takes what `setInputFiles` takes. The events are synthetic
+     * (`isTrusted` is false); a page that only accepts trusted drops ignores them.
+     * Waits for the element to be attached and visible.
+     * @example
+     *  await page.getByTestId("dropzone").dropFiles(["files/a.png", "files/b.png"]);
+     */
+    async dropFiles(files, options) {
+        const list = Array.isArray(files) ? files : [files];
+        const paths = await resolveFileInputs(list, "dropFiles");
+        const types = list.map((file) => isGeneratedFile(file) ? (file.type ?? "") : "");
+        await this.waitForActionable("dropFiles", DROP_CHECKS, { scroll: true, hitTest: false }, options?.timeout === undefined ? undefined : { timeout: options.timeout });
+        const el = await this.resolveOne();
+        if (!el)
+            throw new Error(`Failed to locate element ${this.selector}. Details: no element matches`);
+        // A file input of our own, made in a sandbox and never attached: the page doesn't see it
+        const input = await this.call(DROP_INPUT, [], DROP_SANDBOX);
+        await this.biDiConnector.send("input.setFiles", {
+            context: this.contextId,
+            element: { sharedId: input.sharedId },
+            files: paths,
+        });
+        await this.call(DROP_EVENTS, [el, types], DROP_SANDBOX);
+    }
     /**
      * Takes a screenshot of just this element, after scrolling it into view and waiting until it is attached and
      * visible. Returns the image (also written to `options.path`).

package/dist/project/files-store.d.ts

@@ -0,0 +1,28 @@
+/** Files bigger than this aren't stored while recording */
+export declare const RECORD_LIMIT: number;
+/** A picked file's name as a file name in the files folder: no folders, control characters or leading dots */
+export declare function cleanFileName(name: string): string;
+/** The files folder: absolute, and relative to the project with forward slashes */
+export declare function filesFolder(projectDir: string, filesDir?: string): {
+    absolute: string;
+    relative: string;
+};
+/**
+ * Stores the bytes in `content` in the files folder under their own (cleaned) name, so the page sees at
+ * replay the name it saw while recording. If the name is free the file is copied there; if a file of that
+ * name holds the same content it is reused. If the name is taken by other content, the file goes in a
+ * folder named after the first 8 hex characters of its SHA-256 (`<H>/<name>`; 16, then all 64, on a
+ * collision). Different names with the same content are stored separately. Nothing is overwritten and
+ * nothing is written outside the folder. `content` is left in place. Returns the project-relative path.
+ */
+export declare function storeFile(options: {
+    projectDir: string;
+    filesDir?: string;
+    name: string;
+    content: string;
+}): Promise<{
+    path: string;
+    reused: boolean;
+}>;
+/** Whether the project's .gitignore ignores the folder (`files`, `files/`, `/files`, `files/*`, `files/**`) */
+export declare function isFolderIgnored(projectDir: string, relative: string): Promise<boolean>;