@itmetsam/samurai-framework 0.15.1 → 0.16.0

package/dist/runner/test-runner.js

@@ -2,12 +2,12 @@ import { glob } from "node:fs/promises";
 import path from "path";
 import { ensureWarm } from "../browser/warm-up.js";
 import { projectBrowser } from "../browsers/resolve.js";
-import { loadConfig, projectDir, readConfig } from "../config/config.js";
+import { loadRawConfig, projectDir, readConfig } from "../config/config.js";
 import { forbidsOnly } from "../config/forbid-only.js";
 import logger from "../logger/index.js";
 import { AllHooks } from "./all-hooks.js";
 import { assertNoOnly, narrowToOnly } from "./focus.js";
-import { DEFAULT_SRC_DIR, DEFAULT_TEST_MATCH } from "./groups.js";
+import { DEFAULT_SRC_DIR, DEFAULT_TEST_MATCH } from "../config/defaults.js";
 import { DEFAULT_PORT } from "./ports.js";
 import TestReporter from "./reporter.js";
 import { concurrency, planItems, poolMode, runPooled, serialKeyOf, } from "./pooled-run.js";
@@ -16,7 +16,7 @@ import { staticSkip } from "./skip.js";
 import { browsersOfRun, loadSpecs, selectTests } from "./select.js";
 import { resolveRetries } from "./retries-option.js";
 import { runWithRetries } from "./retry.js";
-import { resolveWorkers } from "./workers-option.js";
+import { resolveWorkers } from "../config/workers-option.js";
 import { WorkerPool } from "./worker-pool.js";
 import { processWorkerFactory } from "./worker-process.js";
 /** Finds the spec files, picks the tests and browsers of a run and runs each test in each browser */
