@itmetsam/samurai-framework 0.22.4 → 0.22.6

package/dist/config/config.js

@@ -8,6 +8,7 @@ import { validateForbidOnlyConfig } from "./forbid-only.js";
 import { validateRetriesConfig } from "./retries.js";
 import { validateFullyParallelConfig } from "./fully-parallel.js";
 import { validateWorkersConfig } from "./workers.js";
+import { validatePlansDirConfig } from "./plans-dir.js";
 import { validateWebServerConfig } from "./web-server-options.js";
 let activeProject;
 /** Makes `project` the one config, secrets, reports and downloads are resolved for; `undefined` ends it */
@@ -39,6 +40,7 @@ export function validateConfig(config) {
     validateGroupUse(config);
     validateEnvironmentUse(config);
     validateWebServerConfig(config);
+    validatePlansDirConfig(config);
 }
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
 export async function loadRawConfig() {

package/dist/config/defaults.d.ts

@@ -33,6 +33,8 @@ export declare const DEFAULT_VIEWPORT: {
 export declare const DEFAULT_DOWNLOADS_DIR = "result/downloads";
 /** The files folder, relative to the project */
 export declare const DEFAULT_FILES_DIR = "files";
+/** Where test plans are written, relative to the project */
+export declare const DEFAULT_PLANS_DIR = "plans";
 /** How many times a failing test is run again */
 export declare const DEFAULT_RETRIES = 0;
 /** Which page log entries go in the report: those of failed tests */

package/dist/config/defaults.js

@@ -30,6 +30,8 @@ export const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
 export const DEFAULT_DOWNLOADS_DIR = "result/downloads";
 /** The files folder, relative to the project */
 export const DEFAULT_FILES_DIR = "files";
+/** Where test plans are written, relative to the project */
+export const DEFAULT_PLANS_DIR = "plans";
 /** How many times a failing test is run again */
 export const DEFAULT_RETRIES = 0;
 /** Which page log entries go in the report: those of failed tests */

package/dist/config/plans-dir.d.ts

@@ -0,0 +1,3 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+/** Checks the `plansDir` key of a config: a folder inside the project. Throws an Error that names the key */
+export declare function validatePlansDirConfig(config: SamuraiTestConfig): void;

package/dist/config/plans-dir.js

@@ -0,0 +1,11 @@
+import path from "node:path";
+/** Checks the `plansDir` key of a config: a folder inside the project. Throws an Error that names the key */
+export function validatePlansDirConfig(config) {
+    const dir = config.plansDir;
+    if (dir === undefined)
+        return;
+    if (typeof dir !== "string" || dir.trim() === "")
+        throw new Error(`plansDir must be a folder name relative to the project, got ${JSON.stringify(dir)}`);
+    if (path.isAbsolute(dir) || path.normalize(dir).split(path.sep)[0] === "..")
+        throw new Error(`plansDir must be a folder inside the project, got "${dir}"`);
+}

package/dist/config/resolved-config.d.ts

@@ -57,6 +57,7 @@ export interface ResolvedConfig {
     } | null;
     downloadsDir: string;
     filesDir: string;
+    plansDir: string;
     logs: {
         capture: "off" | "failures" | "all";
         failOnPageError: boolean;

package/dist/config/resolved-config.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { browsersFor } from "./browsers-for.js";
 import { importConfigFile, projectConfig, validateConfig } from "./config.js";
-import { DEFAULT_COLLECT_BODIES, DEFAULT_COMMAND_TIMEOUT, DEFAULT_DOWNLOADS_DIR, DEFAULT_FAIL_ON_PAGE_ERROR, DEFAULT_FILES_DIR, DEFAULT_IDLE_TIME, DEFAULT_LOGS_CAPTURE, DEFAULT_MAX_BODY_SIZE, DEFAULT_NAVIGATION_TIMEOUT, DEFAULT_RETRIES, DEFAULT_ROUTE_TIMEOUT, DEFAULT_SRC_DIR, DEFAULT_TRACK_NETWORK, DEFAULT_VIEWPORT, DEFAULT_WAIT_UNTIL, } from "./defaults.js";
+import { DEFAULT_COLLECT_BODIES, DEFAULT_COMMAND_TIMEOUT, DEFAULT_DOWNLOADS_DIR, DEFAULT_FAIL_ON_PAGE_ERROR, DEFAULT_FILES_DIR, DEFAULT_PLANS_DIR, DEFAULT_IDLE_TIME, DEFAULT_LOGS_CAPTURE, DEFAULT_MAX_BODY_SIZE, DEFAULT_NAVIGATION_TIMEOUT, DEFAULT_RETRIES, DEFAULT_ROUTE_TIMEOUT, DEFAULT_SRC_DIR, DEFAULT_TRACK_NETWORK, DEFAULT_VIEWPORT, DEFAULT_WAIT_UNTIL, } from "./defaults.js";
 import { forbidsOnly } from "./forbid-only.js";
 import { IMPLICIT_ENVIRONMENT, resolveRunSettings, UnknownEnvironmentError, } from "./run-settings.js";
 import { resolveWorkers } from "./workers-option.js";
@@ -72,6 +72,7 @@ export function resolveConfig(config, options) {
         viewport: viewport === null ? null : { ...(viewport ?? DEFAULT_VIEWPORT) },
         downloadsDir: config.downloadsDir ?? DEFAULT_DOWNLOADS_DIR,
         filesDir: config.filesDir ?? DEFAULT_FILES_DIR,
+        plansDir: config.plansDir ?? DEFAULT_PLANS_DIR,
         logs: {
             capture: config.logs?.capture ?? DEFAULT_LOGS_CAPTURE,
             failOnPageError: config.logs?.failOnPageError ?? DEFAULT_FAIL_ON_PAGE_ERROR,

package/dist/recorder/spec-source.d.ts

@@ -34,6 +34,8 @@ export declare class SpecWriter {
     private readonly testIndex;
     readonly events: RecorderEvent[];
     constructor(source: string, file: string, testIndex: number);
+    /** Changes the source with `change` and writes the file when it differs; returns the new content */
+    rewrite(change: (source: string) => string): string;
     /** Applies the event, writes the file and returns the file's new content */
     write(event: RecorderEvent): string;
 }

package/dist/recorder/spec-source.js

@@ -74,6 +74,15 @@ export class SpecWriter {
         this.testIndex = testIndex;
         this.events = [];
     }
+    /** Changes the source with `change` and writes the file when it differs; returns the new content */
+    rewrite(change) {
+        const next = change(this.source);
+        if (next !== this.source) {
+            this.source = next;
+            writeFileSync(this.file, this.source);
+        }
+        return this.source;
+    }
     /** Applies the event, writes the file and returns the file's new content */
     write(event) {
         this.source = applyRecorderEvent(this.source, this.testIndex, event);

package/dist/runner/registry.js

@@ -7,7 +7,7 @@ import { validateUseOptions } from "../config/use-options.js";
 import { currentStepLog, currentTestInfo, infoFor, skipFromCondition, } from "./test-info.js";
 import { runStep } from "./steps.js";
 import { markTests } from "./test-annotations.js";
-import { validateTestIO } from "./test-io.js";
+import { validateTestAnnotations, validateTestIO } from "./test-io.js";
 import { addHook, addUse, currentSuite, enterSuite, leaveSuite, modifierOf, resetSuites, } from "./suite.js";
 import { configureSuite } from "./serial.js";
 const registered = [];
@@ -26,7 +26,7 @@ function openDescribe(file, title, fn, modifier, reason, mode) {
     }
 }
 function add({ file, line, column }, title, fn, modifier, extras = {}) {
-    const { reason, inputs, outputs, extension, expectedFail } = extras;
+    const { reason, inputs, outputs, annotations, extension, expectedFail } = extras;
     const suite = currentSuite(file);
     const titlePath = [...titlesOf(suite), title];
     const name = titlePath.join(" > ");
@@ -40,6 +40,7 @@ function add({ file, line, column }, title, fn, modifier, extras = {}) {
         ...modifierOf({ modifier, ...(reason !== undefined && { reason }) }, suite),
         ...(inputs && { inputs }),
         ...(outputs && { outputs }),
+        ...(annotations && { annotations }),
         ...(extension && { extension }),
         ...(expectedFail && { expectedFail }),
     });
@@ -65,6 +66,9 @@ function bodyAndOptions(call, title, second, third) {
         fn: fn,
         ...(reason !== undefined && { reason }),
         ...(options && call.startsWith("test") && validateTestIO(call, options)),
+        ...(options &&
+            call.startsWith("test") &&
+            validateTestAnnotations(call, options)),
     };
 }
 /** `test()` and `test.only()`: a reason only makes sense with skip and fixme */

package/dist/runner/test-info.js

@@ -19,6 +19,7 @@ export class TestInfoImpl {
         const { test } = from;
         this.title = test.titlePath[test.titlePath.length - 1] ?? test.name;
         this.titlePath = [...test.titlePath];
+        this.annotations = (test.annotations ?? []).map((a) => ({ ...a }));
         this.file = test.file;
         if (test.line !== undefined)
             this.line = test.line;

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

@@ -1,4 +1,4 @@
-import type { TestError, TestOptions, TestOutputs } from "../types/test.js";
+import type { TestAnnotation, TestError, TestOptions, TestOutputs } from "../types/test.js";
 import type { OutputSink } from "../wait/output-sink.js";
 /**
  * Checks the `inputs` and `outputs` of a `test()` options object and returns them, leaving out an empty or absent
@@ -8,6 +8,10 @@ export declare function validateTestIO(call: string, options: TestOptions): {
     inputs?: Record<string, string>;
     outputs?: string[];
 };
+/** Checks the `annotations` of a `test()` options object and returns them, or nothing when absent or empty */
+export declare function validateTestAnnotations(call: string, options: TestOptions): {
+    annotations?: TestAnnotation[];
+};
 /**
  * The `inputs` fixture: each declared input with the value the run supplies, else its default. Reading a
  * name the test did not declare throws.

package/dist/runner/test-io.js

@@ -45,6 +45,27 @@ export function validateTestIO(call, options) {
     }
     return result;
 }
+/** Checks the `annotations` of a `test()` options object and returns them, or nothing when absent or empty */
+export function validateTestAnnotations(call, options) {
+    const { annotations } = options;
+    if (annotations === undefined)
+        return {};
+    if (!Array.isArray(annotations))
+        throw new Error(`${call}(): annotations must be an array`);
+    for (const note of annotations) {
+        const entry = note;
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            throw new Error(`${call}(): each annotation must be an object with a type`);
+        if (typeof entry.type !== "string" || entry.type === "")
+            throw new Error(`${call}(): an annotation needs a non-empty type`);
+        if (entry.description !== undefined &&
+            typeof entry.description !== "string")
+            throw new Error(`${call}(): the description of annotation "${entry.type}" must be a string`);
+    }
+    return annotations.length > 0
+        ? { annotations: annotations.map((a) => ({ ...a })) }
+        : {};
+}
 /**
  * The `inputs` fixture: each declared input with the value the run supplies, else its default. Reading a
  * name the test did not declare throws.

package/dist/steps/edit.d.ts

@@ -1,3 +1,4 @@
+import type { TestAnnotation } from "../types/test.js";
 import type { Step, TestInput } from "./model.js";
 export type StepEdit = {
     op: "replace";
@@ -34,7 +35,7 @@ export type StepEdit = {
     test: number;
 }
 /**
- * Sets the test's `inputs` and `outputs` in its options object: a given list replaces that list, one left out
+ * Sets the test's `inputs`, `outputs` and `annotations` in its options object: a given list replaces that list, one left out
  * stays. When both end up empty the options object goes, unless it holds a `reason`
  */
  | {
@@ -42,6 +43,7 @@ export type StepEdit = {
     test: number;
     inputs?: TestInput[];
     outputs?: string[];
+    annotations?: TestAnnotation[];
 };
 /**
  * Applies one edit and returns the new source. Only the touched statement changes, plus the test's parameters

package/dist/steps/edit.js

@@ -158,7 +158,7 @@ export function applyEdit(source, edit) {
             return withStep(source, parsed, edit.step, (text, code) => insertCode(text, parsed, edit.index, code));
         case "declare": {
             let next = source;
-            for (const key of ["inputs", "outputs"]) {
+            for (const key of ["inputs", "outputs", "annotations"]) {
                 const list = edit[key];
                 if (list)
                     next = declareList(next, pickTest(next, edit.test), key, list);

package/dist/steps/model.d.ts

@@ -1,4 +1,4 @@
-import type { Modifier } from "../types/test.js";
+import type { Modifier, TestAnnotation } from "../types/test.js";
 /**
  * One call of a locator expression, as written in a spec: `page.getByRole("button", { name: "Save" })`.
  * A RegExp text or name is tested as written, so it never comes with `exact`, `match` or `ignoreCase`.
@@ -264,6 +264,8 @@ export interface ParsedTest {
     inputs?: TestInput[];
     /** The `outputs` of the test's options object; undefined without the key */
     outputs?: string[];
+    /** The `annotations` of the test's options object; undefined without the key or with an empty list */
+    annotations?: TestAnnotation[];
     /** The range of the test's options object (`test(title, { … }, fn)`), when it has one */
     options?: {
         start: number;

package/dist/steps/parse.js

@@ -137,7 +137,7 @@ export function parseSpecFile(source) {
                 return;
             }
             const { callback, options = {}, range } = args;
-            const { reason, inputs, outputs } = options;
+            const { reason, inputs, outputs, annotations } = options;
             const body = callbackBody(callback);
             if (!body) {
                 unparsed.push(unreadable(node, kind, "not-inline"));
@@ -161,6 +161,7 @@ export function parseSpecFile(source) {
                     ...effectiveMark(mark, describes),
                     ...(inputs && { inputs }),
                     ...(outputs && { outputs }),
+                    ...(annotations && { annotations }),
                     ...(range && { options: range }),
                     titleEnd: node.arguments[0].end,
                 });

package/dist/steps/test-options.d.ts

@@ -1,13 +1,15 @@
 import ts from "typescript";
-import type { Modifier } from "../types/test.js";
+import type { Modifier, TestAnnotation } from "../types/test.js";
 import type { ParsedTest, TestInput } from "./model.js";
 /** What a `test()` or `describe()` options object says, as far as the codec reads it */
 export interface TestOptionsRead {
     reason?: string;
     inputs?: TestInput[];
     outputs?: string[];
+    annotations?: TestAnnotation[];
 }
-type ListKey = "inputs" | "outputs";
+type ListKey = "inputs" | "outputs" | "annotations";
+type ListValue = TestInput[] | string[] | TestAnnotation[];
 /**
  * The options object of a test or describe call: a describe takes only `reason`, a test also `inputs` and
  * `outputs`. Undefined when the object isn't a literal the codec can read, so the call is left unparsed. An
@@ -21,5 +23,5 @@ export declare function readTestOptions(node: ts.Expression, kind: "test" | "des
  * the object, its layout and a `reason`, stays as it is; an unchanged list leaves the source as it is. Throws for
  * names the runtime rejects, before writing
  */
-export declare function declareList(source: string, parsed: ParsedTest, key: ListKey, list: TestInput[] | string[]): string;
+export declare function declareList(source: string, parsed: ParsedTest, key: ListKey, list: ListValue): string;
 export {};

package/dist/steps/test-options.js

@@ -33,6 +33,35 @@ function readOutputs(node) {
         ? names
         : undefined;
 }
+/** `[{ type: "plan", description: "…" }, …]`; undefined for anything but string literals under those two keys */
+function readAnnotations(node) {
+    if (!ts.isArrayLiteralExpression(node))
+        return undefined;
+    const notes = [];
+    for (const element of node.elements) {
+        if (!ts.isObjectLiteralExpression(element))
+            return undefined;
+        const note = {};
+        for (const property of element.properties) {
+            if (!ts.isPropertyAssignment(property))
+                return undefined;
+            const key = keyOf(property.name);
+            const value = stringOf(property.initializer);
+            if (value === undefined)
+                return undefined;
+            if (key === "type")
+                note.type = value;
+            else if (key === "description")
+                note.description = value;
+            else
+                return undefined;
+        }
+        if (note.type === undefined || note.type === "")
+            return undefined;
+        notes.push(note);
+    }
+    return notes;
+}
 /**
  * The options object of a test or describe call: a describe takes only `reason`, a test also `inputs` and
  * `outputs`. Undefined when the object isn't a literal the codec can read, so the call is left unparsed. An
@@ -67,13 +96,27 @@ export function readTestOptions(node, kind, modifier) {
             if (outputs.length > 0)
                 read.outputs = outputs;
         }
+        else if (kind === "test" && key === "annotations") {
+            const annotations = readAnnotations(value);
+            if (!annotations)
+                return undefined;
+            if (annotations.length > 0)
+                read.annotations = annotations;
+        }
         else
             return undefined;
     }
     return read;
 }
 const str = (value) => JSON.stringify(value);
+function annotationToSource(note) {
+    return note.description === undefined
+        ? `{ type: ${str(note.type)} }`
+        : `{ type: ${str(note.type)}, description: ${str(note.description)} }`;
+}
 function listToSource(key, list) {
+    if (key === "annotations")
+        return `[${list.map(annotationToSource).join(", ")}]`;
     if (key === "outputs")
         return `[${list.map(str).join(", ")}]`;
     const entries = list.map(({ name, default: value }) => `${IDENTIFIER.test(name) ? name : str(name)}: ${str(value)}`);
@@ -82,6 +125,12 @@ function listToSource(key, list) {
 const sameList = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 /** Throws for a list the runtime's `test()` would reject: a name that isn't valid, a name twice, a default that isn't text */
 function checkList(key, list) {
+    if (key === "annotations") {
+        for (const note of list)
+            if (typeof note.type !== "string" || note.type === "")
+                throw new Error(`applyEdit(): an annotation needs a non-empty type`);
+        return;
+    }
     const kind = key === "inputs" ? "input" : "output";
     const seen = new Set();
     for (const entry of list) {

package/dist/types/config.d.ts

@@ -204,6 +204,12 @@ export interface SamuraiTestConfig {
    * @default "files"
    */
   filesDir?: string;
+  /**
+   * Folder, relative to the project folder, where test plans are kept; `samurai plan "<goal>"` without `--out`
+   * writes `<plansDir>/<slug-of-goal>.plan.md`
+   * @default "plans"
+   */
+  plansDir?: string;
   /**
    * The AI agent (`samurai generate`). `model` is a `provider:name` pair, such as `anthropic:claude-sonnet-4-5`;
    * never a key (keys come from the environment). The `--model` flag and `SAMURAI_AI_MODEL` win over it

package/dist/types/test.d.ts

@@ -170,6 +170,8 @@ export interface TestOptions extends TestDetails {
   inputs?: Record<string, string>;
   /** Names of the text values the test saves for later tests to use */
   outputs?: string[];
+  /** Notes on the test, such as `{ type: "plan", description: "plans/pay.plan.md" }`; the report lists them first */
+  annotations?: TestAnnotation[];
 }
 
 /** Runs before or after each test of a suite, in the test's browser, with the test's fixtures */
@@ -225,6 +227,8 @@ export interface RegisteredTestCase extends TestCaseBase {
   inputs?: Record<string, string>;
   /** The names of the outputs the test declared */
   outputs?: string[];
+  /** The annotations the test declared; every run of the test starts with them */
+  annotations?: TestAnnotation[];
   /** Registered with `test.fail("title", fn)`: expected to fail; `description` is the `{ reason }` given */
   expectedFail?: { description?: string };
   /** The custom fixtures of the `test` it was written with (`test.extend()`); absent for the plain `test` */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.22.4",
+  "version": "0.22.6",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {