@itmetsam/samurai-framework 0.1.0

package/src/types/bidi-modules/storage.d.ts

@@ -0,0 +1,92 @@
+import type { Extensible } from "../bidi.js";
+import type { UserContext } from "./browser.js";
+import type { BrowsingContext } from "./browsing-context.js";
+import type { BytesValue, Cookie, SameSite } from "./network.js";
+
+export type StorageCommands = {
+  "storage.getCookies": {
+    params: {
+      filter?: CookieFilter;
+      partition?: PartitionDescriptor;
+    };
+    result: {
+      cookies: Cookie[];
+      partitionKey: PartitionKey;
+    };
+  };
+  "storage.setCookie": {
+    params: {
+      cookie: PartialCookie;
+      partition?: PartitionDescriptor;
+    };
+    result: {
+      partitionKey: PartitionKey;
+    };
+  };
+  "storage.deleteCookies": {
+    params: {
+      filter?: CookieFilter;
+      partition?: PartitionDescriptor;
+    };
+    result: {
+      partitionKey: PartitionKey;
+    };
+  };
+};
+
+export interface PartialCookie extends Partial<Cookie> {
+  name: string;
+  value: BytesValue;
+  domain: string;
+}
+
+export interface CookieFilter extends Extensible {
+  name?: string;
+  value?: BytesValue;
+  domain?: string;
+  path?: string;
+  size?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: SameSite;
+  expiry?: number;
+}
+
+export type PartitionDescriptor =
+  | BrowsingContextPartitionDescriptor
+  | StorageKeyPartitionDescriptor
+  | undefined;
+
+export interface BrowsingContextPartitionDescriptor {
+  type: "context";
+  context: BrowsingContext;
+}
+
+export interface StorageKeyPartitionDescriptor extends Extensible {
+  type: "storageKey";
+  userContext?: UserContext;
+  sourceOrigin?: string;
+}
+
+export type StorageResult =
+  | DeleteCookiesResult
+  | GetCookiesResult
+  | SetCookieResult;
+
+export interface PartitionKey extends Extensible {
+  userContext?: UserContext;
+  sourceOrigin?: string;
+}
+
+export interface DeleteCookiesResult {
+  partitionKey: PartitionKey;
+}
+
+export interface GetCookiesResult {
+  cookies: Cookie[];
+  partitionKey: PartitionKey;
+}
+
+export interface SetCookieResult {
+  partitionKey: PartitionKey;
+}

package/src/types/bidi-modules/web-extensions.d.ts

@@ -0,0 +1,9 @@
+import type { EmptyResult } from "../bidi.js";
+
+export type WebExtensionResult = InstallResult | UninstallResult;
+
+export type UninstallResult = EmptyResult;
+export type Extension = string;
+export interface InstallResult {
+  extension: Extension;
+}

package/src/types/bidi-protocols/command.d.ts

@@ -0,0 +1,7 @@
+import type { Extensible, ResultData } from "../bidi.js";
+
+export interface CommandResponse extends Extensible {
+  type: "success";
+  id: number;
+  result: ResultData;
+}

package/src/types/bidi-protocols/error.d.ts

@@ -0,0 +1,38 @@
+export type ErrorCode =
+  | "invalid argument"
+  | "invalid selector"
+  | "invalid session id"
+  | "invalid web extension"
+  | "move target out of bounds"
+  | "no such alert"
+  | "no such network collector"
+  | "no such element"
+  | "no such frame"
+  | "no such handle"
+  | "no such history entry"
+  | "no such intercept"
+  | "no such network data"
+  | "no such node"
+  | "no such request"
+  | "no such script"
+  | "no such storage partition"
+  | "no such user context"
+  | "no such web extension"
+  | "session not created"
+  | "unable to capture screen"
+  | "unable to close browser"
+  | "unable to set cookie"
+  | "unable to set file input"
+  | "unavailable network data"
+  | "underspecified storage partition"
+  | "unknown command"
+  | "unknown error"
+  | "unsupported operation";
+
+export interface ErrorResponse {
+  type: "error";
+  id: number | null;
+  error: ErrorCode;
+  message: string;
+  stacktrace?: string;
+}

package/src/types/bidi-protocols/event.d.ts

@@ -0,0 +1,17 @@
+import type { BrowsingContextEvent } from "../bidi-modules/browsing-context.js";
+import type { LogEvent } from "../bidi-modules/log.js";
+import type { NetworkEvent } from "../bidi-modules/network.js";
+import type { ScriptEvent } from "../bidi-modules/script.js";
+import type { Extensible } from "../bidi.js";
+
+export type BiDiEvent = Extensible &
+  EventData & {
+    type: "event";
+  };
+
+export type EventData =
+  | BrowsingContextEvent
+  | InputEvent
+  | LogEvent
+  | NetworkEvent
+  | ScriptEvent;

package/src/types/bidi.d.ts

@@ -0,0 +1,65 @@
+import type { BrowserCommands, BrowserResult } from "./bidi-modules/browser.js";
+import type {
+  BrowsingContextEvents,
+  BrowsingContextModule as BrowsingContextCommands,
+  BrowsingContextResult,
+} from "./bidi-modules/browsing-context.js";
+import type { EmulationCommands, EmulationResult } from "./bidi-modules/emulation.js";
+import type {
+  InputCommands,
+  InputEvents,
+  InputResult,
+} from "./bidi-modules/input.js";
+import type { LogEvents } from "./bidi-modules/log.js";
+import type { PermissionsCommands } from "./bidi-modules/permissions.js";
+import type {
+  NetworkCommands,
+  NetworkEvents,
+  NetworkResult,
+} from "./bidi-modules/network.js";
+import type {
+  ScriptCommands,
+  ScriptEvents,
+  ScriptResult,
+} from "./bidi-modules/script.js";
+import type { SessionModule, SessionResult } from "./bidi-modules/session.js";
+import type { StorageCommands, StorageResult } from "./bidi-modules/storage.js";
+import type { WebExtensionResult } from "./bidi-modules/web-extensions.js";
+import type { CommandResponse } from "./bidi-protocols/command.js";
+import type { ErrorResponse } from "./bidi-protocols/error.js";
+import type { BiDiEvent } from "./bidi-protocols/event.js";
+
+export type BiDiCommands = BrowserCommands &
+  SessionModule &
+  BrowsingContextCommands &
+  ScriptCommands &
+  InputCommands &
+  StorageCommands &
+  NetworkCommands &
+  EmulationCommands &
+  PermissionsCommands;
+
+export type BiDiEvents = BrowsingContextEvents &
+  InputEvents &
+  LogEvents &
+  NetworkEvents &
+  ScriptEvents;
+
+export type BiDiMessages = CommandResponse | ErrorResponse | BiDiEvent;
+
+export type ResultData =
+  | BrowserResult
+  | BrowsingContextResult
+  | EmulationResult
+  | InputResult
+  | NetworkResult
+  | ScriptResult
+  | SessionResult
+  | StorageResult
+  | WebExtensionResult;
+
+export type EmptyResult = Extensible;
+
+export interface Extensible {
+  [key: string]: any;
+}

package/src/types/browser.d.ts

@@ -0,0 +1 @@
+export type SupportedBrowser = "firefox";

package/src/types/config.d.ts

