@chaos-maker/playwright 0.4.0 → 0.6.0

package/README.md

@@ -8,7 +8,7 @@ Playwright adapter for [`@chaos-maker/core`](../core/). One-line chaos injection
 npm install @chaos-maker/core @chaos-maker/playwright
 ```
 
-Both packages are required — `@chaos-maker/playwright` loads the core UMD bundle into the browser page.
+Both packages are required - `@chaos-maker/playwright` loads the core UMD bundle into the browser page.
 
 ## Usage
 
@@ -19,21 +19,27 @@ import { test, expect } from '@playwright/test';
 import { injectChaos, removeChaos, getChaosLog } from '@chaos-maker/playwright';
 
 test('shows error when API fails', async ({ page }) => {
-  await injectChaos(page, {
-    network: {
-      failures: [{ urlPattern: '/api/data', statusCode: 503, probability: 1.0 }]
-    }
-  });
-
-  await page.goto('/dashboard');
-  await expect(page.getByText('Something went wrong')).toBeVisible();
-
-  // Check what chaos was applied
-  const log = await getChaosLog(page);
-  expect(log.some(e => e.type === 'network:failure' && e.applied)).toBe(true);
+  try {
+    await injectChaos(page, {
+      network: {
+        failures: [{ urlPattern: '/api/data', statusCode: 503, probability: 1.0 }]
+      }
+    });
+
+    await page.goto('/dashboard');
+    await expect(page.getByText('Something went wrong')).toBeVisible();
+
+    // Check what chaos was applied
+    const log = await getChaosLog(page);
+    expect(log.some(e => e.type === 'network:failure' && e.applied)).toBe(true);
+  } finally {
+    await removeChaos(page);
+  }
 });
 ```
 
+For direct API calls, use `try` / `finally` when a test can fail before explicit cleanup. `removeChaos(page)` restores the current document and is safe during teardown. Playwright `addInitScript()` entries stay registered on the `Page`, so a later `page.reload()` or `page.goto()` on the same reused page can run prior chaos init scripts again. Prefer the fixture, Playwright's default fresh page per test, or a new page/context when reload isolation matters.
+
 ### Test Fixture
 
 For automatic cleanup, use the built-in fixture:
