@itmetsam/samurai-framework 0.5.0 → 0.7.0

package/dist/browsers/resolve.js

@@ -0,0 +1,56 @@
+import { existsSync } from "node:fs";
+import { projectConfig, projectDir, readConfig } from "../config/config.js";
+import logger from "../logger/index.js";
+import { ENV_PATH, overrideOf } from "./overrides.js";
+import { MANAGED_BROWSERS, PINNED } from "./pins.js";
+import { managedBuildDir, managedExecutable, statusOf, } from "./store.js";
+/** The browser a launch uses: the env path, else the config's `browserPaths`, else the pinned build. Never downloads */
+export function resolveBrowser(name, sources = {}) {
+    const override = overrideOf(name, sources);
+    if (!override)
+        return {
+            executablePath: managedExecutable(name, sources),
+            label: PINNED[name].label,
+            buildDir: managedBuildDir(name, sources),
+        };
+    if (!existsSync(override.path))
+        throw new Error(override.from === "env"
+            ? `${ENV_PATH[name]} points to a missing file: ${override.path}`
+            : `browserPaths.${name} in samurai.config.ts points to a missing file: ${override.path}`);
+    return {
+        executablePath: override.path,
+        label: name.charAt(0).toUpperCase() + name.slice(1),
+    };
+}
+/** The binary a launch uses; see `resolveBrowser` */
+export function resolveExecutable(name, sources = {}) {
+    return resolveBrowser(name, sources).executablePath;
+}
+/** `resolveExecutable` for the active project */
+export async function projectExecutable(name) {
+    return (await projectBrowser(name)).executablePath;
+}
+/** `resolveBrowser` for the active project, with its config's `browserPaths` (none when the config can't be read) */
+export async function projectBrowser(name) {
+    let browserPaths;
+    try {
+        browserPaths = await readConfig("browserPaths");
+    }
+    catch (err) {
+        logger.debug("Could not read browserPaths from config", { err });
+    }
+    return resolveBrowser(name, { browserPaths, projectDir: projectDir() });
+}
+/** Every pinned browser's status for a project (default: the working directory); a config that can't be read gives no config overrides */
+export async function browserStatus(options = {}) {
+    const dir = options.projectDir ?? process.cwd();
+    let browserPaths;
+    try {
+        browserPaths = (await projectConfig({ ...options, projectDir: dir }))
+            .browserPaths;
+    }
+    catch (err) {
+        logger.debug("Could not read browserPaths from config", { err });
+    }
+    return MANAGED_BROWSERS.map((name) => statusOf(name, { ...options, browserPaths, projectDir: dir }));
+}

package/dist/browsers/store.d.ts

@@ -0,0 +1,52 @@
+import { COMPLETE_MARKER, type Downloader } from "./downloader.js";
+import { type Override, type OverrideSources } from "./overrides.js";
+import { type ManagedBrowser } from "./pins.js";
+export { COMPLETE_MARKER };
+export declare class BrowserNotInstalledError extends Error {
+    readonly browser: ManagedBrowser;
+    readonly label: string;
+    constructor(browser: ManagedBrowser, label: string);
+}
+export interface StoreOptions {
+    /** Default: `browsersCacheDir()` */
+    cacheDir?: string;
+    /** Default: @puppeteer/browsers */
+    downloader?: Downloader;
+}
+export interface BrowserStatus {
+    name: ManagedBrowser;
+    label: string;
+    buildId: string;
+    /** unavailable: no download exists for this OS and architecture */
+    state: "installed" | "missing" | "unavailable";
+    executablePath?: string;
+    /** Whether the framework can launch it yet */
+    launchable: boolean;
+    /** A path set on purpose, which launches use instead of the managed build */
+    override?: Override;
+}
+export interface InstalledBuild {
+    name: ManagedBrowser;
+    buildId: string;
+    dir: string;
+    sizeBytes: number;
+    /** Pinned by this framework version */
+    pinned: boolean;
+}
+/**
+ * Downloads the pinned build unless it is complete already; returns its executable. The download goes into a
+ * private staging folder and is moved into place once complete, so two installs at once do not break each other.
+ */
+export declare function installBrowser(name: ManagedBrowser, options?: StoreOptions & {
+    onProgress?: (done: number, total: number) => void;
+}): Promise<string>;
+/** The pinned build of `name`: whether it is there, and any path set instead of it */
+export declare function statusOf(name: ManagedBrowser, options?: StoreOptions & OverrideSources): BrowserStatus;
+/** The pinned build's executable; throws BrowserNotInstalledError when it isn't complete */
+export declare function managedExecutable(name: ManagedBrowser, options?: StoreOptions): string;
+/** The folder the pinned build of `name` is, or would be, installed in */
+export declare function managedBuildDir(name: ManagedBrowser, options?: StoreOptions): string;
+/** Removes a build (default: the pinned one); Chrome takes its chromedriver along */
+export declare function uninstallBrowser(name: ManagedBrowser, buildId?: string, options?: StoreOptions): void;
+/** Every Firefox and Chrome build in the cache, also those other framework versions pinned */
+export declare function listInstalled(options?: StoreOptions): InstalledBuild[];