@@ -0,0 +1,157 @@
+import type { SupportedBrowser } from "./browser.js";
+
+interface SamuraiTest {
+  /** Path relative to srcDir, e.g. 'checkout/coupons.spec.ts' */
+  file: string;
+  /** Full title, including describe blocks: 'Guest checkout > applies coupon' */
+  title: string;
+}
+
+export interface SamuraiGroup {
+  name: string;
+  /**
+   * Directory to search for tests for this group.
+   * If empty, it uses the 'srcDir'
+   */
+  src?: string;
+  /** Glob pattern to use when searching for tests.
+   *  @default "**\/*.spec.ts"
+   **/
+  testMatch?: string;
+  /**
+   * Explicitly define the tests inside the group.
+   * Overrides 'src' and 'testMatch'  options.
+   */
+  tests?: SamuraiTest[];
+}
+
+export interface SamuraiEnvironment {
+  /** Where page.goto('/…') resolves to in this environment, and where recordings start */
+  baseURL?: string;
+  /** Overrides the project timeout (ms) for this environment */
+  timeout?: number;
+  expect?: { timeout?: number };
+  /** Test data, used in steps as ${name}. Never put secrets here. */
+  variables?: Record<string, string | number | boolean>;
+}
+
+export interface SamuraiTestConfig {
+  /**
+   * directory containing all the test files
+   * @default "./src"
+   */
+  srcDir?: string;
+  /**
+   * The browser to use for all tests.
+   * Is overwritten by the 'browser' in a group's config
+   */
+  browser?: SupportedBrowser;
+  /**
+   * The timeout (in ms) to use for all tests
+   * @default 30000
+   */
+  timeout?: number;
+  /**
+   * Define a group of test's you want to have executed with a certain configuration
+   **/
+  groups?: SamuraiGroup[];
+  /**
+   * The base URL to use when navigating the browser.
+   * When recording starts, the browser will start at this URL.
+   */
+  baseURL?: string;
+  /** Options for `expect` assertions */
+  expect?: {
+    /**
+     * Time (ms) locator assertions, actions (click, fill, focus) and waitFor keep retrying before failing
+     * @default 5000
+     */
+    timeout?: number;
+  };
+  /** Options for the WebDriver BiDi connection */
+  bidi?: {
+    /**
+     * Time (ms) a BiDi command may wait for its reply before failing with code "timeout"
+     * @default 30000
+     */
+    commandTimeout?: number;
+  };
+  /**
+   * Folder below which downloads are saved: every browser gets a folder of its own in it, and removes it again
+   * when nothing was downloaded
+   * @default "result/downloads"
+   */
+  downloadsDir?: string;
+  /** How pages are opened */
+  use?: {
+    /**
+     * Size of the page's viewport, so screenshots and layout are the same on every machine.
+     * `null` keeps the browser's own size
+     * @default { width: 1280, height: 720 }
+     */
+    viewport?: { width: number; height: number } | null;
+  };
+  /** What to do with the browser's console output and uncaught page exceptions */
+  logs?: {
+    /**
+     * Which tests get the page's log entries in the report: only failed ones, all, or none
+     * @default "failures"
+     */
+    capture?: "off" | "failures" | "all";
+    /**
+     * Fail a test that passed when the page threw an exception nobody caught.
+     * A test can opt out with `page.allowPageErrors()`
+     * @default false
+     */
+    failOnPageError?: boolean;
+    /** Uncaught exceptions whose message contains a string, or matches a RegExp, never fail a test */
+    ignoreErrors?: (string | RegExp)[];
+  };
+  /** Options for `page.navigateTo()` and `page.waitForLoadState()` */
+  navigation?: {
+    /**
+     * Time (ms) a navigation, or a wait for a load state, may take. Separate from `expect.timeout`:
+     * loading a page legitimately takes longer than an element becoming clickable
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * When `navigateTo()` resolves: "none" right away, "interactive" at DOMContentLoaded, "complete" at load
+     * @default "complete"
+     */
+    waitUntil?: "none" | "interactive" | "complete";
+  };
+  /** Options for network tracking (`page.waitForNetworkIdle()` and the request/response events) */
+  network?: {
+    /**
+     * Follow the page's requests from the moment the browser starts. When false, `waitForNetworkIdle()` throws
+     * @default true
+     */
+    track?: boolean;
+    /**
+     * Time (ms) without requests in flight that counts as idle
+     * @default 500
+     */
+    idleTime?: number;
+    /**
+     * Time (ms) a `page.route` handler may take to answer a request before the request is let through
+     * @default 30000
+     */
+    routeTimeout?: number;
+    /**
+     * Keep response bodies from the moment the browser starts, so `response.body()` works for every response.
+     * Bodies are otherwise kept once `page.on("response")` or `page.waitForResponse()` is used, and cost browser memory
+     * @default false
+     */
+    collectBodies?: boolean;
+    /**
+     * Largest response body (bytes) that is kept for `response.body()`
+     * @default 10485760
+     */
+    maxBodySize?: number;
+  };
+  /** Keyed by name: 'dev', 'staging', 'production' */
+  environments?: Record<string, SamuraiEnvironment>;
+  /** Used when no environment is chosen with --env or SAMURAI_ENV */
+  defaultEnvironment?: string;
+}

