@chaos-maker/playwright 0.1.0 → 0.2.0

package/README.md

@@ -92,12 +92,16 @@ test('checkout handles combined chaos', async ({ page }) => {
 
 ## API
 
-### `injectChaos(page, config)`
+### `injectChaos(page, config, opts?)`
 
 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.
 
 ### `removeChaos(page)`
 
@@ -115,6 +119,54 @@ Available when importing `test` from `@chaos-maker/playwright/fixture`:
 - `chaos.remove()` — same as `removeChaos(page)` (also called automatically after each test)
 - `chaos.getLog()` — same as `getChaosLog(page)`
 
+## 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`.
+
+```ts
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    trace: 'on-first-retry', // or 'on' / 'retain-on-failure'
+  },
+});
+```
+
+```ts
+import { test, expect } from '@chaos-maker/playwright/fixture';
+
+test('flaky checkout', async ({ page, chaos }) => {
+  await chaos.inject({
+    network: {
+      failures: [{ urlPattern: '/api/pay', statusCode: 503, probability: 1.0 }],
+    },
+  });
+  await page.goto('/checkout');
+  await page.click('#pay');
+  await expect(page.getByText('Order placed')).toBeVisible(); // fails
+});
+```
+
+On failure, open the trace (`pnpm exec playwright show-trace ...`). You'll see a step like:
+
+> `chaos:network:failure /api/pay → 503`
+
+…alongside the `page.click` and the failing assertion. The `chaos-log.json` attachment contains the full event stream plus the PRNG seed for exact replay.
+
+**Tracing is auto-enabled** by the fixture whenever your project's `use.trace` is anything other than `'off'`. Opt out per-call with `chaos.inject(config, { tracing: false })`.
+
+**Direct API users** must supply `testInfo` explicitly:
+
+```ts
+import { injectChaos } from '@chaos-maker/playwright';
+import { test } from '@playwright/test';
+
+test('with direct API', async ({ page }, testInfo) => {
+  await injectChaos(page, config, { tracing: true, testInfo });
+  // ...
+});
+```
+
 ## License
 
 [MIT](../../LICENSE)

package/dist/chunk-XVP3BFFM.js

@@ -0,0 +1,193 @@
+// src/index.ts
+import { resolve, dirname } from "path";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+
+// src/trace.ts
+import { test } from "@playwright/test";
+var CHAOS_BINDING = "__chaosMakerReport";
+function formatStepTitle(event) {
+  const prefix = `chaos:${event.type}`;
+  const d = event.detail ?? {};
+  const parts = [];
+  const subject = d.url ?? d.selector;
+  if (subject) parts.push(truncate(subject, 48));
+  const outcome = formatOutcome(event);
+  if (outcome) parts.push(`\u2192 ${outcome}`);
+  if (!event.applied) parts.push("(skipped)");
+  return parts.length > 0 ? `${prefix} ${parts.join(" ")}` : prefix;
+}
+function formatOutcome(event) {
+  const d = event.detail ?? {};
+  switch (event.type) {
+    case "network:failure":
+      return d.statusCode != null ? String(d.statusCode) : null;
+    case "network:latency":
+      return d.delayMs != null ? `+${d.delayMs}ms` : null;
+    case "network:abort":
+      return "abort";
+    case "network:corruption":
+      return d.strategy ?? "corrupted";
+    case "network:cors":
+      return "cors-block";
+    case "ui:assault":
+      return d.action ?? null;
+    case "websocket:drop":
+      return d.direction ? `drop ${d.direction}` : "drop";
+    case "websocket:delay":
+      return d.delayMs != null ? `delay ${d.direction ?? ""} +${d.delayMs}ms` : "delay";
+    case "websocket:corrupt":
+      return d.strategy ?? "corrupt";
+    case "websocket:close":
+      return d.closeCode != null ? `close ${d.closeCode}` : "close";
+    default:
+      return null;
+  }
+}
+function truncate(s, max) {
+  if (s.length <= max) return s;
+  return `\u2026${s.slice(-(max - 1))}`;
+}
+function shouldEmitStep(event, verbose) {
+  if (event.applied) return true;
+  return verbose;
+}
+async function createTraceReporter(page, testInfo, opts = {}) {
+  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(() => {
+    });
+  };
+  await page.exposeBinding(CHAOS_BINDING, handler);
+  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);
+  return {
+    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 {
+      }
+    }
+  };
+}
+
+// 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_KEY = /* @__PURE__ */ Symbol.for("chaos-maker.playwright.traceHandle");
+async function injectChaos(page, config, opts = {}) {
+  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_KEY];
+    if (!existing) {
+      const handle = await createTraceReporter(page, opts.testInfo, opts.traceOptions);
+      page[TRACE_HANDLE_KEY] = handle;
+    }
+  }
+  await page.addInitScript((cfg) => {
+    const win = globalThis;
+    win.__CHAOS_CONFIG__ = cfg;
+  }, config);
+  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_KEY];
+  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_KEY];
+  }
+}
+async function getChaosLog(page) {
+  return page.evaluate(() => {
+    const win = globalThis;
+    if (win.chaosUtils) {
+      return win.chaosUtils.getLog();
+    }
+    return [];
+  });
+}
+async function getChaosSeed(page) {
+  return page.evaluate(() => {
+    const win = globalThis;
+    if (win.chaosUtils) {
+      return win.chaosUtils.getSeed();
+    }
+    return null;
+  });
+}
+
+export {
+  injectChaos,
+  removeChaos,
+  getChaosLog,
+  getChaosSeed
+};

package/dist/fixture.cjs

@@ -20,16 +20,122 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/fixture.ts
 var fixture_exports = {};
 __export(fixture_exports, {
-  expect: () => import_test2.expect,
-  test: () => test
+  expect: () => import_test3.expect,
+  test: () => test2
 });
 module.exports = __toCommonJS(fixture_exports);
-var import_test = require("@playwright/test");
+var import_test2 = require("@playwright/test");
 
 // src/index.ts
 var import_path = require("path");
 var import_module = require("module");
 var import_url = require("url");
+
+// src/trace.ts
+var import_test = require("@playwright/test");
+var CHAOS_BINDING = "__chaosMakerReport";
+function formatStepTitle(event) {
+  const prefix = `chaos:${event.type}`;
+  const d = event.detail ?? {};
+  const parts = [];
+  const subject = d.url ?? d.selector;
+  if (subject) parts.push(truncate(subject, 48));
+  const outcome = formatOutcome(event);
+  if (outcome) parts.push(`\u2192 ${outcome}`);
+  if (!event.applied) parts.push("(skipped)");
+  return parts.length > 0 ? `${prefix} ${parts.join(" ")}` : prefix;
+}
+function formatOutcome(event) {
+  const d = event.detail ?? {};
+  switch (event.type) {
+    case "network:failure":
+      return d.statusCode != null ? String(d.statusCode) : null;
+    case "network:latency":
+      return d.delayMs != null ? `+${d.delayMs}ms` : null;
+    case "network:abort":
+      return "abort";
+    case "network:corruption":
+      return d.strategy ?? "corrupted";
+    case "network:cors":
+      return "cors-block";
+    case "ui:assault":
+      return d.action ?? null;
+    case "websocket:drop":
+      return d.direction ? `drop ${d.direction}` : "drop";
+    case "websocket:delay":
+      return d.delayMs != null ? `delay ${d.direction ?? ""} +${d.delayMs}ms` : "delay";
+    case "websocket:corrupt":
+      return d.strategy ?? "corrupt";
+    case "websocket:close":
+      return d.closeCode != null ? `close ${d.closeCode}` : "close";
+    default:
+      return null;
+  }
+}
+function truncate(s, max) {
+  if (s.length <= max) return s;
+  return `\u2026${s.slice(-(max - 1))}`;
+}
+function shouldEmitStep(event, verbose) {
+  if (event.applied) return true;
+  return verbose;
+}
+async function createTraceReporter(page, testInfo, opts = {}) {
+  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);
+    import_test.test.step(title, async () => {
+    }).catch(() => {
+    });
+  };
+  await page.exposeBinding(CHAOS_BINDING, handler);
+  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);
+  return {
+    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 {
+      }
+    }
+  };
+}
+
+// src/index.ts
 var import_meta = {};
 var cachedUmdPath = null;
 function getCoreUmdPath() {
@@ -41,21 +147,53 @@ function getCoreUmdPath() {
   cachedUmdPath = (0, import_path.resolve)(coreDistDir, "chaos-maker.umd.js");
   return cachedUmdPath;
 }
-async function injectChaos(page, config) {
+var TRACE_HANDLE_KEY = /* @__PURE__ */ Symbol.for("chaos-maker.playwright.traceHandle");
+async function injectChaos(page, config, opts = {}) {
   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_KEY];
+    if (!existing) {
+      const handle = await createTraceReporter(page, opts.testInfo, opts.traceOptions);
+      page[TRACE_HANDLE_KEY] = handle;
+    }
+  }
   await page.addInitScript((cfg) => {
     const win = globalThis;
     win.__CHAOS_CONFIG__ = cfg;
   }, config);
   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_KEY];
+  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_KEY];
+  }
 }
 async function getChaosLog(page) {
   return page.evaluate(() => {
@@ -66,15 +204,45 @@ async function getChaosLog(page) {
     return [];
   });
 }
+async function getChaosSeed(page) {
+  return page.evaluate(() => {
+    const win = globalThis;
+    if (win.chaosUtils) {
+      return win.chaosUtils.getSeed();
+    }
+    return null;
+  });
+}
 
 // src/fixture.ts
-var import_test2 = require("@playwright/test");
-var test = import_test.test.extend({
-  chaos: async ({ page }, use) => {
+var import_test3 = require("@playwright/test");
+function shouldAutoTrace(testInfo) {
+  const trace = testInfo.project.use?.trace;
+  if (trace == null) return false;
+  if (typeof trace === "string") return trace !== "off";
+  if (typeof trace === "object" && trace !== null && "mode" in trace) {
+    return trace.mode !== "off";
+  }
+  return false;
+}
+var test2 = import_test2.test.extend({
+  chaos: async ({ page }, use, testInfo) => {
+    const autoTrace = shouldAutoTrace(testInfo);
     const fixture = {
-      inject: (config) => injectChaos(page, config),
+      inject: (config, opts = {}) => {
+        let tracing = opts.tracing;
+        if (tracing === void 0 || tracing === "auto") {
+          tracing = autoTrace;
+        }
+        return injectChaos(page, config, {
+          ...opts,
+          tracing,
+          testInfo: opts.testInfo ?? testInfo
+        });
+      },
       remove: () => removeChaos(page),
-      getLog: () => getChaosLog(page)
+      getLog: () => getChaosLog(page),
+      getSeed: () => getChaosSeed(page)
     };
     await use(fixture);
     await removeChaos(page);

package/dist/fixture.d.cts

@@ -2,15 +2,20 @@ import * as _playwright_test from '@playwright/test';
 export { expect } from '@playwright/test';
 import { ChaosConfig, ChaosEvent } from '@chaos-maker/core';
 export { ChaosConfig, ChaosEvent } from '@chaos-maker/core';
+import { InjectChaosOptions } from './index.cjs';
 
 interface ChaosFixture {
-    inject: (config: ChaosConfig) => Promise<void>;
+    inject: (config: ChaosConfig, opts?: InjectChaosOptions) => Promise<void>;
     remove: () => Promise<void>;
     getLog: () => Promise<ChaosEvent[]>;
+    getSeed: () => Promise<number | null>;
 }
 /**
  * Extended Playwright test with a `chaos` fixture.
  *
+ * Tracing is auto-enabled when the project's `use.trace` config is not `'off'`.
+ * Override with `chaos.inject(config, { tracing: false })` to opt out.
+ *
  * @example
  * ```ts
  * import { test, expect } from '@chaos-maker/playwright/fixture';
@@ -31,4 +36,4 @@ declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArg
     chaos: ChaosFixture;
 }, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
 
-export { type ChaosFixture, test };
+export { type ChaosFixture, InjectChaosOptions, test };

package/dist/fixture.d.ts

@@ -2,15 +2,20 @@ import * as _playwright_test from '@playwright/test';
 export { expect } from '@playwright/test';
 import { ChaosConfig, ChaosEvent } from '@chaos-maker/core';
 export { ChaosConfig, ChaosEvent } from '@chaos-maker/core';
+import { InjectChaosOptions } from './index.js';
 
 interface ChaosFixture {
-    inject: (config: ChaosConfig) => Promise<void>;
+    inject: (config: ChaosConfig, opts?: InjectChaosOptions) => Promise<void>;
     remove: () => Promise<void>;
     getLog: () => Promise<ChaosEvent[]>;
+    getSeed: () => Promise<number | null>;
 }
 /**
  * Extended Playwright test with a `chaos` fixture.
  *
+ * Tracing is auto-enabled when the project's `use.trace` config is not `'off'`.
+ * Override with `chaos.inject(config, { tracing: false })` to opt out.
+ *
  * @example
  * ```ts
  * import { test, expect } from '@chaos-maker/playwright/fixture';
@@ -31,4 +36,4 @@ declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArg
     chaos: ChaosFixture;
 }, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
 
-export { type ChaosFixture, test };
+export { type ChaosFixture, InjectChaosOptions, test };

package/dist/fixture.js

@@ -1,18 +1,40 @@
 import {
   getChaosLog,
+  getChaosSeed,
   injectChaos,
   removeChaos
-} from "./chunk-BZSMGQHL.js";
+} from "./chunk-XVP3BFFM.js";
 
 // src/fixture.ts
 import { test as base } from "@playwright/test";
 import { expect } from "@playwright/test";
+function shouldAutoTrace(testInfo) {
+  const trace = testInfo.project.use?.trace;
+  if (trace == null) return false;
+  if (typeof trace === "string") return trace !== "off";
+  if (typeof trace === "object" && trace !== null && "mode" in trace) {
+    return trace.mode !== "off";
+  }
+  return false;
+}
 var test = base.extend({
-  chaos: async ({ page }, use) => {
+  chaos: async ({ page }, use, testInfo) => {
+    const autoTrace = shouldAutoTrace(testInfo);
     const fixture = {
-      inject: (config) => injectChaos(page, config),
+      inject: (config, opts = {}) => {
+        let tracing = opts.tracing;
+        if (tracing === void 0 || tracing === "auto") {
+          tracing = autoTrace;
+        }
+        return injectChaos(page, config, {
+          ...opts,
+          tracing,
+          testInfo: opts.testInfo ?? testInfo
+        });
+      },
       remove: () => removeChaos(page),
-      getLog: () => getChaosLog(page)
+      getLog: () => getChaosLog(page),
+      getSeed: () => getChaosSeed(page)
     };
     await use(fixture);
     await removeChaos(page);

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   getChaosLog: () => getChaosLog,
+  getChaosSeed: () => getChaosSeed,
   injectChaos: () => injectChaos,
   removeChaos: () => removeChaos
 });
@@ -28,6 +29,112 @@ module.exports = __toCommonJS(index_exports);
 var import_path = require("path");
 var import_module = require("module");
 var import_url = require("url");
+
+// src/trace.ts
+var import_test = require("@playwright/test");
+var CHAOS_BINDING = "__chaosMakerReport";
+function formatStepTitle(event) {
+  const prefix = `chaos:${event.type}`;
+  const d = event.detail ?? {};
+  const parts = [];
+  const subject = d.url ?? d.selector;
+  if (subject) parts.push(truncate(subject, 48));
+  const outcome = formatOutcome(event);
+  if (outcome) parts.push(`\u2192 ${outcome}`);
+  if (!event.applied) parts.push("(skipped)");
+  return parts.length > 0 ? `${prefix} ${parts.join(" ")}` : prefix;
+}
+function formatOutcome(event) {
+  const d = event.detail ?? {};
+  switch (event.type) {
+    case "network:failure":
+      return d.statusCode != null ? String(d.statusCode) : null;
+    case "network:latency":
+      return d.delayMs != null ? `+${d.delayMs}ms` : null;
+    case "network:abort":
+      return "abort";
+    case "network:corruption":
+      return d.strategy ?? "corrupted";
+    case "network:cors":
+      return "cors-block";
+    case "ui:assault":
+      return d.action ?? null;
+    case "websocket:drop":
+      return d.direction ? `drop ${d.direction}` : "drop";
+    case "websocket:delay":
+      return d.delayMs != null ? `delay ${d.direction ?? ""} +${d.delayMs}ms` : "delay";
+    case "websocket:corrupt":
+      return d.strategy ?? "corrupt";
+    case "websocket:close":
+      return d.closeCode != null ? `close ${d.closeCode}` : "close";
+    default:
+      return null;
+  }
+}
+function truncate(s, max) {
+  if (s.length <= max) return s;
+  return `\u2026${s.slice(-(max - 1))}`;
+}
+function shouldEmitStep(event, verbose) {
+  if (event.applied) return true;
+  return verbose;
+}
+async function createTraceReporter(page, testInfo, opts = {}) {
+  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);
+    import_test.test.step(title, async () => {
+    }).catch(() => {
+    });
+  };
+  await page.exposeBinding(CHAOS_BINDING, handler);
+  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);
+  return {
+    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 {
+      }
+    }
+  };
+}
+
+// src/index.ts
 var import_meta = {};
 var cachedUmdPath = null;
 function getCoreUmdPath() {
@@ -39,21 +146,53 @@ function getCoreUmdPath() {
   cachedUmdPath = (0, import_path.resolve)(coreDistDir, "chaos-maker.umd.js");
   return cachedUmdPath;
 }
-async function injectChaos(page, config) {
+var TRACE_HANDLE_KEY = /* @__PURE__ */ Symbol.for("chaos-maker.playwright.traceHandle");
+async function injectChaos(page, config, opts = {}) {
   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_KEY];
+    if (!existing) {
+      const handle = await createTraceReporter(page, opts.testInfo, opts.traceOptions);
+      page[TRACE_HANDLE_KEY] = handle;
+    }
+  }
   await page.addInitScript((cfg) => {
     const win = globalThis;
     win.__CHAOS_CONFIG__ = cfg;
   }, config);
   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_KEY];
+  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_KEY];
+  }
 }
 async function getChaosLog(page) {
   return page.evaluate(() => {
@@ -64,9 +203,19 @@ async function getChaosLog(page) {
     return [];
   });
 }
+async function getChaosSeed(page) {
+  return page.evaluate(() => {
+    const win = globalThis;
+    if (win.chaosUtils) {
+      return win.chaosUtils.getSeed();
+    }
+    return null;
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   getChaosLog,
+  getChaosSeed,
   injectChaos,
   removeChaos
 });

package/dist/index.d.cts

@@ -1,7 +1,45 @@
-import { Page } from '@playwright/test';
+import { TestInfo, Page } from '@playwright/test';
 import { ChaosEvent, ChaosConfig } from '@chaos-maker/core';
-export { ChaosConfig, ChaosEvent } from '@chaos-maker/core';
+export { ChaosConfig, ChaosEvent, WebSocketCloseConfig, WebSocketConfig, WebSocketCorruptConfig, WebSocketCorruptionStrategy, WebSocketDelayConfig, WebSocketDirection, WebSocketDropConfig } from '@chaos-maker/core';
 
+/**
+ * Shape of the JSON attachment written to `testInfo.attachments` on teardown.
+ */
+interface ChaosTraceAttachment {
+    seed: number | null;
+    eventCount: number;
+    events: ChaosEvent[];
+}
+interface TraceReporterOptions {
+    /** Emit `test.step` for `applied:false` diagnostic events too. Default false. */
+    verbose?: boolean;
+    /** Attachment name. Default `chaos-log.json`. */
+    attachmentName?: string;
+}
+
+/**
+ * Options for `injectChaos`. Most callers can omit this entirely; defaults
+ * preserve backward compatibility with the v0.1.x signature.
+ */
+interface InjectChaosOptions {
+    /**
+     * Emit chaos events into the Playwright trace as `test.step` entries and
+     * attach the full event log on test end.
+     *
+     * - `true` — always on. Requires `testInfo`.
+     * - `false` (default for direct `injectChaos()` calls) — off.
+     * - `'auto'` (default for the fixture) — on when Playwright tracing is
+     *   enabled in the project config; no-op otherwise.
+     */
+    tracing?: boolean | 'auto';
+    /**
+     * Active Playwright `TestInfo`, required when `tracing` is truthy.
+     * The fixture supplies this automatically.
+     */
+    testInfo?: TestInfo;
+    /** Pass through to the trace reporter. */
+    traceOptions?: TraceReporterOptions;
+}
 /**
  * Inject chaos into a Playwright page. Call before `page.goto()` to ensure
  * all network requests are intercepted from the start.
@@ -20,7 +58,7 @@ export { ChaosConfig, ChaosEvent } from '@chaos-maker/core';
  * });
  * ```
  */
-declare function injectChaos(page: Page, config: ChaosConfig): Promise<void>;
+declare function injectChaos(page: Page, config: ChaosConfig, opts?: InjectChaosOptions): Promise<void>;
 /**
  * Remove chaos from a Playwright page. Restores original fetch/XHR/DOM behavior.
  */
@@ -30,5 +68,10 @@ declare function removeChaos(page: Page): Promise<void>;
  * Returns all events emitted since chaos was injected.
  */
 declare function getChaosLog(page: Page): Promise<ChaosEvent[]>;
+/**
+ * Retrieve the PRNG seed from a Playwright page.
+ * Log this value on test failure to replay exact chaos decisions.
+ */
+declare function getChaosSeed(page: Page): Promise<number | null>;
 
-export { getChaosLog, injectChaos, removeChaos };
+export { type ChaosTraceAttachment, type InjectChaosOptions, type TraceReporterOptions, getChaosLog, getChaosSeed, injectChaos, removeChaos };

package/dist/index.d.ts

@@ -1,7 +1,45 @@
-import { Page } from '@playwright/test';
+import { TestInfo, Page } from '@playwright/test';
 import { ChaosEvent, ChaosConfig } from '@chaos-maker/core';
-export { ChaosConfig, ChaosEvent } from '@chaos-maker/core';
+export { ChaosConfig, ChaosEvent, WebSocketCloseConfig, WebSocketConfig, WebSocketCorruptConfig, WebSocketCorruptionStrategy, WebSocketDelayConfig, WebSocketDirection, WebSocketDropConfig } from '@chaos-maker/core';
 
+/**
+ * Shape of the JSON attachment written to `testInfo.attachments` on teardown.
+ */
+interface ChaosTraceAttachment {
+    seed: number | null;
+    eventCount: number;
+    events: ChaosEvent[];
+}
+interface TraceReporterOptions {
+    /** Emit `test.step` for `applied:false` diagnostic events too. Default false. */
+    verbose?: boolean;
+    /** Attachment name. Default `chaos-log.json`. */
+    attachmentName?: string;
+}
+
+/**
+ * Options for `injectChaos`. Most callers can omit this entirely; defaults
+ * preserve backward compatibility with the v0.1.x signature.
+ */
+interface InjectChaosOptions {
+    /**
+     * Emit chaos events into the Playwright trace as `test.step` entries and
+     * attach the full event log on test end.
+     *
+     * - `true` — always on. Requires `testInfo`.
+     * - `false` (default for direct `injectChaos()` calls) — off.
+     * - `'auto'` (default for the fixture) — on when Playwright tracing is
+     *   enabled in the project config; no-op otherwise.
+     */
+    tracing?: boolean | 'auto';
+    /**
+     * Active Playwright `TestInfo`, required when `tracing` is truthy.
+     * The fixture supplies this automatically.
+     */
+    testInfo?: TestInfo;
+    /** Pass through to the trace reporter. */
+    traceOptions?: TraceReporterOptions;
+}
 /**
  * Inject chaos into a Playwright page. Call before `page.goto()` to ensure
  * all network requests are intercepted from the start.
@@ -20,7 +58,7 @@ export { ChaosConfig, ChaosEvent } from '@chaos-maker/core';
  * });
  * ```
  */
-declare function injectChaos(page: Page, config: ChaosConfig): Promise<void>;
+declare function injectChaos(page: Page, config: ChaosConfig, opts?: InjectChaosOptions): Promise<void>;
 /**
  * Remove chaos from a Playwright page. Restores original fetch/XHR/DOM behavior.
  */
@@ -30,5 +68,10 @@ declare function removeChaos(page: Page): Promise<void>;
  * Returns all events emitted since chaos was injected.
  */
 declare function getChaosLog(page: Page): Promise<ChaosEvent[]>;
+/**
+ * Retrieve the PRNG seed from a Playwright page.
+ * Log this value on test failure to replay exact chaos decisions.
+ */
+declare function getChaosSeed(page: Page): Promise<number | null>;
 
-export { getChaosLog, injectChaos, removeChaos };
+export { type ChaosTraceAttachment, type InjectChaosOptions, type TraceReporterOptions, getChaosLog, getChaosSeed, injectChaos, removeChaos };

package/dist/index.js

@@ -1,10 +1,12 @@
 import {
   getChaosLog,
+  getChaosSeed,
   injectChaos,
   removeChaos
-} from "./chunk-BZSMGQHL.js";
+} from "./chunk-XVP3BFFM.js";
 export {
   getChaosLog,
+  getChaosSeed,
   injectChaos,
   removeChaos
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaos-maker/playwright",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Playwright adapter for @chaos-maker/core — one-line chaos injection in E2E tests",
   "keywords": [
@@ -49,7 +49,7 @@
     "dist"
   ],
   "dependencies": {
-    "@chaos-maker/core": "0.1.0"
+    "@chaos-maker/core": "0.2.0"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.40.0"
@@ -61,12 +61,13 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.45.0",
-    "tsup": "^8.0.0",
+    "tsup": "^8.5.1",
     "typescript": "^5.4.5",
-    "vitest": "^1.6.0"
+    "vitest": "^3.2.4"
   },
   "scripts": {
     "build": "tsup",
-    "test": "vitest"
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/dist/chunk-BZSMGQHL.js

@@ -1,45 +0,0 @@
-// src/index.ts
-import { resolve, dirname } from "path";
-import { createRequire } from "module";
-import { fileURLToPath } from "url";
-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;
-}
-async function injectChaos(page, config) {
-  const umdPath = getCoreUmdPath();
-  await page.addInitScript((cfg) => {
-    const win = globalThis;
-    win.__CHAOS_CONFIG__ = cfg;
-  }, config);
-  await page.addInitScript({ path: umdPath });
-}
-async function removeChaos(page) {
-  await page.evaluate(() => {
-    const win = globalThis;
-    if (win.chaosUtils) {
-      win.chaosUtils.stop();
-    }
-  });
-}
-async function getChaosLog(page) {
-  return page.evaluate(() => {
-    const win = globalThis;
-    if (win.chaosUtils) {
-      return win.chaosUtils.getLog();
-    }
-    return [];
-  });
-}
-
-export {
-  injectChaos,
-  removeChaos,
-  getChaosLog
-};