@noego/wood 0.4.0 → 0.4.2

package/docs/browser-testing.md

@@ -162,6 +162,90 @@ bridge, for example `settings.get` or `messages.send`. Static values are
 returned directly. Functions receive the operation input and a small context
 with the channel and recorded calls.
 
+## Tracing Browser Scenarios
+
+Use browser-harness tracing when the behavior under test is a renderer pipeline:
+route/controller selection, repeated work, resize or animation timing,
+stream/reconcile order, bridge calls, or any case where the final DOM is not
+enough to prove what happened.
+
+Enable tracing on the harness with `trace.enabled`. The harness creates a
+`TraceRecorder`, installs the renderer trace bridge, and exposes the recorder as
+`harness.traceRecorder`.
+
+```ts
+import { browser } from '@noego/wood/testing';
+
+const harness = await browser.createHarness({
+  rootDir: process.cwd(),
+  componentDir: 'ui',
+  css: ['ui/app.css'],
+  trace: {
+    enabled: true,
+    harnessId: 'settings-panel-test',
+    windowId: 'settings-window',
+    maxEvents: 500,
+  },
+});
+
+try {
+  const mounted = await harness.mountComponent('ui/SettingsPanel.svelte');
+
+  await mounted.page.evaluate(() => {
+    window.wood.__trace({
+      source: 'settings.panel',
+      type: 'settings.panel.rendered',
+      payload: { tab: 'appearance' },
+    });
+  });
+
+  await expect(harness.traceRecorder?.waitForTrace({
+    type: 'settings.panel.rendered',
+    harnessId: 'settings-panel-test',
+  })).resolves.toMatchObject({
+    process: 'renderer',
+    payload: { tab: 'appearance' },
+  });
+
+  const trace = harness.traceRecorder?.query();
+  trace?.expectOnce({ type: 'settings.panel.rendered' });
+} finally {
+  await harness.destroy();
+}
+```
+
+Renderer trace events are forwarded through the Wood bridge into the same trace
+stream used by main-process and test-process events. The resulting events keep
+their `process` field, so tests can assert whether an event came from
+`renderer`, `main`, or `test`.
+
+Useful options:
+
+- `enabled`: turns on renderer forwarding and creates `harness.traceRecorder`.
+- `harnessId`: tags events from this test so assertions can filter them.
+- `windowId`: tags events with a stable window identity.
+- `maxEvents`: caps the in-memory recorder buffer.
+- `minLevel`: filters lower-level trace events before they reach the recorder.
+
+Use `harness.traceRecorder?.query()` for counts, ordered sequences, payload
+checks, and negative assertions:
+
+```ts
+const trace = harness.traceRecorder?.query();
+
+trace?.expectSequence([
+  { type: 'transcript.projection.started' },
+  { type: 'transcript.projection.completed', 'payload.changedRows': 2 },
+]);
+trace?.expectNone({ type: 'transcript.projection.failed' });
+expect(trace?.count({ type: 'transcript.scroll-plan' })).toBeLessThanOrEqual(1);
+```
+
+For Node-only controller tests, use the controller harness' `traceRecorder` or
+resolve `TraceRecorder` from the test container, call `enable()`, run the
+subject, then assert against `traceRecorder.query()`. For browser harness tests,
+prefer the `trace` harness config because it also wires renderer forwarding.
+
 ## Assertions
 
 Every mounted surface exposes Playwright's `page` and `locator`, plus

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noego/wood",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -43,6 +43,12 @@
       "import": "./dist/testing/index.js",
       "default": "./dist/testing/index.js"
     },
+    "./trace-testing": {
+      "types": "./dist/trace-testing/index.d.ts",
+      "require": "./dist/trace-testing/index.cjs",
+      "import": "./dist/trace-testing/index.js",
+      "default": "./dist/trace-testing/index.js"
+    },
     "./client": {
       "types": "./dist/client/index.d.ts",
       "require": "./dist/client/index.cjs",
@@ -96,6 +102,7 @@
     "@noego/ioc": "^0.3.1",
     "@noego/logger": "^0.0.2",
     "@noego/stitch": "^1.0.3",
+    "@noego/trace": "^0.0.2",
     "ajv": "^8.x",
     "ajv-formats": "^3.x",
     "chokidar": "^4.x",