package/src/types/env.d.ts

@@ -0,0 +1,5 @@
+declare namespace NodeJS {
+  interface ProcessEnv {
+    NODE_CONFIG_DIR: string;
+  }
+}

package/src/types/test.d.ts

@@ -0,0 +1,95 @@
+import type { Browser } from "../browser/browser.ts";
+import type Page from "../browser/page.ts";
+
+/** What a test function receives */
+export interface TestFixtures {
+  page: Page;
+  browser: Browser;
+  /** The chosen environment's variables; reading an unknown name throws */
+  env: Readonly<Record<string, string | number | boolean>>;
+  /** Secrets by name (SAMURAI_SECRET_<NAME>); reading an unset name throws */
+  secrets: Readonly<Record<string, string>>;
+}
+
+export type TestCase = TestCaseBase;
+
+export interface RegisteredTestCase extends TestCaseBase {
+  /** Path of the spec file that registered the test */
+  file: string;
+  /** describe titles, then the test title */
+  titlePath: string[];
+}
+
+export interface TestCaseBase {
+  /** Full title: describe titles and the test title joined with " > " */
+  name: string;
+  function: (fixtures: TestFixtures) => Promise<void>;
+}
+
+export interface PartialTestResult extends TestResultBase {
+  name: string;
+  file: string;
+}
+
+export type TestResult = TestResultSuccess | TestResultFailed | TestResultBase;
+
+interface TestResultSuccess {
+  status: "success";
+  duration: number;
+  logs?: TestLogEntry[];
+  /** Entries that fell out of the page's log buffer */
+  logsDropped?: number;
+}
+
+interface TestResultFailed {
+  status: "failed";
+  error: TestError;
+  duration: number;
+  logs?: TestLogEntry[];
+  logsDropped?: number;
+}
+
+/** One line of the browser's log, as stored in the report */
+export interface TestLogEntry {
+  level: "debug" | "info" | "warn" | "error";
+  /** "console", "javascript" (an uncaught exception), or another type the browser reports */
+  type: string;
+  method?: string;
+  text: string;
+  timestamp: number;
+}
+
+interface TestResultBase {
+  name: string;
+  file: string;
+  startTime: number;
+  status: "started";
+}
+
+interface TestError {
+  message: string;
+  type: "timeout" | "error" | "assertion";
+  stack?: string | undefined;
+  /** Only for `type: "assertion"` */
+  expected?: unknown;
+  /** Only for `type: "assertion"` */
+  actual?: unknown;
+}
+
+export type TestSummary = TestSummarySuccess | TestSummaryFailed;
+
+interface TestSummarySuccess extends TestSummaryBase {
+  status: "success";
+}
+
+interface TestSummaryFailed extends TestSummaryBase {
+  status: "failed";
+}
+
+interface TestSummaryBase {
+  duration: number;
+  startTime: number;
+  tests: TestResult[];
+  /** The environment the run used */
+  environment: string;
+}

package/src/wait/wait-until.test.ts

