@itmetsam/samurai-framework 0.8.0 → 0.10.0

package/dist/network/router.js

@@ -2,13 +2,16 @@ import { STATUS_CODES } from "node:http";
 import logger from "../logger/index.js";
 import { BiDiError } from "../transport/bidi-error.js";
 import { toRequest } from "./network-tracker.js";
-import { isExactString, matchUrl, samePattern } from "./url-match.js";
+import { isExactString, matchUrl, samePattern, } from "./url-match.js";
 /** Time (ms) a handler may take to answer a request before the router lets it continue */
 const DEFAULT_ROUTE_TIMEOUT = 30000;
 /** How many handler errors the router keeps */
 const MAX_ERRORS = 100;
 function toHeaders(headers) {
-    return Object.entries(headers).map(([name, value]) => ({ name, value: { type: "string", value } }));
+    return Object.entries(headers).map(([name, value]) => ({
+        name,
+        value: { type: "string", value },
+    }));
 }
 function toBytes(data) {
     return typeof data === "string"
@@ -44,7 +47,8 @@ export class Route {
         const text = options.json !== undefined ? JSON.stringify(options.json) : undefined;
         const body = options.body ?? text;
         const headers = { ...options.headers };
-        const contentType = options.contentType ?? (text !== undefined ? "application/json" : undefined);
+        const contentType = options.contentType ??
+            (text !== undefined ? "application/json" : undefined);
         if (contentType && !hasHeader(headers, "content-type"))
             headers["content-type"] = contentType;
         if (!hasHeader(headers, "content-length")) {
@@ -67,14 +71,21 @@ export class Route {
         let headers = options.headers;
         if (options.postData !== undefined) {
             const withoutLength = Object.fromEntries(Object.entries(headers ?? this.info.headers).filter(([name]) => name.toLowerCase() !== "content-length"));
-            headers = { ...withoutLength, "content-length": String(Buffer.byteLength(options.postData)) };
+            headers = this.deps.sendsContentLength
+                ? {
+                    ...withoutLength,
+                    "content-length": String(Buffer.byteLength(options.postData)),
+                }
+                : withoutLength;
         }
         await this.answer("network.continueRequest", {
             request: this.info.id,
             ...(options.url !== undefined && { url: options.url }),
             ...(options.method !== undefined && { method: options.method }),
             ...(headers !== undefined && { headers: toHeaders(headers) }),
-            ...(options.postData !== undefined && { body: toBytes(options.postData) }),
+            ...(options.postData !== undefined && {
+                body: toBytes(options.postData),
+            }),
         });
     }
     /** Makes the request fail (the browser reports a network error to the page) */
@@ -146,7 +157,9 @@ export class Router {
             if (!(params.intercepts ?? []).some((id) => this.interceptIds.has(id)))
                 return;
             const info = toRequest(params.request, params.navigation, params.isBlocked, null);
-            const matching = this.routes.filter((entry) => matchUrl(entry.pattern, info.url)).reverse();
+            const matching = this.routes
+                .filter((entry) => matchUrl(entry.pattern, info.url))
+                .reverse();
             this.dispatch(info, matching, 0).catch((err) => logger.error("Handling the request to %s failed", info.url, { err }));
         };
         this.routeTimeout = options.routeTimeout ?? DEFAULT_ROUTE_TIMEOUT;
@@ -171,7 +184,8 @@ export class Router {
     }
     /** Removes the routes for `pattern` (only the one with `handler`, when given) */
     async unroute(pattern, handler) {
-        const removed = this.routes.filter((route) => samePattern(route.pattern, pattern) && (handler === undefined || route.handler === handler));
+        const removed = this.routes.filter((route) => samePattern(route.pattern, pattern) &&
+            (handler === undefined || route.handler === handler));
         await this.remove(removed);
     }
     async unrouteAll() {
@@ -189,7 +203,9 @@ export class Router {
             return;
         this.routes = this.routes.filter((route) => !removed.includes(route));
         // Requests a removed route still holds would wait for nobody
-        await Promise.all([...this.pending].filter((route) => removed.includes(route.entry)).map((route) => route.release()));
+        await Promise.all([...this.pending]
+            .filter((route) => removed.includes(route.entry))
+            .map((route) => route.release()));
         await this.enqueue(() => this.sync());
     }
     enqueue(work) {
@@ -209,7 +225,8 @@ export class Router {
         const id = await this.addIntercept(patterns);
         const previous = this.currentId;
         this.currentId = id;
-        this.currentKey = patterns && !patternsUnsupported.has(this.connector) ? key : "all";
+        this.currentKey =
+            patterns && !patternsUnsupported.has(this.connector) ? key : "all";
         this.interceptIds.add(id);
         // The new intercept is in place before the old one goes: nothing slips through in between
         if (previous !== undefined)
@@ -243,7 +260,9 @@ export class Router {
             return intercept;
         }
         catch (err) {
-            if (patterns && err instanceof BiDiError && err.code === "invalid argument") {
+            if (patterns &&
+                err instanceof BiDiError &&
+                err.code === "invalid argument") {
                 patternsUnsupported.add(this.connector);
                 return this.addIntercept(undefined);
             }
@@ -267,7 +286,9 @@ export class Router {
             return;
         this.connector.onEvent("network.beforeRequestSent", this.onBeforeRequestSent);
         try {
-            this.subscription = await this.connector.subscribe(["network.beforeRequestSent"]);
+            this.subscription = await this.connector.subscribe([
+                "network.beforeRequestSent",
+            ]);
         }
         catch (err) {
             this.connector.offEvent("network.beforeRequestSent", this.onBeforeRequestSent);
@@ -296,6 +317,7 @@ export class Router {
             settled: (settled) => {
                 this.pending.delete(settled);
             },
+            sendsContentLength: this.connector.browserName !== "chrome",
         };
         if (!entry) {
             // Nobody (left) to ask: an unmatched request, or every route fell back

package/dist/recorder/session.d.ts

@@ -1,5 +1,6 @@
 import { Browser } from "../browser/browser.js";
 import type Page from "../browser/page.js";
+import type { SupportedBrowser } from "../types/browser.js";
 import type { PreparedRun } from "../runner/prepare-run.js";
 import { type ProjectOptions } from "../runner/project.js";
 import type { SamuraiTestConfig } from "../types/config.js";
@@ -20,6 +21,8 @@ export interface RecordSpecOptions extends ProjectOptions {
     at?: number;
     /** The page to start on. @default the environment's base URL; without one the browser starts blank */
     url?: string;
+    /** The browser to record in. @default the first of the config's `browsers`, else Firefox */
+    browser?: SupportedBrowser;
     /** The browser's debugging port. @default 9223 */
     port?: number;
     /** Run the browser without a window. A person can't use it then; for tests and machines without a display. @default the config's `use.headless`, else headless on CI and a window otherwise */

package/dist/recorder/session.js

@@ -2,7 +2,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { Browser } from "../browser/browser.js";
 import { ensureWarm } from "../browser/warm-up.js";
-import { loadConfig, projectDir } from "../config/config.js";
+import { browsersFor } from "../runner/browsers.js";
+import { loadConfig, projectDir, readConfig } from "../config/config.js";
 import { loadSecrets } from "../config/secrets.js";
 import { filesFolder, isFolderIgnored, isGitIgnored, } from "../project/index.js";
 import { withProject } from "../runner/project.js";
@@ -101,7 +102,10 @@ export async function recordSpec(options) {
             throw new Error(`${options.file} does not exist; give a title with --new to create it`);
         }
         // Before the spec is touched: a recording without its browser changes nothing
-        await ensureWarm("firefox", { port: options.port ?? 9223 }, options.signal);
+        // Recording in two browsers at once makes no sense: the first of the project's, or the one asked for
+        const browserName = options.browser ??
+            browsersFor({ project: await readConfig("browsers") })[0];
+        await ensureWarm(browserName, { port: options.port ?? 9223 }, options.signal);
         options.signal?.throwIfAborted();
         source ??= "";
         if (options.create !== undefined &&
@@ -117,7 +121,7 @@ export async function recordSpec(options) {
         if (!Number.isInteger(at) || at < 0 || at > test.steps.length) {
             throw new RangeError(`--at must be between 0 and ${test.steps.length} (the test has ${test.steps.length} steps)`);
         }
-        const { browser, page } = await Browser.launch("firefox", {
+        const { browser, page } = await Browser.launch(browserName, {
             port: options.port ?? 9223,
             headless: options.headless ?? settings.headless,
         }, options.signal);

package/dist/recorder/toolbar/controller.d.ts

@@ -46,11 +46,6 @@ export interface ControllerOptions {
 type Message = ToolbarMessage & {
     target?: ElementHandle;
 };
-/**
- * The recorder's side of the toolbar: owns its state (pause, the rail, the environment's variables and
- * secrets) and turns its messages into observations. Secret values stay here; the page only ever gets
- * their names and whether they are set.
- */
 export declare class ToolbarController {
     private readonly deps;
     private readonly options;
@@ -79,6 +74,8 @@ export declare class ToolbarController {
     private readonly done;
     /** Bumped on every page load: work started for an older page is not answered */
     private page;
+    /** Wake-ups for the work that is waiting on the current page: called, and forgotten, when the page changes */
+    private pageGone;
     private toolbar;
     /** A `ready` arrived since the last load: it counts for the next one */
     private readySinceLoad;
@@ -104,6 +101,10 @@ export declare class ToolbarController {
      * and doesn't count for the coming load
      */
     navigating(): void;
+    /** Lets what waits on the current document stop waiting: its commands may never be answered once it is gone */
+    private leavePage;
+    /** Runs `work`, but stops waiting for it when the page is left; resolves `gone` then */
+    private whileOnPage;
     /** A step was emitted (any source): count it */
     stepAdded(step: Step): void;
     /** A recorded step was taken out again (a cancelled file picker's click) */

package/dist/recorder/toolbar/controller.js

@@ -22,6 +22,8 @@ const fail = (error, field) => ({
  * secrets) and turns its messages into observations. Secret values stay here; the page only ever gets
  * their names and whether they are set.
  */
+/** What a wait on the page ends with when the page was left first */
+const LEFT = Symbol("left the page");
 export class ToolbarController {
     constructor(deps, options) {
         this.deps = deps;
@@ -41,6 +43,8 @@ export class ToolbarController {
         this.done = new Set();
         /** Bumped on every page load: work started for an older page is not answered */
         this.page = 0;
+        /** Wake-ups for the work that is waiting on the current page: called, and forgotten, when the page changes */
+        this.pageGone = new Set();
         this.toolbar = true;
         /** A `ready` arrived since the last load: it counts for the next one */
         this.readySinceLoad = false;
@@ -173,6 +177,7 @@ export class ToolbarController {
         if (this.disposed)
             return;
         this.page++;
+        this.leavePage();
         this.pick = undefined;
         this.toast = undefined;
         this.push();
@@ -197,6 +202,28 @@ export class ToolbarController {
      */
     navigating() {
         this.readySinceLoad = false;
+        this.leavePage();
+    }
+    /** Lets what waits on the current document stop waiting: its commands may never be answered once it is gone */
+    leavePage() {
+        const waiting = [...this.pageGone];
+        this.pageGone.clear();
+        for (const wake of waiting)
+            wake();
+    }
+    /** Runs `work`, but stops waiting for it when the page is left; resolves `gone` then */
+    async whileOnPage(work, gone) {
+        let wake;
+        const left = new Promise((resolve) => {
+            wake = () => resolve(gone);
+            this.pageGone.add(wake);
+        });
+        try {
+            return await Promise.race([work(), left]);
+        }
+        finally {
+            this.pageGone.delete(wake);
+        }
     }
     /** A step was emitted (any source): count it */
     stepAdded(step) {
@@ -310,19 +337,24 @@ export class ToolbarController {
             return this.reply(message.id, fail(PAUSED));
         let found;
         try {
-            const locator = message.target &&
-                (await this.deps.rank(message.target, message.candidates));
-            if (locator) {
-                found = await this.deps.inspect(message.target, locator, message.candidates);
+            // Chrome never answers a command into a document that is being replaced, so a pick of the old page must not
+            // keep the messages behind it waiting
+            found = await this.whileOnPage(async () => {
+                const locator = message.target &&
+                    (await this.deps.rank(message.target, message.candidates));
+                if (!locator)
+                    return undefined;
+                const inspected = await this.deps.inspect(message.target, locator, message.candidates);
                 if (page === this.page)
-                    this.pick = { id: message.id, locator, counts: found.counts };
-            }
+                    this.pick = { id: message.id, locator, counts: inspected.counts };
+                return inspected;
+            }, LEFT);
         }
         catch {
             found = undefined; // the element went away while it was inspected
         }
         // The page that asked is gone: its successor's toolbar isn't waiting for this
-        if (page !== this.page)
+        if (found === LEFT || page !== this.page)
             return;
         this.reply(message.id, found ? this.withoutSecrets(found.info) : fail(UNIDENTIFIABLE));
     }

package/dist/runner/browsers.d.ts

@@ -0,0 +1,22 @@
+import type { SupportedBrowser } from "../types/browser.js";
+import type { SamuraiTestConfig } from "../types/config.js";
+/** Every browser a config may name, in the order the messages list them */
+export declare const BROWSER_NAMES: readonly SupportedBrowser[];
+/** The browsers of a run that names none */
+export declare const DEFAULT_BROWSERS: readonly SupportedBrowser[];
+/** Throws when `list` is not a non-empty list of distinct browser names; `where` names the key in the message */
+export declare function checkBrowserList(list: unknown, where: string): void;
+/**
+ * Checks the browser keys of a config: the removed `browser`, and `browsers` on the project and on each group.
+ * Throws an Error that says what to write instead.
+ */
+export declare function validateBrowserConfig(config: SamuraiTestConfig): void;
+/**
+ * The browsers a run uses, the first that is set winning: the command line, the group being run, the project, then
+ * Firefox. An empty list counts as not given.
+ */
+export declare function browsersFor(sources: {
+    flag?: readonly SupportedBrowser[] | undefined;
+    group?: readonly SupportedBrowser[] | undefined;
+    project?: readonly SupportedBrowser[] | undefined;
+}): SupportedBrowser[];

package/dist/runner/browsers.js

@@ -0,0 +1,44 @@
+/** Every browser a config may name, in the order the messages list them */
+export const BROWSER_NAMES = ["firefox", "chrome"];
+/** The browsers of a run that names none */
+export const DEFAULT_BROWSERS = ["firefox"];
+const isBrowser = (value) => typeof value === "string" &&
+    BROWSER_NAMES.includes(value);
+/** Throws when `list` is not a non-empty list of distinct browser names; `where` names the key in the message */
+export function checkBrowserList(list, where) {
+    if (!Array.isArray(list) || list.length === 0)
+        throw new Error(`${where} must list at least one browser.`);
+    const seen = new Set();
+    for (const name of list) {
+        if (!isBrowser(name))
+            throw new Error(`Unknown browser "${String(name)}" in ${where}. Choose ${BROWSER_NAMES.join(" or ")}.`);
+        if (seen.has(name))
+            throw new Error(`Browser "${name}" is listed twice in ${where}.`);
+        seen.add(name);
+    }
+}
+/**
+ * Checks the browser keys of a config: the removed `browser`, and `browsers` on the project and on each group.
+ * Throws an Error that says what to write instead.
+ */
+export function validateBrowserConfig(config) {
+    const legacy = config.browser;
+    if (legacy !== undefined)
+        throw new Error(`"browser" was replaced by "browsers": use browsers: [${JSON.stringify(legacy)}]`);
+    if (config.browsers !== undefined)
+        checkBrowserList(config.browsers, "browsers");
+    config.groups?.forEach((group, index) => {
+        if (group.browsers !== undefined)
+            checkBrowserList(group.browsers, `groups[${index}].browsers`);
+    });
+}
+/**
+ * The browsers a run uses, the first that is set winning: the command line, the group being run, the project, then
+ * Firefox. An empty list counts as not given.
+ */
+export function browsersFor(sources) {
+    for (const list of [sources.flag, sources.group, sources.project])
+        if (list && list.length > 0)
+            return [...list];
+    return [...DEFAULT_BROWSERS];
+}

package/dist/runner/groups.d.ts

@@ -1,3 +1,4 @@
+import type { SupportedBrowser } from "../types/browser.js";
 import type { SamuraiGroup } from "../types/config.js";
 /** The test folder when the config names none */
 export declare const DEFAULT_SRC_DIR = "./src";
@@ -22,6 +23,8 @@ export interface ResolvedGroup {
         file: string;
         title: string;
     }[];
+    /** The browsers the group's tests run in: its own `browsers`, else the project's, else Firefox */
+    browsers: SupportedBrowser[];
 }
 /**
  * The real path of `p` (symlinks resolved), or `p` itself when it does not exist. Registered test files come
@@ -33,10 +36,11 @@ export declare const toPosix: (p: string) => string;
 /** The id of a test: its spec file relative to `srcDir` with `/` separators, then `::` and its full name */
 export declare const testId: (file: string, name: string) => string;
 /** Works out which of `tests` (files relative to `srcDir`) belong to the group */
-export declare function resolveGroup(group: SamuraiGroup, tests: GroupTest[], projectDir: string, srcDir: string): ResolvedGroup;
+export declare function resolveGroup(group: SamuraiGroup, tests: GroupTest[], projectDir: string, srcDir: string, projectBrowsers?: readonly SupportedBrowser[]): ResolvedGroup;
 /** Resolves every group of the config */
 export declare function resolveGroups(config: {
     groups?: SamuraiGroup[];
+    browsers?: SupportedBrowser[];
 }, tests: GroupTest[], projectDir: string, srcDir: string): ResolvedGroup[];
 /** The group called `name`, or an error naming the groups there are */
 export declare function findGroup<T extends {

package/dist/runner/groups.js

@@ -1,5 +1,6 @@
 import { realpathSync } from "node:fs";
 import { matchesGlob, relative, resolve } from "node:path";
+import { browsersFor } from "./browsers.js";
 /** The test folder when the config names none */
 export const DEFAULT_SRC_DIR = "./src";
 /** The spec pattern when a group names none */
@@ -21,7 +22,11 @@ export const toPosix = (p) => p.replace(/\\/g, "/");
 /** The id of a test: its spec file relative to `srcDir` with `/` separators, then `::` and its full name */
 export const testId = (file, name) => `${toPosix(file)}::${name}`;
 /** Works out which of `tests` (files relative to `srcDir`) belong to the group */
-export function resolveGroup(group, tests, projectDir, srcDir) {
+export function resolveGroup(group, tests, projectDir, srcDir, projectBrowsers) {
+    const browsers = browsersFor({
+        group: group.browsers,
+        project: projectBrowsers,
+    });
     const found = tests.map((t) => ({ ...t, id: testId(t.file, t.name) }));
     // Tests picked by hand override src and testMatch
     if (group.tests) {
@@ -38,6 +43,7 @@ export function resolveGroup(group, tests, projectDir, srcDir) {
             missing: picked
                 .filter((t) => !known.has(t.id))
                 .map(({ file, title }) => ({ file, title })),
+            browsers,
         };
     }
     const base = group.src ? resolve(projectDir, group.src) : srcDir;
@@ -54,11 +60,12 @@ export function resolveGroup(group, tests, projectDir, srcDir) {
         pattern: [group.src, group.testMatch].filter(Boolean).join(" · ") || pattern,
         testIds,
         missing: [],
+        browsers,
     };
 }
 /** Resolves every group of the config */
 export function resolveGroups(config, tests, projectDir, srcDir) {
-    return (config.groups ?? []).map((group) => resolveGroup(group, tests, projectDir, srcDir));
+    return (config.groups ?? []).map((group) => resolveGroup(group, tests, projectDir, srcDir, config.browsers));
 }
 /** The group called `name`, or an error naming the groups there are */
 export function findGroup(groups, name) {

package/dist/runner/reporter.d.ts

@@ -1,17 +1,22 @@
 import type { RegisteredTestCase, TestError, TestLogEntry, TestResult, TestSummary } from "../types/test.js";
+import type { SupportedBrowser } from "../types/browser.js";
 /** What a run reports while it happens */
 export type RunEvent = {
     type: "run-start";
     environment: string;
+    /** Every selected test in every browser */
     total: number;
+    browsers: SupportedBrowser[];
 } | {
     type: "test-start";
     name: string;
     file: string;
+    browser: SupportedBrowser;
 } | {
     type: "test-end";
     name: string;
     file: string;
+    browser: SupportedBrowser;
     result: TestResult;
 } | {
     type: "run-end";
@@ -20,6 +25,8 @@ export type RunEvent = {
 export interface ReporterOptions {
     /** The environment the run uses, recorded in the report */
     environment: string;
+    /** The browsers the run uses, in the order they run; recorded in the report */
+    browsers: SupportedBrowser[];
     /** Where the report is written. @default <cwd>/result/report.json */
     output?: string | false;
     /** Called with every event, in order. A throwing listener is ignored */
@@ -29,14 +36,15 @@ export default class TestReporter {
     private testResults;
     private summary;
     private environment;
+    private browsers;
     private output;
     private listener;
     constructor(options: ReporterOptions);
     private emit;
     onStart(total?: number): void;
     onEnd(): Promise<TestSummary>;
-    onTestStart(test: RegisteredTestCase): void;
-    onTestEnd(test: RegisteredTestCase, error?: TestError, extras?: {
+    onTestStart(test: RegisteredTestCase, browser: SupportedBrowser): void;
+    onTestEnd(test: RegisteredTestCase, browser: SupportedBrowser, error?: TestError, extras?: {
         logs?: TestLogEntry[];
         logsDropped?: number;
         screenshots?: {

package/dist/runner/reporter.js

@@ -2,14 +2,15 @@ import { mkdir, writeFile } from "fs/promises";
 import path from "path";
 import { projectDir } from "../config/config.js";
 import { maskDeep } from "../config/mask.js";
-/** Results are keyed by file and full title, so equal titles in different files or describe blocks stay apart */
-function keyOf(test) {
-    return `${test.file}::${test.name}`;
+/** Results are keyed by file, full title and browser, so equal titles in different files or describe blocks, and the same test in two browsers, stay apart */
+function keyOf(test, browser) {
+    return `${test.file}::${test.name}::${browser}`;
 }
 export default class TestReporter {
     constructor(options) {
         this.testResults = new Map();
         this.environment = options.environment;
+        this.browsers = [...options.browsers];
         this.output =
             options.output ?? path.join(projectDir(), "result/report.json");
         this.listener = options.onEvent;
@@ -29,9 +30,15 @@ export default class TestReporter {
             status: "failed",
             startTime: t.startTime,
             environment: this.environment,
+            browsers: this.browsers,
             tests: [],
         };
-        this.emit({ type: "run-start", environment: this.environment, total });
+        this.emit({
+            type: "run-start",
+            environment: this.environment,
+            total,
+            browsers: this.browsers,
+        });
     }
     async onEnd() {
         performance.mark(`group-finish`);
@@ -40,6 +47,7 @@ export default class TestReporter {
             ...this.summary,
             duration,
             environment: this.environment,
+            browsers: this.browsers,
             tests: Array.from(this.testResults.values()),
             status: Array.from(this.testResults.values()).every((r) => r.status === "success")
                 ? "success"
@@ -54,19 +62,25 @@ export default class TestReporter {
         this.emit({ type: "run-end", summary: this.summary });
         return this.summary;
     }
-    onTestStart(test) {
-        const key = keyOf(test);
+    onTestStart(test, browser) {
+        const key = keyOf(test, browser);
         const t = performance.mark(`${key}-start`);
         this.testResults.set(key, {
             name: test.name,
             file: test.file,
+            browser,
             status: "started",
             startTime: t.startTime,
         });
-        this.emit({ type: "test-start", name: test.name, file: test.file });
+        this.emit({
+            type: "test-start",
+            name: test.name,
+            file: test.file,
+            browser,
+        });
     }
-    onTestEnd(test, error, extras) {
-        const key = keyOf(test);
+    onTestEnd(test, browser, error, extras) {
+        const key = keyOf(test, browser);
         performance.mark(`${key}-finish`);
         const duration = performance.measure("test-duration", `${key}-start`, `${key}-finish`).duration;
         const result = maskDeep({
@@ -79,6 +93,12 @@ export default class TestReporter {
             ...(extras?.screenshots?.length && { screenshots: extras.screenshots }),
         });
         this.testResults.set(key, result);
-        this.emit({ type: "test-end", name: test.name, file: test.file, result });
+        this.emit({
+            type: "test-end",
+            name: test.name,
+            file: test.file,
+            browser,
+            result,
+        });
     }
 }

package/dist/runner/run.d.ts

@@ -24,6 +24,7 @@ export interface FoundTest {
 export declare function listTests(options?: RunTestsOptions): Promise<FoundTest[]>;
 /** Imports the project's specs without running anything and lists the config's groups with the tests each holds */
 export declare function listGroups(options?: RunTestsOptions): Promise<ResolvedGroup[]>;
+export { BROWSER_NAMES, checkBrowserList } from "./browsers.js";
 export type { RunEvent } from "./reporter.js";
 export type { TestError, TestResult, TestSummary } from "../types/test.js";
 export type { ResolvedGroup } from "./groups.js";

package/dist/runner/run.js

@@ -44,3 +44,4 @@ export async function listGroups(options = {}) {
         expectTimeout,
     }, async (run) => (await TestRunner.init(run, undefined, runner)).groups());
 }
+export { BROWSER_NAMES, checkBrowserList } from "./browsers.js";

package/dist/runner/test-runner.d.ts

@@ -1,3 +1,4 @@
+import type { SupportedBrowser } from "../types/browser.js";
 import type { RegisteredTestCase } from "../types/test.js";
 import type { PreparedRun } from "./prepare-run.js";
 import { type RunEvent } from "./reporter.js";
@@ -13,6 +14,8 @@ export interface RunnerOptions {
     testNames?: string[];
     /** Only the tests of this group of the config's `groups` (unknown name: an error). Combines with the other filters */
     group?: string;
+    /** The browsers to run in, instead of the group's or the project's `browsers` (the command line's `--browser`) */
+    browsers?: SupportedBrowser[];
     /** Run the browser without a window. @default false */
     headless?: boolean;
     /** Remote debugging port of the browser. @default 9223 */
@@ -49,7 +52,12 @@ export default class TestRunner {
     groups(): Promise<ResolvedGroup[]>;
     /** Imports the spec files and returns the tests the options select: by `group`, `testNames` and `grep` */
     register(): Promise<RegisteredTestCase[]>;
-    /** Runs the selected tests and returns the summary that was also written to the report */
+    /**
+     * The browsers the run uses: the options' (`--browser`), else the selected group's, else the project's, else
+     * Firefox. A group is only looked up when there is something to look up
+     */
+    private browsersOfRun;
+    /** Runs the selected tests in every browser of the run, one browser after the other, and returns the summary that was also written to the report */
     start(): Promise<import("../types/test.js").TestSummary>;
     private executeTestCase;
 }