@@ -48,9 +48,13 @@ export default class TestRunner {
     async groups() {
         return (await loadSpecs(this.testFiles)).groups;
     }
-    /** Imports the spec files and returns the tests the options select: by `group`, `testNames` and `grep` */
-    async register() {
-        return selectTests(await loadSpecs(this.testFiles), this.options);
+    /**
+     * Imports the spec files and returns the tests the options select (by `group`, `testNames` and `grep`)
+     * with the real `srcDir` their ids are relative to
+     */
+    async list() {
+        const loaded = await loadSpecs(this.testFiles);
+        return { tests: selectTests(loaded, this.options), srcDir: loaded.srcDir };
     }
     /**
      * Runs the selected tests in every browser of the run, one browser after the other, and returns the summary that
@@ -60,7 +64,7 @@ export default class TestRunner {
         const { reportPath, onEvent, signal } = this.options;
         // The specs are imported once: their top-level code runs once per run
         const loaded = await loadSpecs(this.testFiles);
-        const config = await loadConfig();
+        const config = await loadRawConfig();
         // A focused test the config refuses stops the run before anything starts; else only the focused ones run
         assertNoOnly(loaded.all, forbidsOnly(config), loaded.srcDir);
         const selected = narrowToOnly(selectTests(loaded, this.options));
@@ -123,9 +127,9 @@ export default class TestRunner {
         try {
             for (const browser of browsers) {
                 for (const test of selected) {
-                    const annotation = staticSkip(test);
-                    if (annotation) {
-                        reporter.onTestSkipped(test, browser, { annotation });
+                    const skip = staticSkip(test);
+                    if (skip) {
+                        reporter.onTestSkipped(test, browser, skip);
                         continue;
                     }
                     if (signal?.aborted) {

package/dist/steps/edit.d.ts

@@ -22,6 +22,16 @@ export type StepEdit = {
     test: number;
     from: number;
     to: number;
+}
+/**
+ * Removes the whole test, with the comments and the blank line above it. For several tests, apply from the last index to the first.
+ * It removes all leading trivia from the end of the previous statement, so comments above the test go with it: a
+ * file-header comment when the test is the first statement, and a trailing `// comment` on the previous test's line.
+ * Throws for a test that isn't `removable`
+ */
+ | {
+    op: "remove-test";
+    test: number;
 };
 /**
  * Applies one edit and returns the new source. Only the touched statement changes, plus the test's parameters

package/dist/steps/edit.js

@@ -125,6 +125,10 @@ export function applyEdit(source, edit) {
         }
         case "remove":
             return removeStep(source, parsed, edit.index);
+        case "remove-test":
+            if (!parsed.removable)
+                throw new Error(`Cannot remove test "${parsed.name}": it is not a statement of its own`);
+            return splice(source, parsed.start, parsed.end, "");
         case "move": {
             const { start, end } = pickStep(parsed, edit.from);
             if (edit.to < 0 || edit.to >= parsed.steps.length)

package/dist/steps/index.d.ts

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

package/dist/steps/index.js

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

package/dist/steps/model.d.ts

@@ -146,6 +146,15 @@ export interface ParsedTest {
     /** Offset just after the `{` of the test body, and of its closing `}` */
     bodyStart: number;
     bodyEnd: number;
+    /** Where the whole test starts: the full start of its statement, so the comments and blank line above are included */
+    start: number;
+    /** Where the whole test ends: the end of its statement, after the `;` */
+    end: number;
+    /**
+     * False when the test call isn't a statement of its own (a loop or `if` body without braces, an arrow's
+     * expression body), so it can't be removed without breaking the file
+     */
+    removable: boolean;
     /**
      * The fixtures the test's callback destructures, and the offset where another one goes: after the last one
      * (`list`), inside an empty `{}` (`empty`) or inside the empty `()` of a callback without parameters (`none`).
@@ -158,4 +167,14 @@ export interface ParsedTest {
     };
     /** `skip` or `fixme` (not run), or `only` (focused), as the runner applies it: a modifier on a `describe` counts */
     modifier?: Modifier;
+    /** The `{ reason }` written with the `skip` or `fixme` that applies, when it is a string literal */
+    reason?: string;
+}
+/** A `test` or `describe` call the codec can't read: its title isn't a plain string, or its function isn't written inline */
+export interface UnparsedTest {
+    kind: "test" | "describe";
+    /** The statement's range, as for `ParsedTest` */
+    start: number;
+    end: number;
+    reason: "dynamic-title" | "not-inline";
 }

package/dist/steps/parse.d.ts

@@ -1,3 +1,8 @@
-import type { ParsedTest } from "./model.js";
+import type { ParsedTest, UnparsedTest } from "./model.js";
+/** The tests in a spec file, with their steps and where each statement sits, and the tests and describes it can't read */
+export declare function parseSpecFile(source: string): {
+    tests: ParsedTest[];
+    unparsed: UnparsedTest[];
+};
 /** The tests in a spec file, with their steps and where each statement sits */
 export declare function parseSpec(source: string): ParsedTest[];

package/dist/steps/parse.js

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import { stringOf } from "./parse/literals.js";
+import { readObject, stringOf } from "./parse/literals.js";
 import { readStep } from "./parse/step.js";
 function parseStatement(source, statement, sourceFile) {
     const start = statement.getStart(sourceFile);
@@ -57,45 +57,115 @@ function calleeOf(expression) {
         };
     return undefined;
 }
-/** What the runner applies to a test (see `modifierOf` in the runner): the innermost `skip` or `fixme`, else `only` */
-function effectiveModifier(own, describes) {
+/**
+ * The callback of `test(title, fn)` and `describe(title, fn)`, and for a skip or fixme also of
+ * `(title, { reason }, fn)` with the reason when it is a literal
+ */
+function callbackOf(node, modifier) {
+    const [, second, third] = node.arguments;
+    if ((modifier === "skip" || modifier === "fixme") &&
+        second &&
+        ts.isObjectLiteralExpression(second)) {
+        const reason = readObject(second, ["reason"])?.reason;
+        return {
+            callback: third,
+            ...(typeof reason === "string" && { reason }),
+        };
+    }
+    return { callback: second };
+}
+/** What the runner applies to a test (see `modifierOf` in the runner): the innermost `skip` or `fixme` with its reason, else `only` */
+function effectiveMark(own, describes) {
     const chain = [own, ...[...describes].reverse()];
-    return (chain.find((m) => m === "skip" || m === "fixme") ??
-        (chain.includes("only") ? "only" : undefined));
+    const skip = chain.find((m) => m.modifier === "skip" || m.modifier === "fixme");
+    if (skip)
+        return {
+            modifier: skip.modifier,
+            ...(skip.reason !== undefined && { reason: skip.reason }),
+        };
+    return chain.some((m) => m.modifier === "only") ? { modifier: "only" } : {};
 }
-/** The tests in a spec file, with their steps and where each statement sits */
-export function parseSpec(source) {
+/** The range of a whole test: its statement with the comments above it, or the call alone when it isn't a statement */
+function wholeRange(call) {
+    const statement = ts.isExpressionStatement(call.parent) ? call.parent : call;
+    return { start: statement.getFullStart(), end: statement.end };
+}
+/** Whether the call is a statement directly inside a block, a module block or the file, so removing its range leaves valid code */
+function isRemovable(call) {
+    const statement = call.parent;
+    if (!ts.isExpressionStatement(statement))
+        return false;
+    const container = statement.parent;
+    return (ts.isBlock(container) ||
+        ts.isSourceFile(container) ||
+        ts.isModuleBlock(container));
+}
+/** A test or describe the codec can't read, with where its statement sits */
+function unreadable(node, kind, reason) {
+    return { kind, reason, ...wholeRange(node) };
+}
+/** `test.skip(condition, reason)` inside a body: it takes a condition where a test takes a title, so it is neither a test nor unparsed */
+function isConditionForm(node, callee) {
+    const [first] = node.arguments;
+    return ((callee.modifier === "skip" || callee.modifier === "fixme") &&
+        !(first &&
+            (ts.isStringLiteral(first) ||
+                ts.isNoSubstitutionTemplateLiteral(first) ||
+                ts.isTemplateExpression(first))));
+}
+/** The tests in a spec file, with their steps and where each statement sits, and the tests and describes it can't read */
+export function parseSpecFile(source) {
     const sourceFile = ts.createSourceFile("spec.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
     const tests = [];
+    const unparsed = [];
     const visit = (node, titles, describes) => {
         const callee = ts.isCallExpression(node)
             ? calleeOf(node.expression)
             : undefined;
-        if (ts.isCallExpression(node) && callee) {
+        if (ts.isCallExpression(node) &&
+            callee &&
+            (callee.name === "test" || callee.name === "describe") &&
+            !(callee.name === "test" && isConditionForm(node, callee))) {
+            const kind = callee.name;
             const title = stringOf(node.arguments[0]);
-            const body = callbackBody(node.arguments[1]);
-            if (title !== undefined && body && callee.name === "test") {
-                // `test.skip(condition, reason)` has no title and no body, so it stays a step of the test it is in
+            const { callback, reason } = callbackOf(node, callee.modifier);
+            const body = callbackBody(callback);
+            if (title === undefined) {
+                unparsed.push(unreadable(node, kind, "dynamic-title"));
+                return;
+            }
+            if (!body) {
+                unparsed.push(unreadable(node, kind, "not-inline"));
+                return;
+            }
+            const mark = {
+                ...(callee.modifier && { modifier: callee.modifier }),
+                ...(reason !== undefined && { reason }),
+            };
+            if (kind === "test") {
                 const titlePath = [...titles, title];
-                const modifier = effectiveModifier(callee.modifier, describes);
                 tests.push({
                     titlePath,
                     name: titlePath.join(" > "),
                     steps: body.statements.map((statement) => parseStatement(source, statement, sourceFile)),
                     bodyStart: body.getStart(sourceFile) + 1,
                     bodyEnd: body.end - 1,
-                    fixtures: callbackFixtures(node.arguments[1], sourceFile),
-                    ...(modifier && { modifier }),
+                    ...wholeRange(node),
+                    removable: isRemovable(node),
+                    fixtures: callbackFixtures(callback, sourceFile),
+                    ...effectiveMark(mark, describes),
                 });
                 return;
             }
-            if (title !== undefined && body && callee.name === "describe") {
-                ts.forEachChild(body, (child) => visit(child, [...titles, title], [...describes, callee.modifier]));
-                return;
-            }
+            ts.forEachChild(body, (child) => visit(child, [...titles, title], [...describes, mark]));
+            return;
         }
         ts.forEachChild(node, (child) => visit(child, titles, describes));
     };
     visit(sourceFile, [], []);
-    return tests;
+    return { tests, unparsed };
+}
+/** The tests in a spec file, with their steps and where each statement sits */
+export function parseSpec(source) {
+    return parseSpecFile(source).tests;
 }

package/dist/transport/bidi-connection.d.ts

@@ -1,7 +1,5 @@
 import type { BiDiCommands, BiDiEvents } from "../types/bidi.js";
 import { type EventName, type Subscription, type SubscribeOptions } from "./subscriptions.js";
-/** Time (ms) a command may wait for its reply before it fails with code "timeout" */
-export declare const DEFAULT_COMMAND_TIMEOUT = 30000;
 export interface ConnectorOptions {
     /** @default DEFAULT_COMMAND_TIMEOUT */
     commandTimeout?: number;

package/dist/transport/bidi-connection.js

@@ -1,11 +1,10 @@
 import EventEmitter from "node:events";
+import { DEFAULT_COMMAND_TIMEOUT } from "../config/defaults.js";
 import logger from "../logger/index.js";
 import { WaitTimeoutError } from "../wait/wait-until.js";
 import { BiDiError } from "./bidi-error.js";
 import { forLog } from "./log-redaction.js";
 import { SubscriptionManager, } from "./subscriptions.js";
-/** Time (ms) a command may wait for its reply before it fails with code "timeout" */
-export const DEFAULT_COMMAND_TIMEOUT = 30000;
 /**
  * The connection to the browser is gone (the browser exited or was closed, or the socket dropped). Commands that
  * were waiting fail with it, and so does every command sent afterwards: a closed socket would swallow them silently.

package/dist/types/test.d.ts

@@ -21,6 +21,12 @@ export type TestCase = TestCaseBase;
 /** `skip`: not run. `fixme`: not run, known to be broken. `only`: the only test that runs when any is focused */
 export type Modifier = "skip" | "fixme" | "only";
 
+/** The optional second argument of `test.skip`, `test.fixme`, `describe.skip` and `describe.fixme` */
+export interface TestDetails {
+  /** Why the tests are not run; shown in the report and by `samurai list` */
+  reason?: string;
+}
+
 /** Runs before or after each test of a suite, in the test's browser, with the test's fixtures */
 export type EachHook = (fixtures: TestFixtures) => Promise<void> | void;
 
@@ -39,6 +45,8 @@ export interface Suite {
   title?: string;
   parent?: Suite;
   modifier?: Modifier;
+  /** The `{ reason }` of a `describe.skip` or `describe.fixme` */
+  reason?: string;
   beforeEach?: EachHook[];
   afterEach?: EachHook[];
   beforeAll?: AllHook[];
@@ -54,6 +62,8 @@ export interface RegisteredTestCase extends TestCaseBase {
   suite: Suite;
   /** What applies to the test: its own modifier, or the one of a suite around it */
   modifier?: Modifier;
+  /** The reason given with the `skip` or `fixme` that applies */
+  reason?: string;
 }
 
 export interface TestCaseBase {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {
@@ -48,6 +48,10 @@
       "types": "./dist/project/index.d.ts",
       "default": "./dist/project/index.js"
     },
+    "./capabilities": {
+      "types": "./dist/capabilities.d.ts",
+      "default": "./dist/capabilities.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -55,7 +59,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/copy-types.mjs",
     "prepack": "npm run build",
     "test": "SAMURAI_LOG_LEVEL=${SAMURAI_LOG_LEVEL:-warn} tsx --import ./scripts/test-tmp.mjs --test --test-timeout=10000 \"src/**/*.test.ts\"",
-    "test:browser": "SAMURAI_LOG_LEVEL=${SAMURAI_LOG_LEVEL:-warn} tsx --import ./scripts/test-tmp.mjs --test --test-concurrency=1 --test-timeout=60000 \"src/**/*.browser-test.ts\"",
+    "test:browser": "SAMURAI_LOG_LEVEL=${SAMURAI_LOG_LEVEL:-warn} tsx --import ./scripts/test-tmp.mjs --test --test-concurrency=1 --test-timeout=60000 ${SAMURAI_TEST_SHARD:+--test-shard=$SAMURAI_TEST_SHARD} \"src/**/*.browser-test.ts\"",
     "test:browser:chrome": "SAMURAI_TEST_BROWSER=chrome npm run test:browser",
     "test:cli": "tsx --import ./scripts/test-tmp.mjs --test --test-concurrency=1 \"src/**/*.cli-test.ts\""
   },