@mizchi/playwright-faults 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Public types for @mizchi/playwright-faults. Three layers of fault
+ * injection share a few types (UrlMatcher, FaultStats shapes); each layer
+ * has its own discriminated-union `Action` type.
+ *
+ *   1. Network — `FaultRule` / `Fault`        (Playwright `route()` interception)
+ *   2. Page lifecycle — `LifecycleFault` / `LifecycleAction`
+ *      (Playwright `Page` / `BrowserContext` / CDP at named stages)
+ *   3. JS runtime — `RuntimeFault` / `RuntimeAction`
+ *      (Playwright `addInitScript` per page nav)
+ */
+/** Anything that can match a URL. String inputs are compiled with `new RegExp`. */
+export type UrlMatcher = string | RegExp;
+/**
+ * Minimal RNG contract used by the runtime-fault compiler. Caller passes
+ * any object with `next(): number` returning [0, 1). Caller-provided so
+ * playwright-faults stays seed-agnostic.
+ */
+export interface Rng {
+    next(): number;
+}
+/** What to do when a FaultRule matches a request. */
+export type Fault = {
+    kind: "abort";
+    errorCode?: string;
+} | {
+    kind: "status";
+    status: number;
+    body?: string;
+    contentType?: string;
+} | {
+    kind: "delay";
+    ms: number;
+};
+export interface FaultRule {
+    /** Optional human-readable name used in stats. */
+    name?: string;
+    /** URL matcher — a regex literal or a regex string. */
+    urlPattern: UrlMatcher;
+    /** HTTP methods to match (case-insensitive). Empty = all methods. */
+    methods?: string[];
+    /** Action taken on a match. */
+    fault: Fault;
+    /** 0..1, default 1.0. Uses the caller-provided RNG. */
+    probability?: number;
+}
+/** Per-rule stats for fault injection, emitted on the final report. */
+export interface FaultInjectionStats {
+    rule: string;
+    matched: number;
+    injected: number;
+}
+/**
+ * When during a page's lifecycle a `LifecycleFault` fires.
+ *
+ * - `beforeNavigation`: before `page.goto` — for CDP-level conditions that need to
+ *   apply during the load itself (CPU throttle, virtual time).
+ * - `afterLoad`: right after navigation completes, before any chaos actions or
+ *   `afterLoad` invariants run — for in-page mutations (storage clears, tamper).
+ * - `beforeActions`: after `afterLoad` invariants pass, before the first chaos
+ *   action — for one-shot evictions that should not affect invariants but should
+ *   precede user simulation (Service Worker cache eviction).
+ * - `betweenActions`: after every chaos action — for sustained pressure faults
+ *   that need re-application across the action loop.
+ */
+export type LifecycleStage = "beforeNavigation" | "afterLoad" | "beforeActions" | "betweenActions";
+/** Where a `clear-storage` / `tamper-storage` action targets. */
+export type StorageScope = "localStorage" | "sessionStorage" | "cookies" | "indexedDB";
+/**
+ * What a lifecycle fault does when it fires.
+ *
+ * Distinct from network-side `Fault` (which is request-scoped). These are
+ * page-scoped client-side perturbations applied via the Playwright Page /
+ * BrowserContext / CDP session.
+ */
+export type LifecycleAction = 
+/**
+ * Apply CPU throttling via CDP `Emulation.setCPUThrottlingRate`.
+ * `rate` is a multiplier ≥ 1 (1 = no throttle, 4 = ~4× slower).
+ */
+{
+    kind: "cpu-throttle";
+    rate: number;
+}
+/** Wipe one or more storage scopes. */
+ | {
+    kind: "clear-storage";
+    scopes: StorageScope[];
+}
+/**
+ * Drop entries from the Service Worker `caches` API. When `cacheNames` is
+ * omitted, every cache is dropped.
+ */
+ | {
+    kind: "evict-cache";
+    cacheNames?: string[];
+}
+/**
+ * Set a single key/value in `localStorage` or `sessionStorage`. Useful for
+ * forcing a logged-in app into "stale auth token" state and similar
+ * targeted-corruption scenarios.
+ */
+ | {
+    kind: "tamper-storage";
+    scope: "localStorage" | "sessionStorage";
+    key: string;
+    value: string;
+};
+/**
+ * Page-level fault injected at a specific lifecycle stage. Network-level faults
+ * stay on `FaultRule` (URL-matched, applied via Playwright `route()`).
+ */
+export interface LifecycleFault {
+    /** Optional human-readable name used in stats. Auto-derived when omitted. */
+    name?: string;
+    /** When during the page lifecycle this fault fires. */
+    when: LifecycleStage;
+    /**
+     * Restrict to URLs matching this matcher. Omit to apply on every page. For
+     * `beforeNavigation` faults the about-to-be-navigated URL is matched.
+     */
+    urlPattern?: UrlMatcher;
+    /** 0..1, default 1.0. Uses the caller-provided RNG. */
+    probability?: number;
+    /** What to do when the fault fires. */
+    action: LifecycleAction;
+}
+/** Per-fault stats emitted on the final report. */
+export interface LifecycleFaultStats {
+    /** `name` from the `LifecycleFault`, or an auto-derived label. */
+    name: string;
+    /** Pages whose URL matched (regardless of probability). */
+    matched: number;
+    /** Pages where the fault actually fired (after the probability roll). */
+    fired: number;
+    /** Pages where the fault threw while firing. */
+    errored: number;
+}
+/**
+ * What a runtime fault does when it fires. Each kind is a persistent
+ * monkey-patch installed in every page via `addInitScript`.
+ */
+export type RuntimeAction = 
+/**
+ * Reject `window.fetch` calls before any network round-trip. Different
+ * from a network `Fault` of kind `"abort"`: `flaky-fetch` rejects the
+ * Promise client-side with a TypeError, simulating "Failed to fetch" /
+ * Service Worker reject / DNS failure.
+ */
+{
+    kind: "flaky-fetch";
+    rejectionMessage?: string;
+}
+/**
+ * Skew `Date.now()` / `performance.now()` (and the no-arg `Date`
+ * constructor) forward by `skewMs`. Useful for forcing token-expiry,
+ * cache-bust, and "clock drift" code paths.
+ */
+ | {
+    kind: "clock-skew";
+    skewMs: number;
+};
+/**
+ * Page-level JS-runtime fault. Installed via `addInitScript` on every page
+ * navigation. Distinct from `FaultRule` (request-scoped) and
+ * `LifecycleFault` (one-shot at named stages of a page visit).
+ */
+export interface RuntimeFault {
+    /** Optional human-readable name used in stats. Auto-derived when omitted. */
+    name?: string;
+    /**
+     * Restrict to pages whose URL matches this matcher. Omitted = applies on
+     * every page. The check happens inside the page (against `location.href`),
+     * so the matcher must be JSON-serializable (string regex or RegExp literal).
+     */
+    urlPattern?: UrlMatcher;
+    /** 0..1, default 1.0. Rolled per call against an in-page seeded RNG. */
+    probability?: number;
+    /** What to do when the fault fires. */
+    action: RuntimeAction;
+}
+/** Per-fault stats for runtime fault injection, emitted on the final report. */
+export interface RuntimeFaultStats {
+    /** `name` from the `RuntimeFault`, or an auto-derived label. */
+    rule: string;
+    /** Times the fault was tested (URL matched, probability about to roll). */
+    matched: number;
+    /** Times the fault actually fired. */
+    fired: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * Public types for @mizchi/playwright-faults. Three layers of fault
+ * injection share a few types (UrlMatcher, FaultStats shapes); each layer
+ * has its own discriminated-union `Action` type.
+ *
+ *   1. Network — `FaultRule` / `Fault`        (Playwright `route()` interception)
+ *   2. Page lifecycle — `LifecycleFault` / `LifecycleAction`
+ *      (Playwright `Page` / `BrowserContext` / CDP at named stages)
+ *   3. JS runtime — `RuntimeFault` / `RuntimeAction`
+ *      (Playwright `addInitScript` per page nav)
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@mizchi/playwright-faults",
+  "version": "0.1.0",
+  "description": "Network / page-lifecycle / JS-runtime fault injection primitives for Playwright. Extracted from chaosbringer.",
+  "license": "MIT",
+  "author": "mizchi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mizchi/chaosbringer.git",
+    "directory": "packages/playwright-faults"
+  },
+  "homepage": "https://github.com/mizchi/chaosbringer/tree/main/packages/playwright-faults#readme",
+  "bugs": {
+    "url": "https://github.com/mizchi/chaosbringer/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "vitest run",
+    "lint:nul": "node ../chaosbringer/scripts/check-no-nul.mjs src"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "playwright",
+    "fault-injection",
+    "chaos-engineering",
+    "testing",
+    "monkey-patch"
+  ],
+  "peerDependencies": {
+    "playwright": "^1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "playwright": "^1.52.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.0.7"
+  }
+}

