@itmetsam/samurai-framework 0.16.0 → 0.17.0

package/dist/capabilities.d.ts

@@ -25,8 +25,12 @@ export declare const CAPABILITIES: {
     readonly testIds: true;
     /** `loadConfig` from `./project`: the config with every default applied, the way a run uses it. */
     readonly resolvedConfig: true;
+    /** `loadConfig({ written: true })`: the config as written next to the resolved one, and `writtenConfig`. */
+    readonly writtenConfig: true;
     /** The recorder's first `onStatus` call, `{ state: "recording", toolbar }`, right after it starts, and a `RecordResult` with every field always present. */
     readonly recorderStartStatus: true;
+    /** `outputDir` on `runTests` and `runFlowInProject`: a folder per run for the report and the screenshots. */
+    readonly outputDir: true;
 };
 /** The shape of {@link CAPABILITIES}. */
 export type Capabilities = typeof CAPABILITIES;

package/dist/capabilities.js

@@ -25,6 +25,10 @@ export const CAPABILITIES = {
     testIds: true,
     /** `loadConfig` from `./project`: the config with every default applied, the way a run uses it. */
     resolvedConfig: true,
+    /** `loadConfig({ written: true })`: the config as written next to the resolved one, and `writtenConfig`. */
+    writtenConfig: true,
     /** The recorder's first `onStatus` call, `{ state: "recording", toolbar }`, right after it starts, and a `RecordResult` with every field always present. */
     recorderStartStatus: true,
+    /** `outputDir` on `runTests` and `runFlowInProject`: a folder per run for the report and the screenshots. */
+    outputDir: true,
 };

package/dist/config/config.d.ts

@@ -21,6 +21,8 @@ export declare function browsersDir(): string;
 export declare function validateConfig(config: SamuraiTestConfig): void;
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
 export declare function loadRawConfig(): Promise<SamuraiTestConfig>;
+/** The default export of `samurai.config.ts` in `dir`, not validated */
+export declare function importConfigFile(dir: string): Promise<SamuraiTestConfig>;
 /** A project's config without keeping the project active (`withProject` is one at a time): the given one, else its samurai.config.ts */
 export declare function projectConfig(options: {
     projectDir?: string;

package/dist/config/config.js

@@ -37,13 +37,18 @@ export async function loadRawConfig() {
         validateConfig(activeProject.config);
         return activeProject.config;
     }
-    const configUrl = path.join(projectDir(), "samurai.config.ts");
+    const config = await importConfigFile(projectDir());
+    validateConfig(config);
+    return config;
+}
+/** The default export of `samurai.config.ts` in `dir`, not validated */
+export async function importConfigFile(dir) {
+    const configUrl = path.join(dir, "samurai.config.ts");
     logger.debug("Reading config from: %s", configUrl);
     const config = (await import(pathToFileURL(configUrl).href));
     if (!config.default) {
         throw new Error("samurai.config.ts does not export defineConfig as default!");
     }
-    validateConfig(config.default);
     return config.default;
 }
 /** A project's config without keeping the project active (`withProject` is one at a time): the given one, else its samurai.config.ts */

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

@@ -91,6 +91,26 @@ export declare function resolveConfig(config: SamuraiTestConfig, options: {
     projectDir: string;
     env: Env;
 }): ResolvedConfig;
+/**
+ * `samurai.config.ts` as the file states it, as JSON: nothing filled in (an absent `workers` stays absent, a config
+ * without `environments` has none), `logs.ignoreErrors` patterns as {@link ResolvedIgnoreError}, and `steps` as
+ * their kinds. For showing and editing the config; {@link ResolvedConfig} is what a run uses.
+ */
+export type WrittenConfig = Omit<SamuraiTestConfig, "logs" | "steps"> & {
+    logs?: Omit<NonNullable<SamuraiTestConfig["logs"]>, "ignoreErrors"> & {
+        ignoreErrors?: ResolvedIgnoreError[];
+    };
+    steps?: string[];
+};
+/** Both views of a config: as written, and resolved; `resolved` is absent, and `error` says why, when the config is invalid */
+export interface ConfigViews {
+    written: WrittenConfig;
+    resolved?: ResolvedConfig;
+    /** The error a run would throw for this config */
+    error?: string;
+}
+/** The config as written, as plain JSON (see {@link WrittenConfig}). Pure: reads no files. */
+export declare function writtenConfig(config: SamuraiTestConfig): WrittenConfig;
 /**
  * A project's `samurai.config.ts` with every default applied, the way a run uses it (see {@link ResolvedConfig}).
  * Leaves no project active. The caller registers `tsx` first (the framework does not), so the config file can be
@@ -98,9 +118,17 @@ export declare function resolveConfig(config: SamuraiTestConfig, options: {
  * (Node caches it): a later edit to `samurai.config.ts` is seen only in a new process.
  * @param options.projectDir The project folder. @default the working directory
  * @param options.env Where `CI` is read from. @default `process.env`
+ * @param options.written Also return the config as written (see {@link ConfigViews})
  */
 export declare function loadConfig(options?: {
     projectDir?: string;
     env?: Env;
+    written?: false;
 }): Promise<ResolvedConfig>;
+/** With `written: true`: the config as written next to the resolved one (see {@link ConfigViews}); an invalid config is reported in `error`, not thrown */
+export declare function loadConfig(options: {
+    projectDir?: string;
+    env?: Env;
+    written: true;
+}): Promise<ConfigViews>;
 export {};

package/dist/config/resolved-config.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { browsersFor } from "./browsers-for.js";
-import { projectConfig, validateConfig } from "./config.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 { forbidsOnly } from "./forbid-only.js";
 import { IMPLICIT_ENVIRONMENT, resolveRunSettings, UnknownEnvironmentError, } from "./run-settings.js";
@@ -97,16 +97,39 @@ export function resolveConfig(config, options) {
         steps: (config.steps ?? []).map((step) => step.kind),
     };
 }
