@itmetsam/samurai-framework 0.15.1 → 0.15.2

package/dist/api.d.ts

@@ -2,5 +2,5 @@ export { test, describe, beforeEach, afterEach, beforeAll, afterAll, } from "./r
 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 { AllHookFixtures, TestFixtures } from "./types/test.js";
+export type { AllHookFixtures, TestDetails, TestFixtures, } from "./types/test.js";
 export { generatedFile, type GeneratedFile, type FileInput, } from "./browser/generated-files.js";

package/dist/cli/main.js

@@ -60,7 +60,7 @@ export async function main(argv, io) {
                 io.out(`${JSON.stringify(tests, null, 2)}\n`);
             else
                 for (const found of tests)
-                    io.out(`${found.name}${found.modifier ? ` [${found.modifier}]` : ""}\n    ${found.file}\n`);
+                    io.out(`${found.name}${found.modifier ? ` [${found.modifier}${found.reason ? `: ${found.reason}` : ""}]` : ""}\n    ${found.file}\n`);
             return 0;
         }
         const human = values.json

package/dist/runner/pooled-run.js

@@ -70,9 +70,9 @@ export function poolMode(input) {
 export async function runPooled(pool, planned, items, reporter, signal) {
     reporter.setOrder(planned);
     for (const { test, browser } of planned) {
-        const annotation = staticSkip(test);
-        if (annotation)
-            reporter.onTestSkipped(test, browser, { annotation });
+        const skip = staticSkip(test);
+        if (skip)
+            reporter.onTestSkipped(test, browser, skip);
     }
     const started = new Set();
     const ended = new Set();

package/dist/runner/registry.d.ts

@@ -1,4 +1,4 @@
-import type { AllHook, EachHook, RegisteredTestCase, TestCaseBase } from "../types/test.js";
+import type { AllHook, EachHook, RegisteredTestCase, TestCaseBase, TestDetails } from "../types/test.js";
 type Body = TestCaseBase["function"];
 /** `test(title, fn)`, `test.skip(title, fn)`, `test.skip(condition, reason)` and the other forms */
 export interface TestFunction {
@@ -10,16 +10,25 @@ export interface TestFunction {
     /** Runs only this test (and the other `only` ones) */
     only(title: string, fn: Body): void;
 }
-/** With a title and a body it registers a skipped test; with a condition it skips the running test when the condition is true */
+/**
+ * With a title and a body it registers a skipped test, `{ reason }` saying why; with a condition it skips the
+ * running test when the condition is true
+ */
 interface SkipFunction {
     (title: string, fn: Body): void;
+    (title: string, details: TestDetails, fn: Body): void;
     (condition: boolean, reason?: string): void;
 }
+/** `describe.skip` and `describe.fixme`: every test inside gets the modifier, and `{ reason }` says why */
+interface DescribeSkipFunction {
+    (title: string, fn: () => void): void;
+    (title: string, details: TestDetails, fn: () => void): void;
+}
 /** `describe(title, fn)` and the same with a modifier on every test inside */
 export interface DescribeFunction {
     (title: string, fn: () => void): void;
-    skip(title: string, fn: () => void): void;
-    fixme(title: string, fn: () => void): void;
+    skip: DescribeSkipFunction;
+    fixme: DescribeSkipFunction;
     only(title: string, fn: () => void): void;
 }
 export declare const test: TestFunction;

package/dist/runner/registry.js

@@ -4,8 +4,8 @@ import { SkipSignal } from "./skip.js";
 import { addHook, currentSuite, enterSuite, leaveSuite, modifierOf, resetSuites, } from "./suite.js";
 const registered = [];
 /** Runs `fn` as the `describe` block `title`, under `modifier` when there is one. `fn` runs immediately and must be synchronous. */
-function openDescribe(file, title, fn, modifier) {
-    enterSuite(file, title, modifier);
+function openDescribe(file, title, fn, modifier, reason) {
+    enterSuite(file, title, modifier, reason);
     try {
         const result = fn();
         if (result instanceof Promise) {
@@ -17,18 +17,17 @@ function openDescribe(file, title, fn, modifier) {
         leaveSuite();
     }
 }
-function add(file, title, fn, modifier) {
+function add(file, title, fn, modifier, reason) {
     const suite = currentSuite(file);
     const titlePath = [...titlesOf(suite), title];
     const name = titlePath.join(" > ");
-    const effective = modifierOf(modifier, suite);
     registered.push({
         name,
         titlePath,
         function: fn,
         file,
         suite,
-        ...(effective && { modifier: effective }),
+        ...modifierOf({ modifier, ...(reason !== undefined && { reason }) }, suite),
     });
     logger.debug("Registered test %s", name);
 }
@@ -40,26 +39,44 @@ function titlesOf(suite) {
             titles.unshift(s.title);
     return titles;
 }
+/** The body and `{ reason }` of `(title, fn)` and `(title, details, fn)` */
+function bodyAndReason(call, title, second, third) {
+    const [details, fn] = typeof second === "function"
+        ? [undefined, second]
+        : [second, third];
+    if (typeof fn !== "function")
+        throw new TypeError(`${call}(${JSON.stringify(title)}) needs a function as its last argument`);
+    const reason = details?.reason;
+    return { fn: fn, ...(reason !== undefined && { reason }) };
+}
 /** `test.skip` and `test.fixme`: a title and a body register a test with the modifier; a condition skips the running test */
 function skipping(annotation) {
-    return ((first, second) => {
+    return ((first, second, third) => {
         if (typeof first === "string") {
+            const { fn, reason } = bodyAndReason(`test.${annotation}`, first, second, third);
             // Frames: Error, callerFile, this function, the spec
-            add(callerFile(), first, second, annotation);
+            add(callerFile(), first, fn, annotation, reason);
             return;
         }
         if (first)
             throw new SkipSignal(annotation, second);
     });
 }
+/** `describe.skip` and `describe.fixme`, with or without `{ reason }` */
+function describeSkipping(annotation) {
+    return ((title, second, third) => {
+        const { fn, reason } = bodyAndReason(`describe.${annotation}`, title, second, third);
+        openDescribe(callerFile(), title, fn, annotation, reason);
+    });
+}
 export const test = Object.assign((title, fn) => add(callerFile(), title, fn), {
     skip: skipping("skip"),
     fixme: skipping("fixme"),
     only: (title, fn) => add(callerFile(), title, fn, "only"),
 });
 export const describe = Object.assign((title, fn) => openDescribe(callerFile(), title, fn), {
-    skip: (title, fn) => openDescribe(callerFile(), title, fn, "skip"),
-    fixme: (title, fn) => openDescribe(callerFile(), title, fn, "fixme"),
+    skip: describeSkipping("skip"),
+    fixme: describeSkipping("fixme"),
     only: (title, fn) => openDescribe(callerFile(), title, fn, "only"),
 });
 /** Runs before each test of the `describe` block it is written in (of the file, at the top level) */

package/dist/runner/run-test.js

@@ -67,7 +67,7 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
     // A test marked skip or fixme never runs, whoever asked for it (a flow's test node, a worker)
     const marked = staticSkip(test);
     if (marked) {
-        reporter.onTestSkipped(test, browserName, { annotation: marked });
+        reporter.onTestSkipped(test, browserName, marked);
         return;
     }
     logger.verbose("Starting test: %s in %s", test.name, browserName);

package/dist/runner/run.d.ts

@@ -21,6 +21,8 @@ export interface FoundTest {
     file: string;
     /** `skip` or `fixme` (not run), or `only` (focused); absent for a plain test. A modifier on a `describe` counts. */
     modifier?: Modifier;
+    /** The `{ reason }` given with the `skip` or `fixme` that applies */
+    reason?: string;
 }
 /** Imports the project's specs without running anything and lists the tests the options select */
 export declare function listTests(options?: RunTestsOptions): Promise<FoundTest[]>;

package/dist/runner/run.js

@@ -35,10 +35,11 @@ export async function runTests(options = {}) {
 }
 /** Imports the project's specs without running anything and lists the tests the options select */
 export async function listTests(options = {}) {
-    return inProject(options, async (runner) => (await runner.register()).map(({ name, file, modifier }) => ({
+    return inProject(options, async (runner) => (await runner.register()).map(({ name, file, modifier, reason }) => ({
         name,
         file,
         ...(modifier && { modifier }),
+        ...(reason !== undefined && { reason }),
     })));
 }
 /** Imports the project's specs without running anything and lists the config's groups with the tests each holds */

package/dist/runner/skip.d.ts

@@ -1,4 +1,5 @@
 import type { RegisteredTestCase } from "../types/test.js";
+import type { TestSkip } from "./reporter.js";
 /** Thrown by `test.skip(condition, reason)` and `test.fixme(condition, reason)` inside a test: the test ends as skipped */
 export declare class SkipSignal extends Error {
     readonly annotation: "skip" | "fixme";
@@ -7,4 +8,4 @@ export declare class SkipSignal extends Error {
 }
 export declare function isSkipSignal(error: unknown): error is SkipSignal;
 /** Why a test does not run at all: it is marked `skip` or `fixme`, itself or by a `describe` around it */
-export declare function staticSkip(test: Pick<RegisteredTestCase, "modifier">): "skip" | "fixme" | undefined;
+export declare function staticSkip(test: Pick<RegisteredTestCase, "modifier" | "reason">): TestSkip | undefined;

package/dist/runner/skip.js

@@ -12,7 +12,8 @@ export function isSkipSignal(error) {
 }
 /** Why a test does not run at all: it is marked `skip` or `fixme`, itself or by a `describe` around it */
 export function staticSkip(test) {
-    return test.modifier === "skip" || test.modifier === "fixme"
-        ? test.modifier
+    const { modifier, reason } = test;
+    return modifier === "skip" || modifier === "fixme"
+        ? { annotation: modifier, ...(reason !== undefined && { reason }) }
         : undefined;
 }

package/dist/runner/suite.d.ts

@@ -1,19 +1,25 @@
 import type { EachHook, Modifier, Suite } from "../types/test.js";
 /** The four hook lists a suite can hold */
 export type HookKind = "beforeEach" | "afterEach" | "beforeAll" | "afterAll";
-export declare function newSuite(title?: string, parent?: Suite, modifier?: Modifier): Suite;
+export declare function newSuite(title?: string, parent?: Suite, modifier?: Modifier, reason?: string): Suite;
 /** The suite a test or hook written now belongs to: the innermost open `describe`, else the file's own */
 export declare function currentSuite(file: string): Suite;
 /** Opens a `describe` block under the current suite; `leaveSuite` closes it */
-export declare function enterSuite(file: string, title: string, modifier?: Modifier): Suite;
+export declare function enterSuite(file: string, title: string, modifier?: Modifier, reason?: string): Suite;
 export declare function leaveSuite(): void;
 /** Forgets every suite: a run registers its specs afresh */
 export declare function resetSuites(): void;
 /**
  * What applies to a test: the innermost `skip` or `fixme` (the test's own, then its suites', inside out), else
- * `only` when the test or any suite around it is focused. A skip beats a focus.
+ * `only` when the test or any suite around it is focused. A skip beats a focus. The reason comes with the skip
+ * or fixme that applies.
  */
-export declare function modifierOf(own: Modifier | undefined, suite: Suite): Modifier | undefined;
+export declare function modifierOf(own: Mark, suite: Suite): Mark;
+/** A modifier and the reason given with it */
+export interface Mark {
+    modifier?: Modifier;
+    reason?: string;
+}
 /** The suites from the file's root down to `suite` */
 export declare function suiteChain(suite: Suite): Suite[];
 /** The `beforeEach` hooks of a test: outermost suite first, in the order they were written */

package/dist/runner/suite.js

@@ -2,11 +2,12 @@
 const roots = new Map();
 /** The `describe` blocks being registered, outermost first */
 const open = [];
-export function newSuite(title, parent, modifier) {
+export function newSuite(title, parent, modifier, reason) {
     return {
         ...(title !== undefined && { title }),
         ...(parent && { parent }),
         ...(modifier && { modifier }),
+        ...(reason !== undefined && { reason }),
     };
 }
 /** The suite a test or hook written now belongs to: the innermost open `describe`, else the file's own */
@@ -22,8 +23,8 @@ export function currentSuite(file) {
     return root;
 }
 /** Opens a `describe` block under the current suite; `leaveSuite` closes it */
-export function enterSuite(file, title, modifier) {
-    const suite = newSuite(title, currentSuite(file), modifier);
+export function enterSuite(file, title, modifier, reason) {
+    const suite = newSuite(title, currentSuite(file), modifier, reason);
     open.push(suite);
     return suite;
 }
@@ -37,18 +38,26 @@ export function resetSuites() {
 }
 /**
  * What applies to a test: the innermost `skip` or `fixme` (the test's own, then its suites', inside out), else
- * `only` when the test or any suite around it is focused. A skip beats a focus.
+ * `only` when the test or any suite around it is focused. A skip beats a focus. The reason comes with the skip
+ * or fixme that applies.
  */
 export function modifierOf(own, suite) {
-    let focused = own === "only";
-    let found = own === "only" ? undefined : own;
-    for (let s = suite; s && !found; s = s.parent) {
+    if (own.modifier === "skip" || own.modifier === "fixme")
+        return markOf(own);
+    let focused = own.modifier === "only";
+    for (let s = suite; s; s = s.parent) {
         if (s.modifier === "only")
             focused = true;
-        else
-            found = s.modifier;
+        else if (s.modifier)
+            return markOf(s);
     }
-    return found ?? (focused ? "only" : undefined);
+    return focused ? { modifier: "only" } : {};
+}
+function markOf({ modifier, reason }) {
+    return {
+        ...(modifier && { modifier }),
+        ...(reason !== undefined && { reason }),
+    };
 }
 /** The suites from the file's root down to `suite` */
 export function suiteChain(suite) {

package/dist/runner/test-runner.js

@@ -123,9 +123,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/model.d.ts

@@ -158,4 +158,6 @@ 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;
 }

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,11 +57,33 @@ 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) {
@@ -73,24 +95,28 @@ export function parseSpec(source) {
             : undefined;
         if (ts.isCallExpression(node) && callee) {
             const title = stringOf(node.arguments[0]);
-            const body = callbackBody(node.arguments[1]);
+            const { callback, reason } = callbackOf(node, callee.modifier);
+            const body = callbackBody(callback);
+            const mark = {
+                ...(callee.modifier && { modifier: callee.modifier }),
+                ...(reason !== undefined && { reason }),
+            };
             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 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 }),
+                    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]));
+                ts.forEachChild(body, (child) => visit(child, [...titles, title], [...describes, mark]));
                 return;
             }
         }

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.15.2",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {