@mizchi/playwright-faults 0.1.0

package/src/lifecycle-faults.test.ts

@@ -0,0 +1,252 @@
+import { describe, expect, it } from "vitest";
+import { createRng } from "./random.js";
+import {
+  compileLifecycleFaults,
+  executeLifecycleAction,
+  lifecycleFaultName,
+  lifecycleFaultsAtStage,
+  lifecycleMatchesUrl,
+  lifecycleStatsFrom,
+  shouldFireProbability,
+  type LifecycleActionExecutor,
+} from "./lifecycle-faults.js";
+import type { LifecycleFault } from "./types.js";
+
+describe("lifecycleFaultName", () => {
+  it("uses fault.name when set", () => {
+    const f: LifecycleFault = {
+      name: "explicit",
+      when: "afterLoad",
+      action: { kind: "clear-storage", scopes: ["localStorage"] },
+    };
+    expect(lifecycleFaultName(f)).toBe("explicit");
+  });
+
+  it("derives a label per action kind", () => {
+    expect(
+      lifecycleFaultName({
+        when: "beforeNavigation",
+        action: { kind: "cpu-throttle", rate: 4 },
+      }),
+    ).toBe("cpu-throttle:4x");
+
+    expect(
+      lifecycleFaultName({
+        when: "afterLoad",
+        action: { kind: "clear-storage", scopes: ["localStorage", "cookies"] },
+      }),
+    ).toBe("clear-storage:localStorage+cookies");
+
+    expect(
+      lifecycleFaultName({
+        when: "beforeActions",
+        action: { kind: "evict-cache" },
+      }),
+    ).toBe("evict-cache");
+
+    expect(
+      lifecycleFaultName({
+        when: "beforeActions",
+        action: { kind: "evict-cache", cacheNames: ["v1"] },
+      }),
+    ).toBe("evict-cache:v1");
+
+    expect(
+      lifecycleFaultName({
+        when: "afterLoad",
+        action: { kind: "tamper-storage", scope: "localStorage", key: "auth", value: "" },
+      }),
+    ).toBe("tamper-storage:localStorage.auth");
+  });
+});
+
+describe("compileLifecycleFaults", () => {
+  it("returns [] for undefined / empty", () => {
+    expect(compileLifecycleFaults(undefined)).toEqual([]);
+    expect(compileLifecycleFaults([])).toEqual([]);
+  });
+
+  it("compiles regex patterns from string and RegExp matchers", () => {
+    const c = compileLifecycleFaults([
+      {
+        when: "afterLoad",
+        urlPattern: "/dashboard",
+        action: { kind: "clear-storage", scopes: ["localStorage"] },
+      },
+      {
+        when: "afterLoad",
+        urlPattern: /\/api\//,
+        action: { kind: "clear-storage", scopes: ["localStorage"] },
+      },
+    ]);
+    expect(c[0]!.pattern).toBeInstanceOf(RegExp);
+    expect(c[0]!.pattern!.test("/dashboard/home")).toBe(true);
+    expect(c[1]!.pattern).toBeInstanceOf(RegExp);
+    expect(c[1]!.pattern!.test("/api/x")).toBe(true);
+  });
+
+  it("leaves pattern null when urlPattern is omitted", () => {
+    const c = compileLifecycleFaults([
+      {
+        when: "afterLoad",
+        action: { kind: "clear-storage", scopes: ["localStorage"] },
+      },
+    ]);
+    expect(c[0]!.pattern).toBeNull();
+  });
+
+  it("derives the name from the action when not provided", () => {
+    const c = compileLifecycleFaults([
+      { when: "beforeNavigation", action: { kind: "cpu-throttle", rate: 8 } },
+    ]);
+    expect(c[0]!.name).toBe("cpu-throttle:8x");
+  });
+});
+
+describe("lifecycleMatchesUrl", () => {
+  it("matches every URL when pattern is null", () => {
+    expect(lifecycleMatchesUrl({ pattern: null }, "anything")).toBe(true);
+  });
+
+  it("delegates to the compiled regex when present", () => {
+    expect(lifecycleMatchesUrl({ pattern: /^\/api\// }, "/api/x")).toBe(true);
+    expect(lifecycleMatchesUrl({ pattern: /^\/api\// }, "/static/x")).toBe(false);
+  });
+});
+
+describe("shouldFireProbability", () => {
+  it("treats undefined / >=1 as always-fire and never consumes the RNG", () => {
+    let calls = 0;
+    const rng = {
+      next() {
+        calls++;
+        return 0.5;
+      },
+    };
+    expect(shouldFireProbability(undefined, rng)).toBe(true);
+    expect(shouldFireProbability(1, rng)).toBe(true);
+    expect(shouldFireProbability(2, rng)).toBe(true);
+    expect(calls).toBe(0);
+  });
+
+  it("treats <=0 as never-fire and never consumes the RNG", () => {
+    let calls = 0;
+    const rng = {
+      next() {
+        calls++;
+        return 0.5;
+      },
+    };
+    expect(shouldFireProbability(0, rng)).toBe(false);
+    expect(shouldFireProbability(-1, rng)).toBe(false);
+    expect(calls).toBe(0);
+  });
+
+  it("samples one number from the RNG when prob is in (0, 1)", () => {
+    // mulberry32 seed 1 → first next() ≈ 0.62707
+    const rng1 = createRng(1);
+    expect(shouldFireProbability(0.7, rng1)).toBe(true); // 0.627 < 0.7
+    const rng2 = createRng(1);
+    expect(shouldFireProbability(0.5, rng2)).toBe(false); // 0.627 >= 0.5
+  });
+
+  it("consumes exactly one RNG draw when prob is in (0, 1)", () => {
+    let calls = 0;
+    const rng = {
+      next() {
+        calls++;
+        return 0.5;
+      },
+    };
+    shouldFireProbability(0.6, rng);
+    expect(calls).toBe(1);
+  });
+});
+
+describe("lifecycleFaultsAtStage", () => {
+  it("filters by `when`", () => {
+    const compiled = compileLifecycleFaults([
+      { when: "beforeNavigation", action: { kind: "cpu-throttle", rate: 2 } },
+      {
+        when: "afterLoad",
+        action: { kind: "clear-storage", scopes: ["localStorage"] },
+      },
+      { when: "beforeActions", action: { kind: "evict-cache" } },
+    ]);
+    expect(lifecycleFaultsAtStage(compiled, "afterLoad").map((c) => c.name)).toEqual([
+      "clear-storage:localStorage",
+    ]);
+    expect(lifecycleFaultsAtStage(compiled, "betweenActions")).toEqual([]);
+  });
+});
+
+describe("lifecycleStatsFrom", () => {
+  it("projects matched / fired / errored counters", () => {
+    const compiled = compileLifecycleFaults([
+      { when: "beforeNavigation", action: { kind: "cpu-throttle", rate: 2 } },
+    ]);
+    compiled[0]!.matched = 5;
+    compiled[0]!.fired = 3;
+    compiled[0]!.errored = 1;
+    expect(lifecycleStatsFrom(compiled)).toEqual([
+      { name: "cpu-throttle:2x", matched: 5, fired: 3, errored: 1 },
+    ]);
+  });
+});
+
+describe("executeLifecycleAction", () => {
+  function makeFakeExecutor() {
+    const calls: Array<{ method: string; args: unknown[] }> = [];
+    const exec: LifecycleActionExecutor = {
+      async cpuThrottle(rate) {
+        calls.push({ method: "cpuThrottle", args: [rate] });
+      },
+      async clearStorage(scopes) {
+        calls.push({ method: "clearStorage", args: [Array.from(scopes)] });
+      },
+      async evictCache(cacheNames) {
+        calls.push({ method: "evictCache", args: [cacheNames ? Array.from(cacheNames) : undefined] });
+      },
+      async tamperStorage(scope, key, value) {
+        calls.push({ method: "tamperStorage", args: [scope, key, value] });
+      },
+    };
+    return { exec, calls };
+  }
+
+  it("dispatches cpu-throttle to cpuThrottle", async () => {
+    const { exec, calls } = makeFakeExecutor();
+    await executeLifecycleAction({ kind: "cpu-throttle", rate: 4 }, exec);
+    expect(calls).toEqual([{ method: "cpuThrottle", args: [4] }]);
+  });
+
+  it("dispatches clear-storage to clearStorage", async () => {
+    const { exec, calls } = makeFakeExecutor();
+    await executeLifecycleAction(
+      { kind: "clear-storage", scopes: ["localStorage", "cookies"] },
+      exec,
+    );
+    expect(calls).toEqual([{ method: "clearStorage", args: [["localStorage", "cookies"]] }]);
+  });
+
+  it("dispatches evict-cache to evictCache (with and without names)", async () => {
+    const { exec, calls } = makeFakeExecutor();
+    await executeLifecycleAction({ kind: "evict-cache" }, exec);
+    await executeLifecycleAction({ kind: "evict-cache", cacheNames: ["v1"] }, exec);
+    expect(calls).toEqual([
+      { method: "evictCache", args: [undefined] },
+      { method: "evictCache", args: [["v1"]] },
+    ]);
+  });
+
+  it("dispatches tamper-storage to tamperStorage", async () => {
+    const { exec, calls } = makeFakeExecutor();
+    await executeLifecycleAction(
+      { kind: "tamper-storage", scope: "sessionStorage", key: "auth", value: "expired" },
+      exec,
+    );
+    expect(calls).toEqual([
+      { method: "tamperStorage", args: ["sessionStorage", "auth", "expired"] },
+    ]);
+  });
+});

package/src/lifecycle-faults.ts

@@ -0,0 +1,252 @@
+/**
+ * Page-lifecycle fault injection.
+ *
+ * Distinct from network-side `FaultRule` (request-scoped, applied via
+ * Playwright `route()`). These are page-scoped client-side perturbations
+ * applied at well-defined stages of a page visit — CPU throttle, storage
+ * wipe, Service Worker cache eviction, key/value tampering. The crawler
+ * decides when to call into the executor; the executor decides how to
+ * realise each `LifecycleAction` against the browser.
+ *
+ * Pure helpers (compile / match / probability roll / name derivation) live
+ * here so the routing logic is unit-testable without a real browser. The
+ * Playwright-backed executor lives at the bottom of this file.
+ */
+
+import type { BrowserContext, CDPSession, Page } from "playwright";
+import type {
+  LifecycleAction,
+  LifecycleFault,
+  LifecycleFaultStats,
+  LifecycleStage,
+  UrlMatcher,
+} from "./types.js";
+
+/** Compiled form: regex pre-compiled, name pre-derived. */
+export interface CompiledLifecycleFault {
+  fault: LifecycleFault;
+  /** null when `fault.urlPattern` was omitted (matches every URL). */
+  pattern: RegExp | null;
+  name: string;
+  matched: number;
+  fired: number;
+  errored: number;
+}
+
+/** Auto-derive a stats label when the user didn't set `fault.name`. */
+export function lifecycleFaultName(fault: LifecycleFault): string {
+  if (fault.name) return fault.name;
+  const a = fault.action;
+  switch (a.kind) {
+    case "cpu-throttle":
+      return `cpu-throttle:${a.rate}x`;
+    case "clear-storage":
+      return `clear-storage:${a.scopes.join("+")}`;
+    case "evict-cache":
+      return a.cacheNames && a.cacheNames.length > 0
+        ? `evict-cache:${a.cacheNames.join("+")}`
+        : "evict-cache";
+    case "tamper-storage":
+      return `tamper-storage:${a.scope}.${a.key}`;
+  }
+}
+
+function compilePattern(matcher: UrlMatcher | undefined): RegExp | null {
+  if (matcher === undefined) return null;
+  return matcher instanceof RegExp ? matcher : new RegExp(matcher);
+}
+
+export function compileLifecycleFaults(
+  faults: LifecycleFault[] | undefined,
+): CompiledLifecycleFault[] {
+  if (!faults || faults.length === 0) return [];
+  return faults.map((fault) => ({
+    fault,
+    pattern: compilePattern(fault.urlPattern),
+    name: lifecycleFaultName(fault),
+    matched: 0,
+    fired: 0,
+    errored: 0,
+  }));
+}
+
+/** True when `compiled.pattern` matches `url` (or no pattern was set). */
+export function lifecycleMatchesUrl(
+  compiled: Pick<CompiledLifecycleFault, "pattern">,
+  url: string,
+): boolean {
+  return compiled.pattern === null || compiled.pattern.test(url);
+}
+
+/**
+ * Roll the seeded RNG against `probability`. Returns true when the fault
+ * should fire. `prob >= 1` (or undefined) always fires; `prob <= 0` never
+ * fires; anything in between samples one number from `rng`.
+ *
+ * RNG consumption is deliberately conditional on `prob < 1` so that adding
+ * a probability-1 fault to a config doesn't shift the seed sequence for
+ * existing chaos action selection.
+ */
+export function shouldFireProbability(
+  prob: number | undefined,
+  rng: { next(): number },
+): boolean {
+  if (prob === undefined || prob >= 1) return true;
+  if (prob <= 0) return false;
+  return rng.next() < prob;
+}
+
+/** Pick the compiled faults that target a given lifecycle stage. */
+export function lifecycleFaultsAtStage(
+  compiled: readonly CompiledLifecycleFault[],
+  stage: LifecycleStage,
+): CompiledLifecycleFault[] {
+  return compiled.filter((c) => c.fault.when === stage);
+}
+
+export function lifecycleStatsFrom(
+  compiled: readonly CompiledLifecycleFault[],
+): LifecycleFaultStats[] {
+  return compiled.map((c) => ({
+    name: c.name,
+    matched: c.matched,
+    fired: c.fired,
+    errored: c.errored,
+  }));
+}
+
+/**
+ * Browser-side primitives needed to realise each `LifecycleAction`. One
+ * method per action kind so tests can fake exactly what they exercise
+ * without standing up Playwright.
+ */
+export interface LifecycleActionExecutor {
+  cpuThrottle(rate: number): Promise<void>;
+  clearStorage(scopes: readonly ("localStorage" | "sessionStorage" | "cookies" | "indexedDB")[]): Promise<void>;
+  evictCache(cacheNames?: readonly string[]): Promise<void>;
+  tamperStorage(scope: "localStorage" | "sessionStorage", key: string, value: string): Promise<void>;
+}
+
+/** Dispatch a single `LifecycleAction` to the right executor method. */
+export async function executeLifecycleAction(
+  action: LifecycleAction,
+  executor: LifecycleActionExecutor,
+): Promise<void> {
+  switch (action.kind) {
+    case "cpu-throttle":
+      await executor.cpuThrottle(action.rate);
+      return;
+    case "clear-storage":
+      await executor.clearStorage(action.scopes);
+      return;
+    case "evict-cache":
+      await executor.evictCache(action.cacheNames);
+      return;
+    case "tamper-storage":
+      await executor.tamperStorage(action.scope, action.key, action.value);
+      return;
+  }
+}
+
+/**
+ * Real executor backed by Playwright. CPU throttle requires a CDP session;
+ * we attach lazily and reuse across calls on the same page.
+ */
+export class PlaywrightLifecycleExecutor implements LifecycleActionExecutor {
+  private cdp: Promise<CDPSession> | null = null;
+
+  constructor(
+    private readonly page: Page,
+    private readonly context: BrowserContext,
+  ) {}
+
+  private getCdp(): Promise<CDPSession> {
+    if (this.cdp === null) {
+      this.cdp = this.context.newCDPSession(this.page);
+    }
+    return this.cdp;
+  }
+
+  async cpuThrottle(rate: number): Promise<void> {
+    const client = await this.getCdp();
+    await client.send("Emulation.setCPUThrottlingRate", { rate });
+  }
+
+  async clearStorage(
+    scopes: readonly ("localStorage" | "sessionStorage" | "cookies" | "indexedDB")[],
+  ): Promise<void> {
+    const inPage = scopes.filter((s) => s !== "cookies");
+    if (inPage.length > 0) {
+      // page.evaluate runs in the page context; we pass the scope set so the
+      // browser side decides which storages to wipe without us injecting JS.
+      await this.page.evaluate(async (scopeList: readonly string[]) => {
+        const s = new Set(scopeList);
+        if (s.has("localStorage")) {
+          try {
+            window.localStorage.clear();
+          } catch {
+            /* SecurityError on opaque origins */
+          }
+        }
+        if (s.has("sessionStorage")) {
+          try {
+            window.sessionStorage.clear();
+          } catch {
+            /* SecurityError on opaque origins */
+          }
+        }
+        if (s.has("indexedDB") && "indexedDB" in window) {
+          // databases() is not in every browser; guard.
+          // @ts-ignore - older lib.dom typings omit databases()
+          const dbs: Array<{ name?: string }> = (await indexedDB.databases?.()) ?? [];
+          await Promise.all(
+            dbs
+              .map((d) => d.name)
+              .filter((n): n is string => typeof n === "string")
+              .map(
+                (name) =>
+                  new Promise<void>((resolve) => {
+                    const req = indexedDB.deleteDatabase(name);
+                    req.onsuccess = () => resolve();
+                    req.onerror = () => resolve();
+                    req.onblocked = () => resolve();
+                  }),
+              ),
+          );
+        }
+      }, inPage);
+    }
+    if (scopes.includes("cookies")) {
+      // Context-level: drops every cookie across every page in the context.
+      await this.context.clearCookies();
+    }
+  }
+
+  async evictCache(cacheNames?: readonly string[]): Promise<void> {
+    await this.page.evaluate(async (names: readonly string[] | undefined) => {
+      if (!("caches" in self)) return;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const c = (self as any).caches as CacheStorage;
+      const all = await c.keys();
+      const target = names && names.length > 0 ? all.filter((k) => names.includes(k)) : all;
+      await Promise.all(target.map((k) => c.delete(k)));
+    }, cacheNames);
+  }
+
+  async tamperStorage(
+    scope: "localStorage" | "sessionStorage",
+    key: string,
+    value: string,
+  ): Promise<void> {
+    await this.page.evaluate(
+      ({ scope, key, value }: { scope: "localStorage" | "sessionStorage"; key: string; value: string }) => {
+        try {
+          (scope === "localStorage" ? window.localStorage : window.sessionStorage).setItem(key, value);
+        } catch {
+          /* SecurityError on opaque origins */
+        }
+      },
+      { scope, key, value },
+    );
+  }
+}

package/src/random.ts

@@ -0,0 +1,26 @@
+/**
+ * Tiny seeded RNG used by the package's own unit tests so they don't have
+ * to depend on chaosbringer. Not part of the public surface — only re-export
+ * from `index.ts` if a downstream legitimately needs the same generator
+ * function (most won't; they'll bring their own RNG).
+ */
+
+import type { Rng } from "./types.js";
+
+export interface SeededRng extends Rng {
+  readonly seed: number;
+}
+
+export function createRng(seed: number): SeededRng {
+  let state = seed >>> 0;
+  return {
+    seed,
+    next(): number {
+      state = (state + 0x6d2b79f5) >>> 0;
+      let t = state;
+      t = Math.imul(t ^ (t >>> 15), t | 1);
+      t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    },
+  };
+}