-/**
- * A project's `samurai.config.ts` with every default applied, the way a run uses it (see {@link ResolvedConfig}).
- * Leaves no project active. The caller registers `tsx` first (the framework does not), so the config file can be
- * imported; an app does that in the child process that calls this. The config module is imported once per process
- * (Node caches it): a later edit to `samurai.config.ts` is seen only in a new process.
- * @param options.projectDir The project folder. @default the working directory
- * @param options.env Where `CI` is read from. @default `process.env`
- */
+/** The config as written, as plain JSON (see {@link WrittenConfig}). Pure: reads no files. */
+export function writtenConfig(config) {
+    const { logs, steps, ...rest } = config;
+    const { ignoreErrors, ...logSettings } = logs ?? {};
+    const written = {
+        ...rest,
+        ...(logs && {
+            logs: {
+                ...logSettings,
+                ...(ignoreErrors && { ignoreErrors: ignoreErrorsOf(ignoreErrors) }),
+            },
+        }),
+        ...(steps && { steps: steps.map((step) => step.kind) }),
+    };
+    // A JSON copy: shares nothing with the config, and leaves out what JSON can't carry
+    return JSON.parse(JSON.stringify(written));
+}
 export async function loadConfig(options = {}) {
     const projectDir = path.resolve(options.projectDir ?? process.cwd());
-    const config = await projectConfig({ projectDir });
-    return resolveConfig(config, { projectDir, env: options.env ?? process.env });
+    const env = options.env ?? process.env;
+    if (!options.written) {
+        const config = await projectConfig({ projectDir });
+        return resolveConfig(config, { projectDir, env });
+    }
+    const config = await importConfigFile(projectDir);
+    const written = writtenConfig(config);
+    try {
+        return { written, resolved: resolveConfig(config, { projectDir, env }) };
+    }
+    catch (error) {
+        return {
+            written,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
 }

package/dist/flows/run/project-options.d.ts

@@ -20,6 +20,8 @@ export interface RunFlowInProjectOptions extends ProjectOptions {
     /** `"fail"` (default): a flow with a node that can't run is refused. `"skip"`: those nodes are skipped. */
     unsupported?: "fail" | "skip";
     port?: number;
+    /** The folder the tests' named screenshots go in, instead of `<project>/result` (see `runTests`). Relative to the project folder */
+    outputDir?: string;
     /**
      * How many worker processes the tests of the whole run share: a number, or a percentage like `"50%"`. Unset
      * takes `SAMURAI_WORKERS` (`workersEnv`), then the config's `workers`, then half the CPUs. 1 runs each Test

package/dist/flows/run/project.js

@@ -176,6 +176,9 @@ async function walkFlowInProject(options) {
                 ...(options.headless !== undefined && {
                     headless: options.headless,
                 }),
+                ...(options.outputDir !== undefined && {
+                    outputDir: options.outputDir,
+                }),
                 files,
                 basePort: options.port ?? DEFAULT_PORT,
                 ...(retries > 0 && { retries }),
@@ -214,6 +217,9 @@ async function walkFlowInProject(options) {
                     files: [...new Set(tests.map((t) => t.file))],
                     testNames: tests.map((t) => t.name),
                     reportPath: false,
+                    ...(options.outputDir !== undefined && {
+                        outputDir: options.outputDir,
+                    }),
                     signal,
                     onEvent,
                 });

package/dist/project/index.d.ts

@@ -2,4 +2,4 @@ export { ConfigEditError, editConfig, hasConfigPath, propertyText, type ConfigVa
 export { addVariable, ExistsError, VARIABLE_NAME } from "./variables.js";
 export { isGitIgnored, SECRET_NAME, setSecret } from "./secrets-file.js";
 export { cleanFileName, filesFolder, isFolderIgnored, RECORD_LIMIT, storeFile, } from "./files-store.js";
-export { loadConfig, type ResolvedConfig, type ResolvedEnvironment, type ResolvedIgnoreError, } from "../config/resolved-config.js";
+export { loadConfig, writtenConfig, type ConfigViews, type ResolvedConfig, type ResolvedEnvironment, type ResolvedIgnoreError, type WrittenConfig, } from "../config/resolved-config.js";

package/dist/project/index.js

@@ -2,4 +2,4 @@ export { ConfigEditError, editConfig, hasConfigPath, propertyText, } from "./con
 export { addVariable, ExistsError, VARIABLE_NAME } from "./variables.js";
 export { isGitIgnored, SECRET_NAME, setSecret } from "./secrets-file.js";
 export { cleanFileName, filesFolder, isFolderIgnored, RECORD_LIMIT, storeFile, } from "./files-store.js";
-export { loadConfig, } from "../config/resolved-config.js";
+export { loadConfig, writtenConfig, } from "../config/resolved-config.js";

package/dist/runner/options.d.ts

@@ -28,7 +28,13 @@ export interface RunnerOptions {
     headless?: boolean;
     /** Remote debugging port of the browser. @default DEFAULT_PORT (9223) */
     port?: number;
-    /** Where the report is written; `false` writes none. @default `<project>/result/report.json` */
+    /**
+     * The folder for what the run writes, instead of `<project>/result`: `report.json` and the named screenshots
+     * (their paths in the results are relative to it). Relative to the project folder.
+     * @default `<project>/result`
+     */
+    outputDir?: string;
+    /** Where the report is written; `false` writes none. Beats `outputDir` for the report. @default `report.json` in `outputDir` */
     reportPath?: string | false;
     /** Receives start and end of the run and of every test, as they happen */
     onEvent?: (event: RunEvent) => void;

package/dist/runner/output.d.ts

@@ -0,0 +1,6 @@
+import type { RunnerOptions } from "./options.js";
+/** Where a run writes: the folder its screenshots go in, and its report (`false`: none) */
+export declare function runOutput(options: Pick<RunnerOptions, "outputDir" | "reportPath">, projectDir: string): {
+    resultDir: string;
+    report: string | false;
+};

package/dist/runner/output.js

@@ -0,0 +1,14 @@
+import path from "node:path";
+/** Where a run writes: the folder its screenshots go in, and its report (`false`: none) */
+export function runOutput(options, projectDir) {
+    const { outputDir, reportPath } = options;
+    const resultDir = outputDir !== undefined
+        ? path.resolve(projectDir, outputDir)
+        : typeof reportPath === "string"
+            ? path.dirname(reportPath)
+            : path.join(projectDir, "result");
+    return {
+        resultDir,
+        report: reportPath ?? path.join(resultDir, "report.json"),
+    };
+}

package/dist/runner/run-test.js

@@ -1,4 +1,3 @@
-import path from "path";
 import { takePendingAssertions } from "../assert/expect.js";
 import { Browser } from "../browser/browser.js";
 import { Evidence } from "../browser/evidence.js";
@@ -11,6 +10,7 @@ import { judgePageLogs } from "./page-logs-report.js";
 import { DEFAULT_PORT } from "./ports.js";
 import { runWithEachHooks } from "./hooks.js";
 import { isSkipSignal, staticSkip } from "./skip.js";
+import { runOutput } from "./output.js";
 import { testDirOf } from "./test-dir.js";
 import { toTestError } from "./test-error.js";
 /**
@@ -75,10 +75,7 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
     const outcome = new TestOutcome(reporter, test, browserName);
     const { settings, secrets } = run;
     const timeout = settings.timeout;
-    const { reportPath } = options;
-    const resultDir = typeof reportPath === "string"
-        ? path.dirname(reportPath)
-        : path.join(projectDir(), "result");
+    const { resultDir } = runOutput(options, projectDir());
     let browser;
     let page;
     let timeoutTimer;

package/dist/runner/test-runner.js

@@ -17,6 +17,7 @@ import { browsersOfRun, loadSpecs, selectTests } from "./select.js";
 import { resolveRetries } from "./retries-option.js";
 import { runWithRetries } from "./retry.js";
 import { resolveWorkers } from "../config/workers-option.js";
+import { runOutput } from "./output.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 */
@@ -61,7 +62,7 @@ export default class TestRunner {
      * was also written to the report. With more than one worker the tests run at the same time in worker processes.
      */
     async start() {
-        const { reportPath, onEvent, signal } = this.options;
+        const { 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 loadRawConfig();
@@ -72,7 +73,7 @@ export default class TestRunner {
         const reporter = new TestReporter({
             environment: this.run.settings.environment,
             browsers,
-            ...(reportPath !== undefined && { output: reportPath }),
+            output: runOutput(this.options, projectDir()).report,
             ...(onEvent && { onEvent }),
         });
         // How the run goes is settled first: a bad `workers` is an error before any browser starts
@@ -159,7 +160,7 @@ export default class TestRunner {
     /** The pool of a run: up to `workers` worker processes that read the same project and settings as this run */
     createPool(workers, retries) {
         const { settings } = this.run;
-        const { reportPath, headless, port } = this.options;
+        const { reportPath, outputDir, headless, port } = this.options;
         const options = {
             workers,
             factory: processWorkerFactory(),
@@ -173,6 +174,7 @@ export default class TestRunner {
                 expectTimeout: settings.expectTimeout,
                 ...(headless !== undefined && { headless }),
                 ...(typeof reportPath === "string" && { reportPath }),
+                ...(outputDir !== undefined && { outputDir }),
                 files: this.testFiles,
                 basePort: port ?? DEFAULT_PORT,
                 ...(retries > 0 && { retries }),

package/dist/runner/worker-protocol.d.ts

@@ -24,6 +24,8 @@ export interface WorkerInit {
     retries?: number;
     /** Where the run's report goes when it is not the default; screenshots are kept beside it */
     reportPath?: string;
+    /** The run's `outputDir`: screenshots go there */
+    outputDir?: string;
     /** Spec files to import, absolute */
     files: string[];
     /** 0 for the first worker; picks the worker's browser port and profile folder */

package/dist/runner/worker-session.js

@@ -48,6 +48,9 @@ export function openSession(init) {
                         ...(init.reportPath !== undefined && {
                             reportPath: init.reportPath,
                         }),
+                        ...(init.outputDir !== undefined && {
+                            outputDir: init.outputDir,
+                        }),
                         port,
                         signal,
                     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.16.0",
+  "version": "0.17.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": {