package/dist/browsers/store.js

@@ -0,0 +1,170 @@
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { browsersCacheDir } from "./cache-dir.js";
+import { COMPLETE_MARKER, puppeteerDownloader, } from "./downloader.js";
+import { overrideOf, } from "./overrides.js";
+import { isManagedBrowser, LAUNCHABLE, PINNED, } from "./pins.js";
+export { COMPLETE_MARKER };
+/** Each install downloads into its own `<cache>/.staging-<random>/` and moves the finished build into place */
+const STAGING_PREFIX = ".staging-";
+/** A staging folder this old belongs to an install that was killed */
+const STALE_STAGING_MS = 24 * 60 * 60 * 1000;
+export class BrowserNotInstalledError extends Error {
+    constructor(browser, label) {
+        super(`${label} is not installed. Run: samurai browsers install ${browser}`);
+        this.browser = browser;
+        this.label = label;
+        this.name = "BrowserNotInstalledError";
+    }
+}
+const store = (options = {}) => ({
+    cacheDir: options.cacheDir ?? browsersCacheDir(),
+    downloader: options.downloader ?? puppeteerDownloader(),
+});
+/** The cache folders one managed browser consists of */
+const parts = (name) => name === "chrome" ? ["chrome", "chromedriver"] : [name];
+const complete = (dir) => existsSync(path.join(dir, COMPLETE_MARKER));
+function sizeOf(dir) {
+    let total = 0;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        total += entry.isDirectory() ? sizeOf(full) : lstatSync(full).size;
+    }
+    return total;
+}
+/** Removes staging folders that killed installs left behind; best effort */
+function removeStaleStaging(cacheDir) {
+    if (!existsSync(cacheDir))
+        return;
+    for (const entry of readdirSync(cacheDir)) {
+        if (!entry.startsWith(STAGING_PREFIX))
+            continue;
+        const dir = path.join(cacheDir, entry);
+        try {
+            if (Date.now() - statSync(dir).mtimeMs > STALE_STAGING_MS)
+                rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // another process may be removing it too
+        }
+    }
+}
+/**
+ * Downloads the pinned build unless it is complete already; returns its executable. The download goes into a
+ * private staging folder and is moved into place once complete, so two installs at once do not break each other.
+ */
+export async function installBrowser(name, options = {}) {
+    const { cacheDir, downloader } = store(options);
+    const pin = PINNED[name];
+    if (!downloader.platform())
+        throw new Error(`${pin.label} has no download for ${process.platform} ${process.arch}`);
+    const dir = downloader.installDir(cacheDir, name, pin.buildId);
+    const exe = () => downloader.executablePath(cacheDir, name, pin.buildId);
+    if (complete(dir))
+        return exe();
+    let staging;
+    try {
+        removeStaleStaging(cacheDir);
+        mkdirSync(cacheDir, { recursive: true });
+        staging = mkdtempSync(path.join(cacheDir, STAGING_PREFIX));
+        for (const part of parts(name))
+            await downloader.install(staging, part, pin.buildId, part === name ? options.onProgress : undefined);
+        writeFileSync(path.join(downloader.installDir(staging, name, pin.buildId), COMPLETE_MARKER), new Date().toISOString());
+        // The part holding the marker moves last, so the build counts as complete only once every part is in place
+        for (const part of parts(name).reverse()) {
+            // Another install finished first
+            if (complete(dir))
+                return exe();
+            // An unfinished folder from an earlier attempt would block the move
+            downloader.clean(cacheDir, part, pin.buildId);
+            const target = downloader.installDir(cacheDir, part, pin.buildId);
+            mkdirSync(path.dirname(target), { recursive: true });
+            try {
+                renameSync(downloader.installDir(staging, part, pin.buildId), target);
+            }
+            catch (e) {
+                if (complete(dir))
+                    return exe();
+                throw e;
+            }
+        }
+    }
+    catch (e) {
+        throw new Error(`Could not download ${pin.label}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    finally {
+        if (staging)
+            rmSync(staging, { recursive: true, force: true });
+    }
+    return exe();
+}
+/** The pinned build of `name`: whether it is there, and any path set instead of it */
+export function statusOf(name, options = {}) {
+    const { cacheDir, downloader } = store(options);
+    const pin = PINNED[name];
+    const override = overrideOf(name, options);
+    const base = {
+        name,
+        label: pin.label,
+        buildId: pin.buildId,
+        launchable: LAUNCHABLE.includes(name),
+        ...(override && { override }),
+    };
+    if (!downloader.platform())
+        return { ...base, state: "unavailable" };
+    if (!complete(downloader.installDir(cacheDir, name, pin.buildId)))
+        return { ...base, state: "missing" };
+    return {
+        ...base,
+        state: "installed",
+        executablePath: downloader.executablePath(cacheDir, name, pin.buildId),
+    };
+}
+/** The pinned build's executable; throws BrowserNotInstalledError when it isn't complete */
+export function managedExecutable(name, options = {}) {
+    const status = statusOf(name, { ...options, env: {} });
+    if (status.state !== "installed")
+        throw new BrowserNotInstalledError(name, status.label);
+    return status.executablePath;
+}
+/** The folder the pinned build of `name` is, or would be, installed in */
+export function managedBuildDir(name, options = {}) {
+    const { cacheDir, downloader } = store(options);
+    return downloader.installDir(cacheDir, name, PINNED[name].buildId);
+}
+/** Removes a build (default: the pinned one); Chrome takes its chromedriver along */
+export function uninstallBrowser(name, buildId = PINNED[name].buildId, options = {}) {
+    const { cacheDir, downloader } = store(options);
+    const root = path.resolve(cacheDir);
+    const dirs = parts(name).map((part) => ({
+        part,
+        dir: downloader.installDir(cacheDir, part, buildId),
+    }));
+    if (/[/\\]|\.\./.test(buildId) ||
+        dirs.some(({ dir }) => !path.resolve(dir).startsWith(root + path.sep)))
+        throw new Error(`Invalid build id "${buildId}"`);
+    for (const { part, dir } of dirs) {
+        if (!existsSync(dir))
+            continue;
+        // Without its marker a build that is only partly removed reads as missing
+        rmSync(path.join(dir, COMPLETE_MARKER), { force: true });
+        downloader.uninstall(cacheDir, part, buildId);
+    }
+}
+/** Every Firefox and Chrome build in the cache, also those other framework versions pinned */
+export function listInstalled(options = {}) {
+    const { cacheDir, downloader } = store(options);
+    return downloader
+        .list(cacheDir)
+        .filter((b) => isManagedBrowser(b.browser))
+        .map((b) => {
+        const name = b.browser;
+        return {
+            name,
+            buildId: b.buildId,
+            dir: b.dir,
+            sizeBytes: sizeOf(b.dir),
+            pinned: PINNED[name].buildId === b.buildId,
+        };
+    });
+}

package/dist/cli/args.d.ts

@@ -19,6 +19,8 @@ export declare function parseCommandLine(argv: string[]): {
         at?: string | undefined;
         new?: string | undefined;
         url?: string | undefined;
+        build?: string | undefined;
+        unused?: boolean | undefined;
         help?: boolean | undefined;
         version?: boolean | undefined;
     };

package/dist/cli/args.js

@@ -15,6 +15,8 @@ const FLAGS = {
     at: { type: "string" },
     new: { type: "string" },
     url: { type: "string" },
+    build: { type: "string" },
+    unused: { type: "boolean" },
     help: { type: "boolean", short: "h" },
     version: { type: "boolean", short: "v" },
 };

package/dist/cli/browsers.d.ts

@@ -0,0 +1,6 @@
+import { type StoreOptions } from "../browsers/index.js";
+import type { Io } from "./main.js";
+export declare const BROWSERS_USAGE = "Usage:\n  samurai browsers [list]                        The pinned browsers and every build in the cache\n  samurai browsers install [firefox|chrome|all]  Download the pinned builds (default: all)\n  samurai browsers uninstall <name> [--build <id>]\n                                                 Remove a build (default: the pinned one)\n  samurai browsers uninstall --unused            Remove builds this framework version doesn't pin\n";
+export declare function formatBytes(n: number): string;
+/** `samurai browsers …`; `options` is for tests. The cache folder follows `io.env` */
+export declare function browsersCommand(argv: string[], io: Io, options?: StoreOptions): Promise<number>;

package/dist/cli/browsers.js

@@ -0,0 +1,117 @@
+import { browsersCacheDir, browserStatus, installBrowser, isManagedBrowser, listInstalled, MANAGED_BROWSERS, PINNED, uninstallBrowser, } from "../browsers/index.js";
+import { parseCommandLine } from "./args.js";
+export const BROWSERS_USAGE = `Usage:
+  samurai browsers [list]                        The pinned browsers and every build in the cache
+  samurai browsers install [firefox|chrome|all]  Download the pinned builds (default: all)
+  samurai browsers uninstall <name> [--build <id>]
+                                                 Remove a build (default: the pinned one)
+  samurai browsers uninstall --unused            Remove builds this framework version doesn't pin
+`;
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / 1024 / 1024).toFixed(1)} MB`;
+    return `${(n / 1024 / 1024 / 1024).toFixed(1)} GB`;
+}
+class UnknownBrowser extends Error {
+}
+function names(arg) {
+    if (arg === undefined || arg === "all")
+        return [...MANAGED_BROWSERS];
+    if (!isManagedBrowser(arg))
+        throw new UnknownBrowser(arg);
+    return [arg];
+}
+async function list(io, store) {
+    for (const s of await browserStatus({ ...store, env: io.env })) {
+        const state = s.override
+            ? `uses ${s.override.path} (${s.override.from === "env" ? "environment variable" : "samurai.config.ts"})`
+            : s.state === "installed"
+                ? "installed"
+                : s.state === "missing"
+                    ? "not installed"
+                    : "no download for this computer";
+        io.out(`${s.label.padEnd(36)} ${state}\n`);
+    }
+    const other = listInstalled(store).filter((b) => !b.pinned);
+    if (other.length > 0) {
+        io.out("\nOther builds in the cache:\n");
+        for (const b of other)
+            io.out(`  ${b.name} ${b.buildId}  ${formatBytes(b.sizeBytes)}\n`);
+    }
+}
+async function install(io, targets, store) {
+    const baseUrl = io.env.SAMURAI_BROWSERS_BASE_URL;
+    if (baseUrl)
+        io.out(`Downloading from ${baseUrl}\n`);
+    for (const name of targets) {
+        const label = PINNED[name].label;
+        let shown = -1;
+        const exe = await installBrowser(name, {
+            ...store,
+            onProgress: (done, total) => {
+                const percent = total > 0 ? Math.floor((done / total) * 100) : 0;
+                if (io.color) {
+                    io.out(`\r${label}: ${percent}%`);
+                }
+                else if (percent >= shown + 10 ||
+                    (percent === 100 && shown !== 100)) {
+                    shown = percent;
+                    io.out(`${label}: ${percent}%\n`);
+                }
+            },
+        });
+        if (io.color)
+            io.out("\n");
+        io.out(`${label} installed at ${exe}\n`);
+    }
+}
+/** `samurai browsers …`; `options` is for tests. The cache folder follows `io.env` */
+export async function browsersCommand(argv, io, options = {}) {
+    const store = {
+        ...options,
+        cacheDir: options.cacheDir ?? browsersCacheDir(io.env),
+    };
+    const { values, positionals } = parseCommandLine(argv);
+    const [sub = "list", target] = positionals;
+    try {
+        if (sub === "list") {
+            await list(io, store);
+            return 0;
+        }
+        if (sub === "install") {
+            await install(io, names(target), store);
+            return 0;
+        }
+        if (sub === "uninstall") {
+            if (values.unused) {
+                for (const b of listInstalled(store).filter((b) => !b.pinned)) {
+                    uninstallBrowser(b.name, b.buildId, store);
+                    io.out(`removed ${b.name} ${b.buildId}\n`);
+                }
+                io.out("Projects on other framework versions may still use the removed builds.\n");
+                return 0;
+            }
+            if (target === undefined || target === "all") {
+                io.err(`Which browser? \n\n${BROWSERS_USAGE}`);
+                return 2;
+            }
+            const [name] = names(target);
+            uninstallBrowser(name, values.build, store);
+            io.out(`removed ${name} ${values.build ?? PINNED[name].buildId}\n`);
+            return 0;
+        }
+        io.err(`Unknown browsers command "${sub}"\n\n${BROWSERS_USAGE}`);
+        return 2;
+    }
+    catch (e) {
+        if (e instanceof UnknownBrowser) {
+            io.err(`Unknown browser "${e.message}". Choose firefox, chrome or all.\n`);
+            return 1;
+        }
+        throw e;
+    }
+}

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\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\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):\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

@@ -4,6 +4,7 @@ import { recordSpec } from "../recorder/index.js";
 import { listTests, runTests } from "../runner/run.js";
 import { stepToSource } from "../steps/index.js";
 import { ConsoleReporter } from "./console-reporter.js";
+import { browsersCommand } from "./browsers.js";
 import { flowCommand } from "./flow.js";
 import { initProject } from "./init.js";
 export const USAGE = `samurai: browser tests over WebDriver BiDi
@@ -14,6 +15,7 @@ Usage:
   samurai record <spec>       Open a browser and record what you do into a spec file
   samurai init [folder]       Scaffold a project: config, an example test, .env.example
   samurai flow <command>      List, check and run the flows in ./flows (see below)
+  samurai browsers [command]  List, install and remove the browsers SAMURAI launches
 
 Options for run and list:
   --env <name>                Environment to run against (or SAMURAI_ENV)
@@ -48,6 +50,12 @@ samurai flow:
   Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported
   Run \`samurai flow\` alone for the details.
 
+samurai browsers:
+  list                        The pinned browsers and every build in the cache (the default)
+  install [firefox|chrome|all]
+                              Download the pinned builds (default: all)
+  uninstall <name> [--build <id>] | --unused
+
 Run it in the project folder, the one holding samurai.config.ts.
 `;
 function version() {
@@ -72,13 +80,15 @@ export async function main(argv, io) {
         }
         if (command === "flow")
             return await flowCommand(rest, io);
+        if (command === "browsers")
+            return await browsersCommand(rest, io);
         if (command === "init") {
             const { written, skipped } = initProject(positionals[0] ?? ".");
             for (const file of written)
                 io.out(`created ${file}\n`);
             for (const file of skipped)
                 io.out(`kept    ${file} (already there)\n`);
-            io.out("\nNext: install the dependencies, then `samurai run`.\n");
+            io.out("\nNext: install the dependencies, then `samurai browsers install firefox`, then `samurai run`.\n");
             return 0;
         }
         if (command === "record") {
@@ -95,6 +105,8 @@ export async function main(argv, io) {
                     ? Number(values.test)
                     : values.test;
             let count = 0;
+            let state = "recording";
+            let toolbarWarned = false;
             const result = await recordSpec({
                 ...parseRunOverrides(rest, io.env),
                 file,
@@ -106,7 +118,19 @@ export async function main(argv, io) {
                 ...(io.signal && { signal: io.signal }),
                 onStarted: () => {
                     if (!values.json)
-                        io.out("Recording. Alt+click an element to assert on it. Press Ctrl+C or close the window to stop.\n");
+                        io.out("Recording. Alt+click an element to assert on it. Press Stop in the toolbar, Ctrl+C or close the window to stop.\n");
+                },
+                onStatus: (status) => {
+                    if (values.json)
+                        return;
+                    if (!status.toolbar && !toolbarWarned) {
+                        toolbarWarned = true;
+                        io.out("The toolbar couldn't load on this page. Alt+click still records assertions.\n");
+                    }
+                    if (status.state !== state) {
+                        state = status.state;
+                        io.out(state === "paused" ? "Paused\n" : "Recording\n");
+                    }
                 },
                 onEvent: (event) => {
                     if (values.json)

package/dist/project/config-edit.d.ts

@@ -0,0 +1,16 @@
+export type ConfigValue = string | number | boolean | ConfigValue[] | {
+    [key: string]: ConfigValue;
+};
+/** The config can't be edited in place, e.g. it builds its object from variables or spreads */
+export declare class ConfigEditError extends Error {
+}
+/**
+ * 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 declare function editConfig(source: string, path: string[], value: ConfigValue | undefined): string;
+/** The text of one property (`staging: { … }`), indentation removed, for showing a part of the file; undefined when missing */
+export declare function propertyText(source: string, path: string[]): string | undefined;
+/** Whether the property at this path exists in the file's source, walking the same object literals `editConfig` does */
+export declare function hasConfigPath(source: string, path: string[]): boolean;