@@ -0,0 +1,117 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveTimeout, waitUntil, WaitTimeoutError } from "./wait-until.js";
+import { resolveRunSettings, setRunSettings } from "../config/run-settings.js";
+
+/** Probe returning the given values in order; the last one repeats */
+function sequence<T>(...values: T[]) {
+  let calls = 0;
+  const probe = async () => values[Math.min(calls++, values.length - 1)]!;
+  return { probe, calls: () => calls };
+}
+
+test("probes until isDone and resolves with that value", async () => {
+  const { probe, calls } = sequence(1, 2, 3);
+  assert.equal(await waitUntil(probe, (value) => value === 3, { timeout: 2000 }), 3);
+  assert.equal(calls(), 3);
+});
+
+test("passes the previous value to isDone", async () => {
+  const { probe } = sequence(1, 2, 2);
+  const seen: Array<[number, number | undefined]> = [];
+  await waitUntil(
+    probe,
+    (current, previous) => {
+      seen.push([current, previous]);
+      return current === previous;
+    },
+    { timeout: 2000 },
+  );
+  assert.deepEqual(seen, [
+    [1, undefined],
+    [2, 1],
+    [2, 2],
+  ]);
+});
+
+test("times out with the last value, ending at the deadline", async () => {
+  const { probe, calls } = sequence("a", "b");
+  const start = Date.now();
+  await assert.rejects(waitUntil(probe, () => false, { timeout: 250 }), (err) => {
+    assert.ok(err instanceof WaitTimeoutError);
+    assert.equal(err.name, "WaitTimeoutError");
+    assert.equal(err.timeout, 250);
+    assert.equal(err.last, "b");
+    return true;
+  });
+  const elapsed = Date.now() - start;
+  // probes at ~0, ~100, ~200; the final sleep is clamped to the ~50ms left, and no probe starts after the deadline
+  assert.ok(elapsed >= 245 && elapsed < 295, `elapsed ${elapsed}ms`);
+  assert.equal(calls(), 3);
+});
+
+test("timeout 0 probes exactly once", async () => {
+  const { probe, calls } = sequence(false);
+  await assert.rejects(waitUntil(probe, (value) => value, { timeout: 0 }), WaitTimeoutError);
+  assert.equal(calls(), 1);
+});
+
+test("timeout 0 resolves when the single probe is done", async () => {
+  const { probe } = sequence(true);
+  assert.equal(await waitUntil(probe, (value) => value, { timeout: 0 }), true);
+});
+
+test("probe errors are rethrown without retrying", async () => {
+  let calls = 0;
+  const probe = async () => {
+    calls++;
+    throw new Error("boom");
+  };
+  await assert.rejects(waitUntil(probe, () => true, { timeout: 2000 }), /boom/);
+  assert.equal(calls, 1);
+});
+
+test("a probe that never settles stops at the deadline", async () => {
+  const start = Date.now();
+  await assert.rejects(
+    waitUntil(() => new Promise<never>(() => {}), () => true, { timeout: 200 }),
+    (err) => {
+      assert.ok(err instanceof WaitTimeoutError);
+      assert.equal(err.last, undefined);
+      return true;
+    },
+  );
+  assert.ok(Date.now() - start < 400);
+});
+
+test("a probe that hangs after earlier results reports the last completed value", async () => {
+  let calls = 0;
+  const probe = () => (calls++ === 0 ? Promise.resolve("first") : new Promise<string>(() => {}));
+  await assert.rejects(waitUntil(probe, () => false, { timeout: 200 }), (err) => {
+    assert.ok(err instanceof WaitTimeoutError);
+    assert.equal(err.last, "first");
+    return true;
+  });
+});
+
+test("no timer outlives a resolved wait", async () => {
+  const timers = () => process.getActiveResourcesInfo().filter((name) => name === "Timeout").length;
+  const before = timers();
+  await waitUntil(async () => true, (value) => value, { timeout: 10000 });
+  assert.equal(timers(), before);
+});
+
+test("resolveTimeout prefers the per-call value", async () => {
+  assert.equal(await resolveTimeout(1234), 1234);
+  assert.equal(await resolveTimeout(0), 0);
+});
+
+test("resolveTimeout uses the active run's expect timeout", async () => {
+  setRunSettings(resolveRunSettings({}, { expectTimeout: 1234 }));
+  try {
+    assert.equal(await resolveTimeout(), 1234);
+    assert.equal(await resolveTimeout(10), 10);
+  } finally {
+    setRunSettings(undefined);
+  }
+});