package/src/faults.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+import { faults } from "./faults.js";
+
+describe("faults helpers", () => {
+  it("faults.status produces a status fault rule", () => {
+    const rule = faults.status(500, { urlPattern: /\/api\// });
+    expect(rule.fault).toEqual({ kind: "status", status: 500 });
+    expect(rule.urlPattern).toBeInstanceOf(RegExp);
+  });
+
+  it("faults.status forwards body + contentType when provided", () => {
+    const rule = faults.status(503, {
+      urlPattern: "/api",
+      body: "down",
+      contentType: "text/plain",
+    });
+    expect(rule.fault).toEqual({
+      kind: "status",
+      status: 503,
+      body: "down",
+      contentType: "text/plain",
+    });
+  });
+
+  it("faults.abort defaults errorCode to nothing (crawler supplies default)", () => {
+    const rule = faults.abort({ urlPattern: /tracking/ });
+    expect(rule.fault).toEqual({ kind: "abort" });
+  });
+
+  it("faults.abort passes errorCode through", () => {
+    const rule = faults.abort({ urlPattern: "t", errorCode: "internetdisconnected" });
+    expect(rule.fault).toEqual({ kind: "abort", errorCode: "internetdisconnected" });
+  });
+
+  it("faults.delay wraps ms", () => {
+    const rule = faults.delay(2000, { urlPattern: "/slow" });
+    expect(rule.fault).toEqual({ kind: "delay", ms: 2000 });
+  });
+
+  it("forwards common options (name, methods, probability)", () => {
+    const rule = faults.status(500, {
+      urlPattern: "/api",
+      name: "api-500",
+      methods: ["POST"],
+      probability: 0.5,
+    });
+    expect(rule.name).toBe("api-500");
+    expect(rule.methods).toEqual(["POST"]);
+    expect(rule.probability).toBe(0.5);
+  });
+
+  it("omits common options when not set (no undefined pollution)", () => {
+    const rule = faults.status(500, { urlPattern: "/api" });
+    expect(rule).not.toHaveProperty("name");
+    expect(rule).not.toHaveProperty("methods");
+    expect(rule).not.toHaveProperty("probability");
+  });
+});
+
+describe("lifecycle fault helpers", () => {
+  it("faults.cpu wraps CPU throttle rate with a sensible default stage", () => {
+    const lf = faults.cpu(4);
+    expect(lf.action).toEqual({ kind: "cpu-throttle", rate: 4 });
+    expect(lf.when).toBe("beforeNavigation");
+  });
+
+  it("faults.cpu forwards override stage / urlPattern / probability / name", () => {
+    const lf = faults.cpu(2, {
+      when: "afterLoad",
+      urlPattern: /\/heavy\//,
+      probability: 0.25,
+      name: "cpu-2x-on-heavy",
+    });
+    expect(lf).toMatchObject({
+      when: "afterLoad",
+      probability: 0.25,
+      name: "cpu-2x-on-heavy",
+      action: { kind: "cpu-throttle", rate: 2 },
+    });
+    expect(lf.urlPattern).toBeInstanceOf(RegExp);
+  });
+
+  it("faults.cpu rejects rates < 1", () => {
+    expect(() => faults.cpu(0.5)).toThrow(/rate/i);
+    expect(() => faults.cpu(0)).toThrow(/rate/i);
+    expect(() => faults.cpu(-1)).toThrow(/rate/i);
+  });
+
+  it("faults.clearStorage requires at least one scope and defaults stage to afterLoad", () => {
+    const lf = faults.clearStorage({ scopes: ["localStorage", "cookies"] });
+    expect(lf.action).toEqual({ kind: "clear-storage", scopes: ["localStorage", "cookies"] });
+    expect(lf.when).toBe("afterLoad");
+  });
+
+  it("faults.clearStorage rejects empty scope list", () => {
+    expect(() => faults.clearStorage({ scopes: [] })).toThrow(/scope/i);
+  });
+
+  it("faults.evictCache defaults to all caches and beforeActions stage", () => {
+    const lf = faults.evictCache();
+    expect(lf.action).toEqual({ kind: "evict-cache" });
+    expect(lf.when).toBe("beforeActions");
+  });
+
+  it("faults.evictCache passes specific cacheNames through", () => {
+    const lf = faults.evictCache({ cacheNames: ["v1", "static"] });
+    expect(lf.action).toEqual({ kind: "evict-cache", cacheNames: ["v1", "static"] });
+  });
+
+  it("faults.tamperStorage produces a tamper action and defaults stage to afterLoad", () => {
+    const lf = faults.tamperStorage({ scope: "localStorage", key: "auth", value: "" });
+    expect(lf.action).toEqual({
+      kind: "tamper-storage",
+      scope: "localStorage",
+      key: "auth",
+      value: "",
+    });
+    expect(lf.when).toBe("afterLoad");
+  });
+
+  it("lifecycle helpers omit name / urlPattern / probability when not provided", () => {
+    const lf = faults.cpu(4);
+    expect(lf).not.toHaveProperty("name");
+    expect(lf).not.toHaveProperty("urlPattern");
+    expect(lf).not.toHaveProperty("probability");
+  });
+});

package/src/faults.ts

@@ -0,0 +1,225 @@
+/**
+ * Small helper functions that build FaultRule objects without the
+ * discriminated-union ceremony. Exported from the package root.
+ *
+ *   import { faults } from "chaosbringer";
+ *   const rules = [
+ *     faults.status(500, { urlPattern: /\/api\// }),
+ *     faults.abort({ urlPattern: /tracking/ }),
+ *     faults.delay(2000, { urlPattern: /\/api\// }),
+ *   ];
+ */
+
+import type {
+  FaultRule,
+  LifecycleFault,
+  LifecycleStage,
+  RuntimeFault,
+  StorageScope,
+  UrlMatcher,
+} from "./types.js";
+
+export interface FaultHelperOptions {
+  urlPattern: UrlMatcher;
+  methods?: string[];
+  probability?: number;
+  name?: string;
+}
+
+function applyCommon(rule: FaultRule, opts: FaultHelperOptions): FaultRule {
+  rule.urlPattern = opts.urlPattern;
+  if (opts.methods !== undefined) rule.methods = opts.methods;
+  if (opts.probability !== undefined) rule.probability = opts.probability;
+  if (opts.name !== undefined) rule.name = opts.name;
+  return rule;
+}
+
+/** Common options accepted by every lifecycle fault helper. */
+export interface LifecycleHelperOptions {
+  /** Override the helper's default lifecycle stage. */
+  when?: LifecycleStage;
+  /** Restrict the fault to URLs matching this matcher. */
+  urlPattern?: UrlMatcher;
+  /** 0..1, default 1.0. Uses the crawler's seeded RNG. */
+  probability?: number;
+  /** Override the auto-derived stats name. */
+  name?: string;
+}
+
+function applyLifecycleCommon(
+  fault: LifecycleFault,
+  opts: LifecycleHelperOptions | undefined,
+  defaultStage: LifecycleStage,
+): LifecycleFault {
+  fault.when = opts?.when ?? defaultStage;
+  if (opts?.urlPattern !== undefined) fault.urlPattern = opts.urlPattern;
+  if (opts?.probability !== undefined) fault.probability = opts.probability;
+  if (opts?.name !== undefined) fault.name = opts.name;
+  return fault;
+}
+
+export const faults = {
+  /** Respond with `status` (and optional body / content-type). */
+  status(
+    status: number,
+    opts: FaultHelperOptions & { body?: string; contentType?: string }
+  ): FaultRule {
+    const rule: FaultRule = {
+      urlPattern: opts.urlPattern,
+      fault: {
+        kind: "status",
+        status,
+        ...(opts.body !== undefined ? { body: opts.body } : {}),
+        ...(opts.contentType !== undefined ? { contentType: opts.contentType } : {}),
+      },
+    };
+    return applyCommon(rule, opts);
+  },
+
+  /** Abort the request (e.g. to simulate a blocked third-party or transport failure). */
+  abort(opts: FaultHelperOptions & { errorCode?: string }): FaultRule {
+    const rule: FaultRule = {
+      urlPattern: opts.urlPattern,
+      fault: {
+        kind: "abort",
+        ...(opts.errorCode !== undefined ? { errorCode: opts.errorCode } : {}),
+      },
+    };
+    return applyCommon(rule, opts);
+  },
+
+  /** Wait `ms` milliseconds, then continue the request unchanged. */
+  delay(ms: number, opts: FaultHelperOptions): FaultRule {
+    const rule: FaultRule = {
+      urlPattern: opts.urlPattern,
+      fault: { kind: "delay", ms },
+    };
+    return applyCommon(rule, opts);
+  },
+
+  /**
+   * Apply CDP CPU throttling. `rate` is a multiplier ≥ 1 (1 = no throttle,
+   * 4 = ~4× slower). Default stage is `beforeNavigation` so the load itself
+   * is slowed.
+   */
+  cpu(rate: number, opts?: LifecycleHelperOptions): LifecycleFault {
+    if (!Number.isFinite(rate) || rate < 1) {
+      throw new Error(`faults.cpu: rate must be a finite number >= 1 (got ${rate})`);
+    }
+    const fault: LifecycleFault = {
+      when: "beforeNavigation",
+      action: { kind: "cpu-throttle", rate },
+    };
+    return applyLifecycleCommon(fault, opts, "beforeNavigation");
+  },
+
+  /**
+   * Wipe the listed storage scopes. Cookies are cleared at the BrowserContext
+   * level; `localStorage` / `sessionStorage` / `indexedDB` are cleared in-page.
+   * Default stage is `afterLoad` so the page exists when the wipe runs.
+   */
+  clearStorage(
+    opts: LifecycleHelperOptions & { scopes: StorageScope[] },
+  ): LifecycleFault {
+    if (!opts.scopes || opts.scopes.length === 0) {
+      throw new Error("faults.clearStorage: at least one scope is required");
+    }
+    const fault: LifecycleFault = {
+      when: "afterLoad",
+      action: { kind: "clear-storage", scopes: [...opts.scopes] },
+    };
+    return applyLifecycleCommon(fault, opts, "afterLoad");
+  },
+
+  /**
+   * Drop entries from the Service Worker `caches` API. With no `cacheNames`,
+   * every cache is dropped. Default stage is `beforeActions` so the wipe
+   * happens after invariants but before chaos clicks.
+   */
+  evictCache(
+    opts?: LifecycleHelperOptions & { cacheNames?: string[] },
+  ): LifecycleFault {
+    const fault: LifecycleFault = {
+      when: "beforeActions",
+      action:
+        opts?.cacheNames !== undefined
+          ? { kind: "evict-cache", cacheNames: [...opts.cacheNames] }
+          : { kind: "evict-cache" },
+    };
+    return applyLifecycleCommon(fault, opts, "beforeActions");
+  },
+
+  /**
+   * Set a single key/value in `localStorage` or `sessionStorage`. Empty value
+   * mimics a logged-out / token-cleared state without dropping unrelated keys.
+   */
+  tamperStorage(
+    opts: LifecycleHelperOptions & {
+      scope: "localStorage" | "sessionStorage";
+      key: string;
+      value: string;
+    },
+  ): LifecycleFault {
+    const fault: LifecycleFault = {
+      when: "afterLoad",
+      action: {
+        kind: "tamper-storage",
+        scope: opts.scope,
+        key: opts.key,
+        value: opts.value,
+      },
+    };
+    return applyLifecycleCommon(fault, opts, "afterLoad");
+  },
+
+  /**
+   * Reject `window.fetch` calls before any network round-trip. Different
+   * from `faults.abort()` (request-scoped, applied via Playwright `route`):
+   * `flakyFetch` rejects the Promise client-side with a TypeError, so any
+   * `try/catch` and Service-Worker fallbacks downstream of `fetch` engage
+   * just like a real "Failed to fetch" event.
+   */
+  flakyFetch(opts?: RuntimeHelperOptions & { rejectionMessage?: string }): RuntimeFault {
+    const fault: RuntimeFault = {
+      action: {
+        kind: "flaky-fetch",
+        ...(opts?.rejectionMessage !== undefined
+          ? { rejectionMessage: opts.rejectionMessage }
+          : {}),
+      },
+    };
+    return applyRuntimeCommon(fault, opts);
+  },
+
+  /**
+   * Skew `Date.now()`, `performance.now()`, and the no-arg `Date`
+   * constructor forward by `skewMs`. Use to surface token-expiry,
+   * cache-bust, and "clock drift" code paths without waiting real time.
+   */
+  clockSkew(skewMs: number, opts?: RuntimeHelperOptions): RuntimeFault {
+    if (!Number.isFinite(skewMs) || !Number.isInteger(skewMs)) {
+      throw new Error(`faults.clockSkew: skewMs must be a finite integer (got ${skewMs})`);
+    }
+    const fault: RuntimeFault = { action: { kind: "clock-skew", skewMs } };
+    return applyRuntimeCommon(fault, opts);
+  },
+};
+
+export interface RuntimeHelperOptions {
+  /** Restrict the fault to pages whose URL matches this matcher. */
+  urlPattern?: UrlMatcher;
+  /** 0..1, default 1.0. Rolled per call against the in-page seeded RNG. */
+  probability?: number;
+  /** Override the auto-derived stats name. */
+  name?: string;
+}
+
+function applyRuntimeCommon(
+  fault: RuntimeFault,
+  opts: RuntimeHelperOptions | undefined,
+): RuntimeFault {
+  if (opts?.urlPattern !== undefined) fault.urlPattern = opts.urlPattern;
+  if (opts?.probability !== undefined) fault.probability = opts.probability;
+  if (opts?.name !== undefined) fault.name = opts.name;
+  return fault;
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+// Types
+export type {
+  Fault,
+  FaultInjectionStats,
+  FaultRule,
+  LifecycleAction,
+  LifecycleFault,
+  LifecycleFaultStats,
+  LifecycleStage,
+  Rng,
+  RuntimeAction,
+  RuntimeFault,
+  RuntimeFaultStats,
+  StorageScope,
+  UrlMatcher,
+} from "./types.js";
+
+// Network-level (FaultRule helpers + builders)
+export {
+  faults,
+  type FaultHelperOptions,
+  type LifecycleHelperOptions,
+  type RuntimeHelperOptions,
+} from "./faults.js";
+
+// Runtime-level (addInitScript-based monkey patches)
+export {
+  buildRuntimeFaultsScript,
+  compileRuntimeFaults,
+  mergeRuntimeStats,
+  runtimeFaultName,
+  runtimeMatchesUrl,
+  type CompiledRuntimeFault,
+} from "./runtime-faults.js";
+
+// Page lifecycle (Playwright Page / BrowserContext at named stages)
+export {
+  compileLifecycleFaults,
+  executeLifecycleAction,
+  lifecycleFaultName,
+  lifecycleFaultsAtStage,
+  lifecycleMatchesUrl,
+  lifecycleStatsFrom,
+  PlaywrightLifecycleExecutor,
+  shouldFireProbability,
+  type CompiledLifecycleFault,
+  type LifecycleActionExecutor,
+} from "./lifecycle-faults.js";