@@ -59,6 +65,27 @@ test('handles slow network', async ({ page, chaos }) => {
 
 ### With Presets
 
+Drop a built-in preset by name with the declarative `presets` field:
+
+```ts
+await injectChaos(page, { presets: ['slow-api'] });
+```
+
+Register your own bundle inline via `customPresets`:
+
+```ts
+await injectChaos(page, {
+  customPresets: {
+    'team-flow': {
+      network: { failures: [{ urlPattern: '/checkout', statusCode: 503, probability: 1 }] },
+    },
+  },
+  presets: ['team-flow'],
+});
+```
+
+The legacy spread style still works for migration:
+
 ```ts
 import { test, expect } from '@playwright/test';
 import { presets } from '@chaos-maker/core';
@@ -90,6 +117,49 @@ test('checkout handles combined chaos', async ({ page }) => {
 });
 ```
 
+### Rule Groups
+
+Use Rule Groups to toggle a set of rules during a test without reinjecting chaos.
+
+```ts
+import { test, expect } from '@playwright/test';
+import { ChaosConfigBuilder } from '@chaos-maker/core';
+import {
+  injectChaos,
+  enableGroup,
+  disableGroup,
+  enableSWGroup,
+  disableSWGroup,
+} from '@chaos-maker/playwright';
+
+test('toggles checkout chaos', async ({ page }) => {
+  const config = new ChaosConfigBuilder()
+    .defineGroup('payments', { enabled: false })
+    .inGroup('payments')
+    .failRequests('/api/pay', 503, 1)
+    .build();
+
+  await injectChaos(page, config);
+  await page.goto('/checkout');
+
+  await enableGroup(page, 'payments');
+  await expect(page.getByText('Try again')).toBeVisible();
+
+  await disableGroup(page, 'payments');
+});
+```
+
+With the fixture, the same helpers are available as `chaos.enableGroup(name)` and `chaos.disableGroup(name)`.
+
+For Service Worker rules, use the SW helpers after `injectSWChaos`:
+
+```ts
+await enableSWGroup(page, 'payments');
+await disableSWGroup(page, 'payments');
+```
+
+Browser-side `enableGroup` and `disableGroup` affect page rules from `injectChaos`. `enableSWGroup` and `disableSWGroup` affect Service Worker rules from `injectSWChaos`.
+
 ### SSE and GraphQL
 
 ```ts
@@ -118,32 +188,65 @@ SSE chaos and GraphQL operation matching use the same pre-navigation `injectChao
 
 Inject chaos into a Playwright page. **Call before `page.goto()`** to ensure all network requests are intercepted from the start.
 
-- `page` — Playwright `Page` instance
-- `config` — `ChaosConfig` object (see [@chaos-maker/core](../core/) for full config reference)
-- `opts` — optional. `InjectChaosOptions`:
-  - `tracing?: boolean | 'auto'` — emit chaos events into the Playwright trace (see [Debugging with trace](#debugging-with-trace)). Requires `testInfo` when `true`.
-  - `testInfo?: TestInfo` — active Playwright `TestInfo` (supplied automatically by the fixture).
-  - `traceOptions?: { verbose?: boolean; attachmentName?: string }` — tune trace output.
+- `page` - Playwright `Page` instance
+- `config` - `ChaosConfig` object (see [@chaos-maker/core](../core/) for full config reference)
+- `opts` - optional. `InjectChaosOptions`:
+  - `tracing?: boolean | 'auto'` - emit chaos events into the Playwright trace (see [Debugging with trace](#debugging-with-trace)). Requires `testInfo` when `true`.
+  - `testInfo?: TestInfo` - active Playwright `TestInfo` (supplied automatically by the fixture).
+  - `traceOptions?: { verbose?: boolean; attachmentName?: string }` - tune trace output.
 
 ### `removeChaos(page)`
 
 Stop chaos and restore original `fetch`/`XHR`/DOM behavior.
 
+This restores the active document. It does not remove Playwright `addInitScript()` registrations from a reused `Page`, because Playwright does not expose a removal API for them.
+
 ### `getChaosLog(page)`
 
-Retrieve the chaos event log from the page. Returns `ChaosEvent[]` — every chaos check emitted since injection, with `applied: true/false`.
+Retrieve the chaos event log from the page. Returns `ChaosEvent[]` - every chaos check emitted since injection, with `applied: true/false`.
+
+### `enableGroup(page, name)` / `disableGroup(page, name)`
+
+Toggle a browser-side Rule Group at runtime.
+
+### `enableSWGroup(page, name, opts?)` / `disableSWGroup(page, name, opts?)`
+
+Toggle a Service Worker Rule Group at runtime. Pass `opts.timeoutMs` to override the Service Worker acknowledgement timeout.
 
 ### Fixture: `chaos`
 
 Available when importing `test` from `@chaos-maker/playwright/fixture`:
 
-- `chaos.inject(config)` — same as `injectChaos(page, config)`
-- `chaos.remove()` — same as `removeChaos(page)` (also called automatically after each test)
-- `chaos.getLog()` — same as `getChaosLog(page)`
+- `chaos.inject(config)` - same as `injectChaos(page, config)`
+- `chaos.remove()` - same as `removeChaos(page)` (also called automatically after each test)
+- `chaos.getLog()` - same as `getChaosLog(page)`
+- `chaos.enableGroup(name)` - same as `enableGroup(page, name)`
+- `chaos.disableGroup(name)` - same as `disableGroup(page, name)`
+- `chaos.enableSWGroup(name, opts?)` - same as `enableSWGroup(page, name, opts)`
+- `chaos.disableSWGroup(name, opts?)` - same as `disableSWGroup(page, name, opts)`
+
+## Validation
+
+`injectChaos` validates the config from Node BEFORE any page touch. A malformed config throws `ChaosConfigError` synchronously from the test runner - your test fails before navigation, not in the browser console. `ChaosConfigError.issues` is a structured `ValidationIssue[]` with `path`, `code`, `ruleType`, and optional `expected` / `received`. See the [Rule Validation concept page](https://chaos-maker-dev.github.io/chaos-maker/concepts/validation/).
+
+```ts
+import { injectChaos, ChaosConfigError } from '@chaos-maker/playwright';
+
+try {
+  await injectChaos(page, config, {
+    validation: { unknownFields: 'warn' },
+  });
+} catch (e) {
+  if (e instanceof ChaosConfigError) {
+    for (const issue of e.issues) console.error(issue.path, issue.code, issue.message);
+  }
+  throw e;
+}
+```
 
 ## Debugging with trace
 
-When a chaos test fails, the Playwright trace viewer is the first place to look. Enable tracing in your Playwright config and use the fixture — every applied chaos decision appears inline in the trace action timeline as a `chaos:<type>` step, and the full event log is attached as `chaos-log.json`.
+When a chaos test fails, the Playwright trace viewer is the first place to look. Enable tracing in your Playwright config and use the fixture - every applied chaos decision appears inline in the trace action timeline as a `chaos:<type>` step, and the full event log is attached as `chaos-log.json`.
 
 ```ts
 // playwright.config.ts
@@ -189,6 +292,18 @@ test('with direct API', async ({ page }, testInfo) => {
 });
 ```
 
+## Leak diagnostics
+
+Enable `debug: true` on the chaos config to surface leaked-runtime diagnostics in the event log. Filter `getChaosLog(page)` for `type === 'debug'` events with `detail.reason` covering double-patched globals, stale wrapper handles, orphaned observers, or active-instance conflicts. See [`@chaos-maker/core`](../core/README.md#leak-diagnostics) for the full reason list.
+
+```ts
+await injectChaos(page, { debug: true, network: { /* ... */ } });
+await page.goto('/');
+const issues = (await getChaosLog(page)).filter(
+  (e) => e.type === 'debug' && /already-patched|stale|orphaned|active-instance-conflict/.test(String(e.detail.reason ?? '')),
+);
+```
+
 ## Service Worker chaos
 
 Intercept SW-originated fetches. Requires one line in your service-worker script.
@@ -199,25 +314,41 @@ importScripts('/chaos-maker-sw.js');
 ```
 
 ```ts
-import { injectSWChaos, removeSWChaos, getSWChaosLog } from '@chaos-maker/playwright';
+import {
+  injectSWChaos,
+  removeSWChaos,
+  getSWChaosLog,
+  getSWChaosLogFromSW,
+  enableSWGroup,
+  disableSWGroup,
+} from '@chaos-maker/playwright';
 
 test('SW-fetched /api returns 503', async ({ page }) => {
   await page.goto('/app-with-sw/');
   // wait for controller after your app's SW registration
   await injectSWChaos(page, {
-    network: { failures: [{ urlPattern: '/api/data', statusCode: 503, probability: 1 }] },
+    groups: [{ name: 'payments', enabled: false }],
+    network: {
+      failures: [{ urlPattern: '/api/data', statusCode: 503, probability: 1, group: 'payments' }],
+    },
     seed: 1,
   });
+  await enableSWGroup(page, 'payments');
   await page.click('#trigger');
   const log = await getSWChaosLog(page);
   expect(log.some(e => e.type === 'network:failure' && e.applied)).toBe(true);
+  await disableSWGroup(page, 'payments');
   await removeSWChaos(page);
 });
 ```
 
+Use `getSWChaosLog(page)` for the page-buffered event log. This is the default assertion surface because it reflects events broadcast from the Service Worker to the page. Use `getSWChaosLogFromSW(page)` when you need a direct pull from the Service Worker's in-memory log, such as debugging a missed page-side broadcast.
+
+`removeSWChaos(page)` stops the worker engine and clears both the page-buffered and worker-side logs. For full browser isolation between tests, unregister the app's Service Worker or use a fresh browser context.
+
 Two artifacts ship in `@chaos-maker/core`:
-- `dist/sw.js` — IIFE bundle for classic SWs (`importScripts('/chaos-maker-sw.js')`).
-- `dist/sw.mjs` — ESM bundle for module SWs (`import { installChaosSW } from '/chaos-maker-sw.mjs'`).
+- `dist/sw.js` - IIFE bundle for classic SWs (`importScripts('/chaos-maker-sw.js')`).
+- `dist/sw.mjs` - ESM bundle for module SWs (`import { installChaosSW } from '/chaos-maker-sw.mjs'`).
 
 Serve whichever your SW type uses at a URL reachable from the service-worker scope.
 

package/dist/chunk-ZJZRSTXG.js

@@ -0,0 +1,324 @@
+// src/index.ts
+import { serializeForTransport, validateChaosConfig as validateChaosConfig2 } from "@chaos-maker/core";
+import { resolve, dirname } from "path";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+
+// src/trace.ts
+import { test } from "@playwright/test";
+import { formatStepTitle, shouldEmitStep } from "@chaos-maker/core";
+import { formatStepTitle as formatStepTitle2, shouldEmitStep as shouldEmitStep2 } from "@chaos-maker/core";
+var CHAOS_BINDING = "__chaosMakerReport";
+var TRACE_HANDLE_KEY = /* @__PURE__ */ Symbol.for("chaos-maker.playwright.traceHandle");
+var TRACE_BINDING_KEY = /* @__PURE__ */ Symbol.for("chaos-maker.playwright.traceBinding");
+async function createTraceReporter(page, testInfo, opts = {}) {
+  const existing = page[TRACE_HANDLE_KEY];
+  if (existing) return existing;
+  const verbose = opts.verbose ?? false;
+  const attachmentName = opts.attachmentName ?? "chaos-log.json";
+  const events = [];
+  const handler = (_source, event) => {
+    events.push(event);
+    if (!shouldEmitStep(event, verbose)) return;
+    const title = formatStepTitle(event);
+    test.step(title, async () => {
+    }).catch(() => {
+    });
+  };
+  let state = page[TRACE_BINDING_KEY];
+  if (!state) {
+    state = { handler };
+    page[TRACE_BINDING_KEY] = state;
+    await page.exposeBinding(CHAOS_BINDING, (source, event) => {
+      state.handler(source, event);
+    });
+    await page.addInitScript((bindingName) => {
+      const win = globalThis;
+      const attach = () => {
+        const utils = win.chaosUtils;
+        if (!utils || !utils.instance) return false;
+        if (utils.__chaosMakerTraceBound === utils.instance) return true;
+        utils.__chaosMakerTraceBound = utils.instance;
+        utils.instance.on("*", (event) => {
+          try {
+            if (typeof win[bindingName] === "function") {
+              win[bindingName](event);
+            }
+          } catch {
+          }
+        });
+        return true;
+      };
+      if (attach()) return;
+      const intervalId = setInterval(() => {
+        if (attach()) clearInterval(intervalId);
+      }, 10);
+      setTimeout(() => clearInterval(intervalId), 5e3);
+    }, CHAOS_BINDING);
+  } else {
+    state.handler = handler;
+  }
+  const handle = {
+    events,
+    dispose: async (seed = null) => {
+      const payload = {
+        seed,
+        eventCount: events.length,
+        events
+      };
+      try {
+        await testInfo.attach(attachmentName, {
+          body: Buffer.from(JSON.stringify(payload, null, 2), "utf-8"),
+          contentType: "application/json"
+        });
+      } catch {
+      }
+      if (page[TRACE_HANDLE_KEY] === handle) {
+        delete page[TRACE_HANDLE_KEY];
+      }
+    }
+  };
+  page[TRACE_HANDLE_KEY] = handle;
+  return handle;
+}
+
+// src/index.ts
+import { Logger } from "@chaos-maker/core";
+import { validateChaosConfig as validateChaosConfig3, ChaosConfigError, formatSeedReproduction } from "@chaos-maker/core";
+
+// src/sw.ts
+import { validateChaosConfig, SW_BRIDGE_SOURCE } from "@chaos-maker/core";
+var BRIDGE_INIT_KEY = /* @__PURE__ */ Symbol.for("chaos-maker.playwright.sw.bridgeInit");
+var DEFAULT_SW_TOGGLE_TIMEOUT = 2e3;
+async function ensurePageBridge(page) {
+  if (!page[BRIDGE_INIT_KEY]) {
+    await page.addInitScript({ content: SW_BRIDGE_SOURCE });
+    page[BRIDGE_INIT_KEY] = true;
+  }
+  await page.evaluate(SW_BRIDGE_SOURCE).catch(() => {
+  });
+}
+async function injectSWChaos(page, config, opts = {}) {
+  const validated = validateChaosConfig(config, opts.validation);
+  const timeoutMs = opts.timeoutMs ?? 1e4;
+  await ensurePageBridge(page);
+  const result = await page.evaluate(
+    async ({ cfg, timeoutMs: timeoutMs2 }) => {
+      const bridge = globalThis.__chaosMakerSWBridge;
+      if (!bridge) throw new Error("[chaos-maker] SW bridge missing from page \u2014 ensurePageBridge failed");
+      return await bridge.apply(cfg, timeoutMs2);
+    },
+    { cfg: validated, timeoutMs }
+  );
+  return result;
+}
+async function removeSWChaos(page, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 5e3;
+  await page.evaluate(
+    async ({ timeoutMs: timeoutMs2 }) => {
+      const bridge = globalThis.__chaosMakerSWBridge;
+      if (!bridge) return;
+      try {
+        await bridge.stop(timeoutMs2);
+      } finally {
+        bridge.clearLocalLog();
+        await bridge.clearRemoteLog?.(timeoutMs2).catch(() => void 0);
+      }
+    },
+    { timeoutMs }
+  ).catch(() => {
+  });
+}
+async function enableSWGroup(page, name, opts = {}) {
+  if (typeof name !== "string") {
+    throw new Error("[chaos-maker] group name must be a string");
+  }
+  const nameNorm = name.trim();
+  if (!nameNorm) {
+    throw new Error("[chaos-maker] group name cannot be empty");
+  }
+  await toggleSWGroup(page, nameNorm, true, opts);
+}
+async function disableSWGroup(page, name, opts = {}) {
+  if (typeof name !== "string") {
+    throw new Error("[chaos-maker] group name must be a string");
+  }
+  const nameNorm = name.trim();
+  if (!nameNorm) {
+    throw new Error("[chaos-maker] group name cannot be empty");
+  }
+  await toggleSWGroup(page, nameNorm, false, opts);
+}
+async function toggleSWGroup(page, name, enabled, opts) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_SW_TOGGLE_TIMEOUT;
+  await ensurePageBridge(page);
+  await page.evaluate(
+    async ({ n, e, t }) => {
+      const bridge = globalThis.__chaosMakerSWBridge;
+      if (!bridge) throw new Error("[chaos-maker] SW bridge missing \u2014 ensurePageBridge failed");
+      await bridge.toggleGroup(n, e, t);
+    },
+    { n: name, e: enabled, t: timeoutMs }
+  );
+}
+async function getSWChaosLog(page) {
+  return page.evaluate(() => {
+    const bridge = globalThis.__chaosMakerSWBridge;
+    if (!bridge) return [];
+    return bridge.getLocalLog();
+  });
+}
+async function getSWChaosLogFromSW(page, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 5e3;
+  return page.evaluate(
+    async ({ timeoutMs: timeoutMs2 }) => {
+      const bridge = globalThis.__chaosMakerSWBridge;
+      if (!bridge) return [];
+      return bridge.getRemoteLog(timeoutMs2);
+    },
+    { timeoutMs }
+  );
+}
+
+// src/index.ts
+var cachedUmdPath = null;
+function getCoreUmdPath() {
+  if (cachedUmdPath) return cachedUmdPath;
+  const currentDir = typeof __dirname !== "undefined" ? __dirname : dirname(fileURLToPath(import.meta.url));
+  const req = createRequire(resolve(currentDir, "package.json"));
+  const coreEntry = req.resolve("@chaos-maker/core");
+  const coreDistDir = dirname(coreEntry);
+  cachedUmdPath = resolve(coreDistDir, "chaos-maker.umd.js");
+  return cachedUmdPath;
+}
+var TRACE_HANDLE_KEY2 = /* @__PURE__ */ Symbol.for("chaos-maker.playwright.traceHandle");
+async function injectChaos(page, config, opts = {}) {
+  const validated = validateChaosConfig2(config, opts.validation);
+  const umdPath = getCoreUmdPath();
+  const tracingEnabled = resolveTracing(opts);
+  if (tracingEnabled) {
+    if (!opts.testInfo) {
+      throw new Error(
+        "[chaos-maker] tracing requires a `testInfo` in InjectChaosOptions. Use the fixture (`@chaos-maker/playwright/fixture`) or pass testInfo explicitly."
+      );
+    }
+    const existing = page[TRACE_HANDLE_KEY2];
+    if (!existing) {
+      const handle = await createTraceReporter(page, opts.testInfo, opts.traceOptions);
+      page[TRACE_HANDLE_KEY2] = handle;
+    }
+  }
+  const serialized = serializeForTransport(validated);
+  await page.addInitScript((cfg) => {
+    const win = globalThis;
+    win.__CHAOS_CONFIG__ = cfg;
+  }, serialized);
+  await page.addInitScript({ path: umdPath });
+}
+function resolveTracing(opts) {
+  if (opts.tracing === true) return true;
+  if (opts.tracing === false || opts.tracing === void 0) return false;
+  return false;
+}
+async function removeChaos(page) {
+  const handle = page[TRACE_HANDLE_KEY2];
+  let seed = null;
+  if (handle) {
+    try {
+      seed = await getChaosSeed(page);
+    } catch {
+    }
+  }
+  await page.evaluate(() => {
+    const win = globalThis;
+    if (win.chaosUtils) {
+      win.chaosUtils.stop();
+    }
+  }).catch(() => {
+  });
+  if (handle) {
+    await handle.dispose(seed);
+    delete page[TRACE_HANDLE_KEY2];
+  }
+}
+async function getChaosLog(page) {
+  return page.evaluate(() => {
+    const win = globalThis;
+    if (win.chaosUtils) {
+      return win.chaosUtils.getLog();
+    }
+    return [];
+  });
+}
+async function enableGroup(page, name) {
+  if (typeof name !== "string") {
+    throw new Error("[chaos-maker] group name must be a string");
+  }
+  const nameNorm = name.trim();
+  if (!nameNorm) {
+    throw new Error("[chaos-maker] group name cannot be empty");
+  }
+  await page.evaluate(({ n }) => {
+    const utils = globalThis.chaosUtils;
+    if (!utils || !utils.instance) {
+      throw new Error("[chaos-maker] no chaos instance on page \u2014 call injectChaos first");
+    }
+    if (typeof utils.enableGroup !== "function") {
+      throw new Error("[chaos-maker] enableGroup API unavailable");
+    }
+    const result = utils.enableGroup(n);
+    if (result && result.success === false) {
+      throw new Error(`[chaos-maker] enableGroup('${n}') failed: ${result.message}`);
+    }
+  }, { n: nameNorm });
+}
+async function disableGroup(page, name) {
+  if (typeof name !== "string") {
+    throw new Error("[chaos-maker] group name must be a string");
+  }
+  const nameNorm = name.trim();
+  if (!nameNorm) {
+    throw new Error("[chaos-maker] group name cannot be empty");
+  }
+  await page.evaluate(({ n }) => {
+    const utils = globalThis.chaosUtils;
+    if (!utils || !utils.instance) {
+      throw new Error("[chaos-maker] no chaos instance on page \u2014 call injectChaos first");
+    }
+    if (typeof utils.disableGroup !== "function") {
+      throw new Error("[chaos-maker] disableGroup API unavailable");
+    }
+    const result = utils.disableGroup(n);
+    if (result && result.success === false) {
+      throw new Error(`[chaos-maker] disableGroup('${n}') failed: ${result.message}`);
+    }
+  }, { n: nameNorm });
+}
+async function getChaosSeed(page) {
+  return page.evaluate(() => {
+    const win = globalThis;
+    if (win.chaosUtils) {
+      return win.chaosUtils.getSeed();
+    }
+    return null;
+  });
+}
+
+export {
+  injectSWChaos,
+  removeSWChaos,
+  enableSWGroup,
+  disableSWGroup,
+  getSWChaosLog,
+  getSWChaosLogFromSW,
+  injectChaos,
+  removeChaos,
+  getChaosLog,
+  enableGroup,
+  disableGroup,
+  getChaosSeed,
+  Logger,
+  validateChaosConfig3 as validateChaosConfig,
+  ChaosConfigError,
+  formatSeedReproduction
+};