@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/src/config/mask.ts

@@ -1,87 +0,0 @@
-import { inspect } from "node:util";
-import { format } from "winston";
-
-export const MASK = "••••";
-/** Values shorter than this only match as a whole token, so "1" does not hide every digit */
-const SHORT_LENGTH = 4;
-
-const secrets = new Map<string, string>();
-let patterns: RegExp[] = [];
-
-/** Registers a secret value; every later maskText/maskDeep/log line hides it */
-export function registerSecret(name: string, value: string): void {
-  if (value === "") return;
-  secrets.set(name, value);
-  rebuild();
-}
-
-/** Forgets every registered secret (tests only) */
-export function resetSecrets(): void {
-  secrets.clear();
-  patterns = [];
-}
-
-export function isShortSecret(value: string): boolean {
-  return value.length > 0 && value.length < SHORT_LENGTH;
-}
-
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/** A value plus its JSON-escaped, inspect-escaped and percent-encoded spellings */
-function variants(value: string): string[] {
-  const forms = [value, JSON.stringify(value).slice(1, -1), inspect(value).slice(1, -1), encodeURIComponent(value)];
-  return forms.filter((form) => form !== "");
-}
-
-function rebuild(): void {
-  // Longest first, so a secret that contains another one is hidden whole
-  const forms = [...new Set([...secrets.values()].flatMap(variants))].sort((a, b) => b.length - a.length);
-  patterns = forms.map((value) =>
-    isShortSecret(value)
-      ? new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(value)}(?![\\p{L}\\p{N}])`, "gu")
-      : new RegExp(escapeRegExp(value), "gu"),
-  );
-}
-
-export function maskText(text: string): string {
-  let masked = text;
-  for (const pattern of patterns) masked = masked.replace(pattern, MASK);
-  return masked;
-}
-
-/** A copy of `value` with every string in it masked, following JSON.stringify semantics for objects */
-export function maskDeep<T>(value: T): T {
-  if (patterns.length === 0) return value;
-  return walk(value, new WeakSet()) as T;
-}
-
-function walk(value: unknown, path: WeakSet<object>): unknown {
-  if (typeof value === "string") return maskText(value);
-  if (value === null || typeof value !== "object") return value;
-  if (path.has(value)) return "[Circular]";
-  path.add(value);
-  try {
-    if (Array.isArray(value)) return value.map((item) => walk(item, path));
-    const toJSON = (value as { toJSON?: unknown }).toJSON;
-    if (typeof toJSON === "function") return walk(toJSON.call(value), path);
-    const entries: Array<[string, unknown]> = Object.entries(value);
-    if (value instanceof Error) {
-      const own = new Set(entries.map(([key]) => key));
-      for (const key of ["name", "message", "stack"] as const) {
-        if (!own.has(key)) entries.unshift([key, value[key]]);
-      }
-    }
-    return Object.fromEntries(entries.map(([key, item]) => [key, walk(item, path)]));
-  } finally {
-    path.delete(value);
-  }
-}
-
-/** Winston format that masks every string field of a log entry (message and metadata) */
-export const maskFormat = format((info) => {
-  if (patterns.length === 0) return info;
-  for (const key of Object.keys(info)) info[key] = walk(info[key], new WeakSet());
-  return info;
-});

package/src/config/run-settings.test.ts

@@ -1,163 +0,0 @@
-import { afterEach, describe, test } from "node:test";
-import assert from "node:assert/strict";
-import type { SamuraiTestConfig } from "../types/config.js";
-import {
-  getRunSettings,
-  parseRunOverrides,
-  peekRunSettings,
-  resolveRunSettings,
-  setRunSettings,
-  UnknownEnvironmentError,
-} from "./run-settings.js";
-
-const twoEnvironments: SamuraiTestConfig = {
-  baseURL: "https://harbor.shop",
-  timeout: 20000,
-  expect: { timeout: 3000 },
-  environments: {
-    dev: { baseURL: "http://localhost:3000", variables: { customerEmail: "dev@example.test" } },
-    staging: { timeout: 45000, expect: { timeout: 8000 }, variables: { customerEmail: "sam@example.test" } },
-  },
-};
-
-describe("resolveRunSettings: choosing the environment", () => {
-  test("an override wins over defaultEnvironment", () => {
-    const settings = resolveRunSettings({ ...twoEnvironments, defaultEnvironment: "staging" }, { environment: "dev" });
-    assert.equal(settings.environment, "dev");
-  });
-
-  test("defaultEnvironment is used without an override", () => {
-    assert.equal(resolveRunSettings({ ...twoEnvironments, defaultEnvironment: "staging" }).environment, "staging");
-  });
-
-  test("the only environment is used when nothing is chosen", () => {
-    assert.equal(resolveRunSettings({ environments: { qa: {} } }).environment, "qa");
-  });
-
-  test("no environments gives the implicit default environment with top-level values", () => {
-    assert.deepEqual(resolveRunSettings({ baseURL: "https://harbor.shop", timeout: 1000 }), {
-      environment: "default",
-      baseURL: "https://harbor.shop",
-      timeout: 1000,
-      expectTimeout: 5000,
-      variables: {},
-    });
-  });
-
-  test("several environments and no choice throws, listing them", () => {
-    assert.throws(
-      () => resolveRunSettings(twoEnvironments),
-      (err) =>
-        err instanceof UnknownEnvironmentError &&
-        err.message === "No environment chosen. Available: dev, staging (use --env or set defaultEnvironment)",
-    );
-  });
-
-  test("an unknown name throws, listing the available ones", () => {
-    assert.throws(
-      () => resolveRunSettings(twoEnvironments, { environment: "stg" }),
-      (err) => err instanceof UnknownEnvironmentError && err.message === 'Unknown environment "stg". Available: dev, staging',
-    );
-  });
-
-  test("a named environment when none are defined throws", () => {
-    assert.throws(
-      () => resolveRunSettings({}, { environment: "staging" }),
-      (err) =>
-        err instanceof UnknownEnvironmentError &&
-        err.message === 'Unknown environment "staging". No environments are defined in samurai.config.ts',
-    );
-  });
-});
-
-describe("resolveRunSettings: precedence", () => {
-  test("environment values beat project values", () => {
-    const settings = resolveRunSettings(twoEnvironments, { environment: "staging" });
-    assert.equal(settings.timeout, 45000);
-    assert.equal(settings.expectTimeout, 8000);
-    assert.equal(settings.baseURL, "https://harbor.shop");
-    assert.deepEqual(settings.variables, { customerEmail: "sam@example.test" });
-  });
-
-  test("project values fill what the environment leaves out", () => {
-    const settings = resolveRunSettings(twoEnvironments, { environment: "dev" });
-    assert.equal(settings.timeout, 20000);
-    assert.equal(settings.expectTimeout, 3000);
-    assert.equal(settings.baseURL, "http://localhost:3000");
-  });
-
-  test("run overrides beat everything", () => {
-    const settings = resolveRunSettings(twoEnvironments, { environment: "staging", timeout: 1, expectTimeout: 2 });
-    assert.equal(settings.timeout, 1);
-    assert.equal(settings.expectTimeout, 2);
-  });
-
-  test("built-in defaults apply last", () => {
-    const settings = resolveRunSettings({ environments: { qa: {} } });
-    assert.equal(settings.timeout, 30000);
-    assert.equal(settings.expectTimeout, 5000);
-    assert.equal("baseURL" in settings, false);
-  });
-
-  test("variables are a copy", () => {
-    const config: SamuraiTestConfig = { environments: { qa: { variables: { a: 1 } } } };
-    resolveRunSettings(config).variables.a = 2;
-    assert.equal(config.environments?.qa?.variables?.a, 1);
-  });
-});
-
-describe("parseRunOverrides", () => {
-  test("reads --env, --timeout and --expect-timeout", () => {
-    assert.deepEqual(parseRunOverrides(["--env", "dev", "--timeout", "1000", "--expect-timeout=200"]), {
-      environment: "dev",
-      timeout: 1000,
-      expectTimeout: 200,
-    });
-  });
-
-  test("falls back to SAMURAI_ENV", () => {
-    assert.deepEqual(parseRunOverrides([], { SAMURAI_ENV: "staging" }), { environment: "staging" });
-    assert.deepEqual(parseRunOverrides(["--env", "dev"], { SAMURAI_ENV: "staging" }), { environment: "dev" });
-  });
-
-  test("nothing given is no overrides", () => {
-    assert.deepEqual(parseRunOverrides([], {}), {});
-  });
-
-  test("rejects bad overrides", () => {
-    assert.throws(() => parseRunOverrides(["--env"]), /--env/);
-    assert.throws(() => parseRunOverrides(["--timeout", "abc"]), {
-      message: '--timeout must be a whole number of milliseconds, got "abc"',
-    });
-    // A value starting with "-" must use "=" (parseArgs treats "--timeout -5" as a missing value)
-    assert.throws(() => parseRunOverrides(["--timeout=-5"]), /--timeout must be a whole number/);
-    assert.throws(() => parseRunOverrides(["--expect-timeout", ""]), /--expect-timeout must be a whole number/);
-  });
-});
-
-describe("active run settings", () => {
-  afterEach(() => setRunSettings(undefined));
-
-  test("nothing is active until set", () => {
-    assert.equal(peekRunSettings(), undefined);
-    assert.throws(() => getRunSettings(), /No test run is active/);
-  });
-
-  test("set settings are returned", () => {
-    const settings = resolveRunSettings({});
-    setRunSettings(settings);
-    assert.equal(peekRunSettings(), settings);
-    assert.equal(getRunSettings(), settings);
-  });
-});
-
-test("prototype keys are not environments", () => {
-  for (const name of ["constructor", "toString", "__proto__"]) {
-    assert.throws(
-      () => resolveRunSettings(twoEnvironments, { environment: name }),
-      (err) =>
-        err instanceof UnknownEnvironmentError &&
-        err.message === `Unknown environment "${name}". Available: dev, staging`,
-    );
-  }
-});

package/src/config/run-settings.ts

@@ -1,114 +0,0 @@
-import { parseArgs } from "node:util";
-import type { SamuraiTestConfig } from "../types/config.js";
-
-export type Variables = Record<string, string | number | boolean>;
-
-/** Values given for one run (CLI flags, SAMURAI_ENV); they beat the config */
-export interface RunOverrides {
-  environment?: string;
-  timeout?: number;
-  expectTimeout?: number;
-}
-
-/** Everything about a run that depends on the chosen environment */
-export interface RunSettings {
-  environment: string;
-  baseURL?: string;
-  /** Time (ms) one test may take */
-  timeout: number;
-  /** Time (ms) actions and assertions retry */
-  expectTimeout: number;
-  variables: Variables;
-}
-
-const DEFAULT_TIMEOUT = 30000;
-const DEFAULT_EXPECT_TIMEOUT = 5000;
-/** The environment of a config without `environments` */
-const IMPLICIT_ENVIRONMENT = "default";
-
-export class UnknownEnvironmentError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "UnknownEnvironmentError";
-  }
-}
-
-/** Picks the environment and applies precedence: run override > environment > project > built-in default */
-export function resolveRunSettings(config: SamuraiTestConfig, overrides: RunOverrides = {}): RunSettings {
-  const environments = config.environments ?? {};
-  const names = Object.keys(environments);
-  const available = `Available: ${names.join(", ")}`;
-
-  let name = overrides.environment ?? config.defaultEnvironment;
-  if (name === undefined) {
-    if (names.length === 0) name = IMPLICIT_ENVIRONMENT;
-    else if (names.length === 1) name = names[0]!;
-    else throw new UnknownEnvironmentError(`No environment chosen. ${available} (use --env or set defaultEnvironment)`);
-  }
-
-  const environment = Object.prototype.hasOwnProperty.call(environments, name) ? environments[name] : undefined;
-  if (!environment && !(names.length === 0 && name === IMPLICIT_ENVIRONMENT)) {
-    throw new UnknownEnvironmentError(
-      names.length === 0
-        ? `Unknown environment "${name}". No environments are defined in samurai.config.ts`
-        : `Unknown environment "${name}". ${available}`,
-    );
-  }
-
-  const baseURL = environment?.baseURL ?? config.baseURL;
-  return {
-    environment: name,
-    ...(baseURL !== undefined && { baseURL }),
-    timeout: overrides.timeout ?? environment?.timeout ?? config.timeout ?? DEFAULT_TIMEOUT,
-    expectTimeout:
-      overrides.expectTimeout ?? environment?.expect?.timeout ?? config.expect?.timeout ?? DEFAULT_EXPECT_TIMEOUT,
-    variables: { ...(environment?.variables ?? {}) },
-  };
-}
-
-/** Reads `--env`, `--timeout` and `--expect-timeout` from `argv`; the environment falls back to SAMURAI_ENV */
-export function parseRunOverrides(argv: string[], env: Partial<NodeJS.ProcessEnv> = {}): RunOverrides {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      env: { type: "string" },
-      timeout: { type: "string" },
-      "expect-timeout": { type: "string" },
-    },
-    strict: true,
-    allowPositionals: true,
-  });
-  const overrides: RunOverrides = {};
-  const environment = values.env ?? env.SAMURAI_ENV;
-  if (environment) overrides.environment = environment;
-  if (values.timeout !== undefined) overrides.timeout = milliseconds("--timeout", values.timeout);
-  if (values["expect-timeout"] !== undefined) {
-    overrides.expectTimeout = milliseconds("--expect-timeout", values["expect-timeout"]);
-  }
-  return overrides;
-}
-
-function milliseconds(flag: string, raw: string): number {
-  const value = Number(raw);
-  if (raw.trim() === "" || !Number.isInteger(value) || value < 0) {
-    throw new Error(`${flag} must be a whole number of milliseconds, got "${raw}"`);
-  }
-  return value;
-}
-
-let active: RunSettings | undefined;
-
-/** Makes `settings` the run's settings; `undefined` ends the run (tests use this to reset) */
-export function setRunSettings(settings: RunSettings | undefined): void {
-  active = settings;
-}
-
-/** The active run's settings, or undefined outside a run (unit and browser tests) */
-export function peekRunSettings(): RunSettings | undefined {
-  return active;
-}
-
-export function getRunSettings(): RunSettings {
-  if (!active) throw new Error("No test run is active; run settings are set when the runner starts");
-  return active;
-}

package/src/config/secrets.ts

@@ -1,70 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { inspect, parseEnv } from "node:util";
-import logger from "../logger/index.js";
-import { MASK } from "./mask.js";
-import { isPassthroughKey } from "./variables.js";
-
-const PREFIX = "SAMURAI_SECRET_";
-const NAME = /^[A-Z][A-Z0-9_]*$/;
-
-export class MissingSecretError extends Error {
-  constructor(name: string, environment: string) {
-    super(`Secret "${name}" is not set (expected env var ${PREFIX}${name} or .env.${environment})`);
-    this.name = "MissingSecretError";
-  }
-}
-
-/** Secrets by name: `.env.<environment>` in `cwd` first, then env vars (which win) */
-export function loadSecrets(
-  environment: string,
-  options: { cwd?: string; env?: NodeJS.ProcessEnv } = {},
-): Map<string, string> {
-  const file = path.join(options.cwd ?? process.cwd(), `.env.${environment}`);
-  const sources: Array<Record<string, string | undefined>> = [];
-  if (existsSync(file)) sources.push(parseEnv(readFileSync(file, "utf8")) as Record<string, string>);
-  sources.push(options.env ?? process.env);
-
-  const secrets = new Map<string, string>();
-  for (const source of sources) {
-    for (const [key, value] of Object.entries(source)) {
-      if (!key.startsWith(PREFIX) || value === undefined || value === "") continue;
-      const name = key.slice(PREFIX.length);
-      if (!NAME.test(name)) {
-        logger.warn(`Ignoring ${key}: secret names must be UPPER_SNAKE_CASE`);
-        continue;
-      }
-      secrets.set(name, value);
-    }
-  }
-  return secrets;
-}
-
-/** The test's `secrets`: values by name, read-only; JSON and inspect show only masks */
-export function createSecretsFixture(
-  environment: string,
-  values: ReadonlyMap<string, string>,
-): Readonly<Record<string, string>> {
-  const masked = () => Object.fromEntries([...values.keys()].map((name) => [name, MASK]));
-  // Not frozen: the get trap returns the real value, which a frozen target's invariants forbid
-  const target: Record<string, string> = masked();
-  Object.defineProperty(target, "toJSON", { value: masked, enumerable: false });
-  Object.defineProperty(target, inspect.custom, { value: masked, enumerable: false });
-  const readOnly = (): never => {
-    throw new TypeError("secrets are read-only");
-  };
-
-  return new Proxy(target, {
-    get(target, key, receiver) {
-      if (isPassthroughKey(target, key)) return Reflect.get(target, key, receiver);
-      const name = String(key);
-      if (!NAME.test(name)) throw new Error(`Invalid secret name "${name}" (use UPPER_SNAKE_CASE)`);
-      const value = values.get(name);
-      if (value === undefined) throw new MissingSecretError(name, environment);
-      return value;
-    },
-    set: readOnly,
-    defineProperty: readOnly,
-    deleteProperty: readOnly,
-  });
-}

package/src/config/variables.ts

@@ -1,31 +0,0 @@
-import type { Variables } from "./run-settings.js";
-
-export class UnknownVariableError extends Error {
-  constructor(name: string, environment: string) {
-    super(`Variable "${name}" is not defined in environment "${environment}"`);
-    this.name = "UnknownVariableError";
-  }
-}
-
-/**
- * Keys that every object answers and that `await`, JSON.stringify and util.inspect probe:
- * symbols, `then`, `toJSON` and Object.prototype members. Reading them never throws.
- */
-export function isPassthroughKey(target: object, key: string | symbol): boolean {
-  return (
-    typeof key === "symbol" ||
-    key === "then" ||
-    key === "toJSON" ||
-    (!Object.prototype.hasOwnProperty.call(target, key) && key in target)
-  );
-}
-
-/** The test's `env`: the environment's variables, read-only; an unknown name throws */
-export function createEnvFixture(environment: string, variables: Variables): Readonly<Variables> {
-  return new Proxy(Object.freeze({ ...variables }), {
-    get(target, key, receiver) {
-      if (isPassthroughKey(target, key) || Object.prototype.hasOwnProperty.call(target, key)) return Reflect.get(target, key, receiver);
-      throw new UnknownVariableError(String(key), environment);
-    },
-  });
-}

package/src/index.ts

@@ -1,10 +0,0 @@
-import { loadConfig } from "./config/config.js";
-import { parseRunOverrides } from "./config/run-settings.js";
-import { prepareRun } from "./runner/prepare-run.js";
-import TestRunner from "./runner/test-runner.js";
-
-const run = prepareRun(await loadConfig(), parseRunOverrides(process.argv.slice(2), process.env));
-const runner = await TestRunner.init(run);
-await runner.start();
-
-process.exit();

package/src/locator/action-timeout-error.test.ts

@@ -1,83 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { ActionTimeoutError } from "./action-timeout-error.js";
-
-const base = { action: "click", selector: '//button[@type="submit"]', timeout: 5000 } as const;
-
-test("unreadable: no probe completed", () => {
-  const err = new ActionTimeoutError({ ...base, reason: "unreadable" });
-  assert.equal(err.message, 'click(): could not read //button[@type="submit"] within 5000ms');
-});
-
-test("not attached", () => {
-  const err = new ActionTimeoutError({
-    ...base,
-    reason: "not-attached",
-    checks: { attached: "fail", visible: "pending" },
-  });
-  assert.equal(err.message, 'click(): //button[@type="submit"] was not attached within 5000ms');
-});
-
-test("wrong state for waitFor", () => {
-  const err = new ActionTimeoutError({
-    action: "waitFor",
-    selector: '//div[@class="spinner"]',
-    timeout: 300,
-    reason: "wrong-state",
-    state: "hidden",
-  });
-  assert.equal(err.message, 'waitFor(): //div[@class="spinner"] did not become hidden within 300ms');
-});
-
-test("not actionable lists every check in order", () => {
-  const err = new ActionTimeoutError({
-    ...base,
-    reason: "not-actionable",
-    checks: {
-      attached: "pass",
-      visible: "pass",
-      stable: "pass",
-      enabled: "fail",
-      "hit target": "pending",
-    },
-  });
-  assert.equal(
-    err.message,
-    'click(): //button[@type="submit"] was not actionable within 5000ms\n' +
-      "  attached ✓  visible ✓  stable ✓  enabled ✗  hit target —",
-  );
-});
-
-test("a failed hit target names the covering element", () => {
-  const err = new ActionTimeoutError({
-    ...base,
-    reason: "not-actionable",
-    checks: {
-      attached: "pass",
-      visible: "pass",
-      stable: "pass",
-      enabled: "pass",
-      "hit target": "fail",
-    },
-    coveredBy: "div#cookie-banner.overlay",
-  });
-  assert.equal(
-    err.message,
-    'click(): //button[@type="submit"] was not actionable within 5000ms\n' +
-      "  attached ✓  visible ✓  stable ✓  enabled ✓  hit target ✗ (covered by div#cookie-banner.overlay)",
-  );
-});
-
-test("exposes its details", () => {
-  const checks = { attached: "fail" } as const;
-  const err = new ActionTimeoutError({ ...base, reason: "not-attached", checks });
-  assert.ok(err instanceof Error);
-  assert.equal(err.name, "ActionTimeoutError");
-  assert.equal(err.action, "click");
-  assert.equal(err.selector, '//button[@type="submit"]');
-  assert.equal(err.timeout, 5000);
-  assert.equal(err.reason, "not-attached");
-  assert.deepEqual(err.checks, checks);
-  assert.equal(err.coveredBy, undefined);
-  assert.equal(err.state, undefined);
-});

package/src/locator/action-timeout-error.ts

@@ -1,72 +0,0 @@
-import type { CheckName, CheckResult, CheckResults, WaitForState } from "./element-state.js";
-
-export type ActionTimeoutReason = "unreadable" | "not-attached" | "not-actionable" | "wrong-state";
-
-export interface ActionTimeoutDetails {
-  /** Locator method that timed out, e.g. "click" */
-  action: string;
-  selector: string;
-  timeout: number;
-  reason: ActionTimeoutReason;
-  /** Check results from the last probe, in check order */
-  checks?: CheckResults | undefined;
-  /** Description of the element covering the target, when the hit-target check failed */
-  coveredBy?: string | undefined;
-  /** Target state, for waitFor */
-  state?: WaitForState | undefined;
-}
-
-const SYMBOLS: Record<CheckResult, string> = { pass: "✓", fail: "✗", pending: "—" };
-
-function formatMessage({
-  action,
-  selector,
-  timeout,
-  reason,
-  checks,
-  coveredBy,
-  state,
-}: ActionTimeoutDetails) {
-  switch (reason) {
-    case "unreadable":
-      return `${action}(): could not read ${selector} within ${timeout}ms`;
-    case "not-attached":
-      return `${action}(): ${selector} was not attached within ${timeout}ms`;
-    case "wrong-state":
-      return `${action}(): ${selector} did not become ${state} within ${timeout}ms`;
-    case "not-actionable": {
-      const summary = (Object.entries(checks ?? {}) as Array<[CheckName, CheckResult]>)
-        .map(([name, result]) => {
-          const covered =
-            name === "hit target" && result === "fail" && coveredBy
-              ? ` (covered by ${coveredBy})`
-              : "";
-          return `${name} ${SYMBOLS[result]}${covered}`;
-        })
-        .join("  ");
-      return `${action}(): ${selector} was not actionable within ${timeout}ms\n  ${summary}`;
-    }
-  }
-}
-
-export class ActionTimeoutError extends Error {
-  public readonly action: string;
-  public readonly selector: string;
-  public readonly timeout: number;
-  public readonly reason: ActionTimeoutReason;
-  public readonly checks: CheckResults | undefined;
-  public readonly coveredBy: string | undefined;
-  public readonly state: WaitForState | undefined;
-
-  constructor(details: ActionTimeoutDetails) {
-    super(formatMessage(details));
-    this.name = "ActionTimeoutError";
-    this.action = details.action;
-    this.selector = details.selector;
-    this.timeout = details.timeout;
-    this.reason = details.reason;
-    this.checks = details.checks;
-    this.coveredBy = details.coveredBy;
-    this.state = details.state;
-  }
-}