package/src/wait/wait-until.ts

@@ -0,0 +1,86 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { readConfig } from "../config/config.js";
+import { peekRunSettings } from "../config/run-settings.js";
+
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_INTERVAL = 100;
+
+export interface WaitOptions {
+  /** Total time (ms) to keep probing; 0 probes exactly once */
+  timeout: number;
+  /** Time (ms) between probes. @default 100 */
+  interval?: number;
+}
+
+export class WaitTimeoutError<T> extends Error {
+  public readonly timeout: number;
+  /** Last completed probe result; undefined when no probe completed */
+  public readonly last: T | undefined;
+
+  constructor(timeout: number, last: T | undefined) {
+    super(`Condition not met within ${timeout}ms`);
+    this.name = "WaitTimeoutError";
+    this.timeout = timeout;
+    this.last = last;
+  }
+}
+
+/** Per-call timeout, else the active run's expect timeout, else config `expect.timeout`, else 5000 */
+export async function resolveTimeout(perCall?: number): Promise<number> {
+  if (perCall !== undefined) return perCall;
+  const run = peekRunSettings();
+  if (run) return run.expectTimeout;
+  return (await readConfig("expect"))?.timeout ?? DEFAULT_TIMEOUT;
+}
+
+const DEADLINE = Symbol("deadline");
+
+/**
+ * Races `probe()` against the time left. Resolves `{ value }` when the probe wins,
+ * DEADLINE when the time runs out first; probe errors reject as-is.
+ */
+function probeBefore<T>(
+  probe: () => Promise<T>,
+  remaining: number,
+): Promise<{ value: T } | typeof DEADLINE> {
+  const probing = probe();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<typeof DEADLINE>((resolve) => {
+    timer = setTimeout(() => resolve(DEADLINE), remaining);
+  });
+  // A probe that loses the race may still fail later; nobody is waiting for it any more
+  probing.catch(() => {});
+  return Promise.race([probing.then((value) => ({ value })), expired]).finally(() =>
+    clearTimeout(timer),
+  );
+}
+
+/**
+ * Probes until `isDone(current, previous)` is true and resolves with that result.
+ * Always probes at least once; with `timeout > 0` every probe races the time left.
+ * Probe errors are rethrown immediately. Throws WaitTimeoutError at the deadline.
+ */
+export async function waitUntil<T>(
+  probe: () => Promise<T>,
+  isDone: (current: T, previous: T | undefined) => boolean,
+  { timeout, interval = DEFAULT_INTERVAL }: WaitOptions,
+): Promise<T> {
+  const deadline = Date.now() + timeout;
+  let previous: T | undefined;
+
+  for (let first = true; ; first = false) {
+    const remaining = deadline - Date.now();
+    // Only start a probe while time remains; a later one could only lose the race
+    if (!first && remaining <= 0) throw new WaitTimeoutError(timeout, previous);
+
+    // timeout 0 keeps the single probe un-raced so it always completes
+    const result = timeout > 0 ? await probeBefore(probe, remaining) : { value: await probe() };
+    if (result === DEADLINE) throw new WaitTimeoutError(timeout, previous);
+    if (isDone(result.value, previous)) return result.value;
+    previous = result.value;
+
+    const left = deadline - Date.now();
+    if (left <= 0) throw new WaitTimeoutError(timeout, previous);
+    await sleep(Math.min(interval, left));
+  }
+}