ma-agents 3.6.2 → 3.8.0

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/resources/knowledge/webhook-providers.md

@@ -0,0 +1,155 @@
+# Webhook Provider Patterns
+
+## Principle
+
+Three built-in providers ship with playwright-utils. Each wraps a different mock server API. For any backend not covered, implement the `WebhookProvider` interface. The registry only cares about the contract — not the backend technology.
+
+## WireMockWebhookProvider
+
+Uses `GET /__admin/requests` to fetch the webhook log and `DELETE /__admin/requests` to reset. Supports `deleteById` for `matched-only` cleanup.
+
+**Works with any backend implementing the `/__admin/requests` format** — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+```
+
+Supports both cleanup strategies. Use `matched-only` when running `fullyParallel: true`.
+
+## MockServerWebhookProvider
+
+Uses `PUT /mockserver/retrieve` to fetch logs with client-side `since` filtering.
+
+**Limitation**: `deleteById` is a no-op — MockServer does not support deleting individual log entries by ID. The `startedAt` timestamp filter handles per-test isolation. Use `full-reset` for explicit journal cleanup.
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## MockoonWebhookProvider
+
+Uses `GET /mockoon-admin/logs` to fetch logs. The admin API is enabled by default in `@mockoon/cli`. Default log limit is 100 entries — increase with `--max-transaction-logs` if your suite generates more.
+
+**Limitation**: `deleteById` is a no-op for the same reason as MockServer. Use `full-reset`.
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+Start Mockoon with an increased log limit if needed:
+
+```bash
+mockoon-cli start --data ./mockoon-config.json --max-transaction-logs 500
+```
+
+## Custom Provider
+
+Implement `WebhookProvider` for any backend that exposes a queryable request log:
+
+```typescript
+// support/providers/custom-webhook-provider.ts
+import type { WebhookProvider, ReceivedWebhook, WebhookQueryFilter } from '@seontechnologies/playwright-utils/webhook';
+import type { APIRequestContext } from '@playwright/test';
+
+export class CustomWebhookProvider implements WebhookProvider {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly request: APIRequestContext,
+  ) {}
+
+  async getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]> {
+    const params = new URLSearchParams();
+    if (filter?.since) params.set('since', filter.since.toISOString());
+    if (filter?.method) params.set('method', filter.method);
+
+    const response = await this.request.get(`${this.baseUrl}/webhooks/received?${params}`);
+    const { webhooks } = await response.json();
+    return webhooks.map((w: Record<string, unknown>) => ({
+      id: String(w.id),
+      url: String(w.url),
+      method: String(w.method),
+      headers: (w.headers as Record<string, string>) ?? {},
+      body: w.body,
+      receivedAt: new Date(String(w.receivedAt)),
+    }));
+  }
+
+  async resetJournal(): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received`);
+  }
+
+  async deleteById(id: string): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received/${id}`);
+  }
+
+  async getCount(): Promise<number> {
+    const response = await this.request.get(`${this.baseUrl}/webhooks/count`);
+    const { count } = await response.json();
+    return count as number;
+  }
+}
+```
+
+## WebhookProvider Interface
+
+```typescript
+interface WebhookProvider {
+  getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]>;
+  resetJournal(): Promise<void>;
+  deleteById(id: string): Promise<void>;
+  getCount(criteria?: Record<string, unknown>): Promise<number>;
+  removeByCriteria?(criteria: Record<string, unknown>): Promise<void>;
+  setup?(): Promise<void>; // optional — called before test
+  teardown?(): Promise<void>; // optional — called after test
+}
+```
+
+## Provider Comparison
+
+| Provider                  | deleteById | resetJournal | Parallel-safe (shared journal)      | Recommended strategy                                  | API endpoint           |
+| ------------------------- | ---------- | ------------ | ----------------------------------- | ----------------------------------------------------- | ---------------------- |
+| WireMockWebhookProvider   | ✅ Yes     | ✅ Yes       | ✅ Yes (`matched-only`)             | `matched-only`                                        | `/__admin/requests`    |
+| MockServerWebhookProvider | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockserver/retrieve` |
+| MockoonWebhookProvider    | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockoon-admin/logs`  |
+| Custom                    | Depends    | Depends      | Depends on implementation           | Depends                                               | Your API               |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Full fixture wiring for each provider
+- `webhook-testing-fundamentals.md` — Cleanup strategy rationale

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/resources/knowledge/webhook-risk-guidance.md

@@ -0,0 +1,114 @@
+# Webhook Testing Risk Guidance
+
+## Principle
+
+Webhook integration points are high-risk boundaries — they represent asynchronous side effects that cross service boundaries. A missing or malformed webhook means a downstream system never received its trigger. Default risk level: **P2 × I3** (medium probability, high impact = Risk Score 6) → must be covered by integration tests.
+
+## When Webhook Tests Are Required
+
+Webhook tests are **required** (not optional) when:
+
+| Condition                                                          | Rationale                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Application publishes events to external subscribers               | External consumers depend on correct payload shape and delivery timing |
+| Event-driven architecture (Kafka/SQS/event bus → webhook delivery) | The delivery pipeline is a risk boundary; delivery failures are silent |
+| Payment, order, or notification side effects                       | Business-critical; missed webhooks = missed transactions               |
+| Integration with third-party services via webhooks                 | Breaking payload changes won't surface in unit or component tests      |
+| Any async side effect that a consumer polls-on or reacts-to        | Polling tests (`recurse`) can mask webhook delivery failures entirely  |
+
+## Risk Scoring
+
+```
+Risk = Probability × Impact
+
+Probability factors (P1–P3):
+  P1 (low):    Webhook system is mature, well-tested, no history of failures
+  P2 (medium): Kafka pipeline, multiple consumers, new integrations
+  P3 (high):   New delivery mechanism, external third-party webhooks, no retry logic
+
+Impact factors (I1–I3):
+  I1 (low):    Non-critical notifications (e.g. audit logs)
+  I2 (medium): Feature-level side effects (e.g. search index updates)
+  I3 (high):   Business-critical events (payments, orders, compliance)
+```
+
+Default webhook integrations: **P2 × I3 = 6** → High → must be tested.
+
+## What a Complete Webhook Test Looks Like
+
+A complete webhook test covers:
+
+1. **Happy path**: Action fires → webhook arrives with correct payload
+2. **Sequential events (drain pattern)**: Preceding event drained before asserting on next
+3. **Parallel isolation**: Template scoped by entity ID — workers don't cross-contaminate
+4. **Timeout/error shape**: `WebhookTimeoutError` tested for negative path coverage
+5. **Cleanup verification**: Fixture auto-cleans; no leaked webhooks after test
+
+**Minimal complete example** (from playwright-utils E2E suite):
+
+```typescript
+// Template factories scoped by ID — parallel safety
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+test('movie deletion triggers a webhook with correct payload', async ({ authToken, addMovie, deleteMovie, webhookRegistry }) => {
+  const movie = generateMovieWithoutId();
+  const { body: createResponse } = await addMovie(authToken, movie);
+  const movieId = createResponse.data.id;
+
+  // Drain: consume the create webhook before testing the delete path
+  await webhookRegistry.waitFor(movieCreated(movieId));
+
+  await deleteMovie(authToken, movieId);
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+## Common Failure Patterns
+
+| Failure pattern                        | Root cause                                             | How the module addresses it                                                  |
+| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Test passes but webhook never verified | Test asserted on status endpoint, not delivery         | `waitFor` forces assertion on actual webhook arrival                         |
+| Flaky under `fullyParallel: true`      | `full-reset` cleanup deletes another worker's webhooks | `matched-only` strategy — only matched webhooks are deleted                  |
+| Timeout gives no useful information    | No payload inspection on failure                       | `WebhookTimeoutError.receivedWebhooks` snapshot                              |
+| Template matches wrong test's webhook  | Template not scoped by entity ID                       | Template factories accept ID parameter; `matchPredicate` for complex scoping |
+| Test hangs at 30s default timeout      | Webhook not arriving; pipeline is slow                 | Use `withTimeout()` and `withInterval(500)` per template                     |
+| Journal grows unbounded                | No cleanup strategy configured                         | Configure `cleanupStrategy` in `webhookConfig`; fixture auto-cleans          |
+
+## Risk Mitigation Checklist (for TA assessment)
+
+When a system uses webhooks, verify the test suite covers:
+
+- [ ] Happy path for each event type that has an external subscriber
+- [ ] Template factories scoped by entity ID (parallel-safe)
+- [ ] Drain pattern applied to all sequential event assertions
+- [ ] Cleanup strategy matches provider capability: `matched-only` for providers that support `deleteById` (e.g. WireMock); `full-reset` with serial execution or an isolated provider instance per worker for MockServer/Mockoon
+- [ ] Timeout values appropriate for the delivery pipeline latency (Kafka pipelines need 15s+)
+- [ ] `WebhookTimeoutError` imported and tested in negative path coverage
+- [ ] Mock server (WireMock/MockServer/Mockoon) in Docker Compose / test infra
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-module-setup.md` — Fixture wiring for each provider
+- `webhook-template-matchers.md` — Template and matcher patterns
+- `risk-governance.md` — Risk scoring framework
+- `probability-impact.md` — P×I scale definitions

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/resources/knowledge/webhook-template-matchers.md

@@ -0,0 +1,160 @@
+# Webhook Template Matchers
+
+## Principle
+
+Build typed templates with `webhookTemplate()` and compose matchers using `matchField`, `matchPartial`, and `matchPredicate`. All matchers on a template use AND semantics — every matcher must pass for a webhook to be considered a match. Templates are immutable value objects produced by a fluent builder.
+
+## Template Factory Pattern
+
+Define template factories as pure functions that accept a test-scoped ID. This is the key pattern for parallel isolation — each factory call produces a template bound to a specific entity:
+
+```typescript
+import { webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+// Template factories for movie webhooks
+// 15s timeout: the Kafka → HTTP webhook delivery pipeline can back up under
+// high CI concurrency (burn-in with many parallel workers). 10s was occasionally
+// not enough; 15s gives the pipeline headroom without slowing normal runs.
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+```
+
+The ID parameter scopes each template to a specific entity, preventing parallel workers from matching each other's webhooks.
+
+## Matcher Reference
+
+### matchField — dot-path exact match
+
+Traverses dot-notation paths into the payload. Never throws if the path is missing — a missing path evaluates as non-matching.
+
+```typescript
+webhookTemplate('order.created')
+  .matchField('event', 'order.created') // top-level field
+  .matchField('data.id', orderId) // nested path
+  .matchField('data.status', 'pending') // nested string value
+  .build();
+```
+
+Matcher detail output: `field(data.id=42)`
+
+### matchPartial — deep subset check
+
+Checks that the expected object is a subset of the received payload. Extra fields in the payload are ignored. Arrays use strict length matching.
+
+```typescript
+const partialTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.created.partial')
+  .matchPartial({ event: 'movie.created', data: { id: movieId } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `partial({"event":"movie.created","data":{"id":42}})`
+
+### matchPredicate — arbitrary function
+
+Accepts any `(payload: T) => boolean` function. Always requires a human-readable description string — this appears in `WebhookTimeoutError.matcherDetails` for debugging.
+
+**ID-scoped parallel isolation** (prevents cross-worker contamination in `waitForCount`):
+
+```typescript
+const batchTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.created.batch')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${id1} or ${id2}`, (p) => p.data.id === id1 || p.data.id === id2)
+  .withTimeout(15_000)
+  .withInterval(500)
+  .build();
+```
+
+**Business data filtering**:
+
+```typescript
+const highRatingTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; rating: number };
+}>('movie.created.high-rating')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${movieId} and data.rating >= 9`, (p) => p.data.id === movieId && p.data.rating >= 9)
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `predicate(data.id is 42 and data.rating >= 9)`
+
+## Combining Matchers
+
+All matchers use AND semantics — all must pass for the webhook to match:
+
+```typescript
+// Combined field + partial: both matchers must pass
+const updateTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.updated')
+  .matchField('event', 'movie.updated')
+  .matchPartial({ data: { id: movieId, name: nameUpdate.name } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+## Per-Template Timeout and Interval
+
+Override the registry defaults on a per-template basis:
+
+```typescript
+webhookTemplate('slow.pipeline.event')
+  .matchField('event', 'slow.pipeline.event')
+  .withTimeout(60_000) // 60s for slow delivery pipelines
+  .withInterval(2_000) // poll every 2s
+  .build();
+```
+
+## clone() for Base Template Variations
+
+> **Note**: `clone()` is available on the builder but is not used in the playwright-utils E2E suite. Use it when multiple tests share the same base template with slight field variations.
+
+```typescript
+const base = webhookTemplate<OrderPayload>('order').matchField('event', 'order.completed');
+
+const forOrderA = base.clone().matchField('data.orderId', 'A').build();
+const forOrderB = base.clone().matchField('data.orderId', 'B').build();
+```
+
+## Builder API Summary
+
+| Method                      | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `webhookTemplate<T>(name)`  | Create a new builder with the given template name      |
+| `.matchField(path, value)`  | Add dot-path exact-match matcher                       |
+| `.matchPartial(expected)`   | Add deep-subset matcher                                |
+| `.matchPredicate(desc, fn)` | Add arbitrary predicate matcher (description required) |
+| `.withTimeout(ms)`          | Override registry default timeout                      |
+| `.withInterval(ms)`         | Override registry default poll interval                |
+| `.clone()`                  | Copy current builder state for variation               |
+| `.build()`                  | Produce the immutable `WebhookTemplate<T>` object      |
+
+## Related Fragments
+
+- `webhook-waiting-querying.md` — waitFor, waitForCount, drain pattern
+- `webhook-timeout-error.md` — Reading matcherDetails in error output

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/resources/knowledge/webhook-testing-fundamentals.md

@@ -0,0 +1,42 @@
+# Webhook Testing Fundamentals
+
+## Principle
+
+Webhook delivery is eventually consistent — your application fires HTTP callbacks asynchronously after events occur. Tests must poll until the expected webhook arrives or time out. The `@seontechnologies/playwright-utils` webhook module provides deterministic polling, typed matchers, rich timeout diagnostics, and cleanup strategies safe under `fullyParallel: true`.
+
+## Rationale
+
+Webhook tests fail for four structural reasons:
+
+- **Eventually consistent**: Webhook delivery happens asynchronously — you cannot assert immediately after triggering an event
+- **Parallel journal pollution**: When multiple workers share the same mock server, a fast worker's teardown can delete records a slow worker is still polling
+- **Opaque timeouts**: A bare timeout tells you only that the webhook didn't arrive — it shows you nothing about what did arrive
+- **Cleanup drift**: Resetting the full journal in `afterEach` creates a race condition under `fullyParallel: true`
+
+The playwright-utils approach:
+
+- **Polling via `recurse`**: Uses Playwright's `expect.poll` under the hood — retries with configurable timeout and interval until a match is found
+- **Typed matchers**: `matchField`, `matchPartial`, `matchPredicate` — all must pass (AND semantics); matchers never throw on missing paths
+- **Rich timeout errors**: `WebhookTimeoutError` carries `totalReceived`, `receivedWebhooks`, and `matcherDetails` so you can see what arrived vs. what was expected
+- **Isolation via `startedAt`**: Each `WebhookRegistry` instance records its creation timestamp; polling only fetches webhooks received after that point, preventing leakage from prior tests
+- **Two cleanup strategies**: `full-reset` (resets entire journal) and `matched-only` (deletes only matched webhooks — parallel-safe when the provider supports delete-by-ID, e.g. WireMock)
+
+## When to Use Webhook Tests
+
+| Scenario                                                          | Use webhook tests         |
+| ----------------------------------------------------------------- | ------------------------- |
+| Application publishes events to external subscribers              | ✅ Required               |
+| Event-driven architecture with Kafka/event bus → webhook delivery | ✅ Required               |
+| Payment, order, or notification side effects via webhooks         | ✅ Required               |
+| Testing that a webhook was NOT delivered                          | ✅ Verify via timeout     |
+| Polling a status endpoint for eventual consistency                | ❌ Use `recurse` directly |
+| Frontend receiving push notifications (WebSocket)                 | ❌ Different mechanism    |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Fixture wiring and cleanup strategies
+- `webhook-template-matchers.md` — matchField, matchPartial, matchPredicate
+- `webhook-waiting-querying.md` — waitFor, waitForCount, getReceived, drain pattern
+- `webhook-timeout-error.md` — WebhookTimeoutError debugging
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider
+- `webhook-risk-guidance.md` — Risk-based guidance for TA and TD capabilities

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/resources/knowledge/webhook-timeout-error.md

@@ -0,0 +1,130 @@
+# WebhookTimeoutError and Debugging
+
+## Principle
+
+`WebhookTimeoutError` is thrown when `waitFor` or `waitForCount` does not find a matching webhook within the configured timeout. It carries a snapshot of received webhooks from the last polling cycle — truncated to the last 10 entries — so you can inspect what arrived vs. what was expected. The full count of all received webhooks is available in `totalReceived`.
+
+## Error Properties
+
+```typescript
+class WebhookTimeoutError extends Error {
+  readonly name = 'WebhookTimeoutError';
+  readonly templateName: string; // from webhookTemplate('...')
+  readonly timeoutMs: number; // the timeout that was exceeded
+  readonly totalReceived: number; // total webhooks seen in polling window
+  readonly receivedWebhooks: ReceivedWebhook[]; // last ≤10 received webhooks
+  readonly matcherDetails: string[]; // human-readable matcher summary
+
+  toJSON(): Record<string, unknown>; // serialize all fields for CI logs
+}
+```
+
+`receivedWebhooks` is capped at the last 10 entries. If more than 10 webhooks arrived, `totalReceived` shows the full count but `receivedWebhooks` contains only the most recent 10.
+
+## Reading the Error
+
+The error message format:
+
+```
+Webhook "movie.deleted" not received within 15000ms.
+3 webhook(s) were received but none matched.
+Matchers: field(event="movie.deleted"), field(data.id=42).
+```
+
+Use `matcherDetails` to confirm the matchers were configured correctly. Use `receivedWebhooks` to inspect actual payloads — compare field paths and values against what the matchers expect.
+
+## Validating the Error Shape in Tests
+
+```typescript
+import { WebhookTimeoutError, webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+const neverArrivingTemplate = webhookTemplate('never.arrives')
+  .matchField('event', 'event.that.never.happens')
+  .withTimeout(500)
+  .withInterval(100)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(neverArrivingTemplate)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.templateName).toBe('never.arrives');
+expect(error.timeoutMs).toBe(500);
+expect(error.toJSON()).toMatchObject({
+  name: 'WebhookTimeoutError',
+  templateName: 'never.arrives',
+  timeoutMs: 500,
+  totalReceived: expect.any(Number),
+  matcherDetails: ['field(event="event.that.never.happens")'],
+});
+```
+
+## Inspecting receivedWebhooks
+
+When a webhook arrives but doesn't match, `receivedWebhooks` shows you what actually came in:
+
+```typescript
+// Wait for create webhook first — puts it in the journal
+await webhookRegistry.waitFor(movieCreated(movieId));
+
+// Wait for delete webhook that will never arrive — no delete was called
+const undeliveredDelete = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.deleted.not.delivered')
+  .matchField('event', 'movie.deleted')
+  .matchField('data.id', movieId)
+  .withTimeout(2_000)
+  .withInterval(200)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(undeliveredDelete)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.totalReceived).toBeGreaterThanOrEqual(1);
+
+// The movie.created webhook that did arrive is visible in the error
+const createdWebhook = error.receivedWebhooks.find((w) => (w.body as { data: { id: number } }).data.id === movieId);
+expect(createdWebhook).toBeDefined();
+expect((createdWebhook!.body as { event: string }).event).toBe('movie.created');
+```
+
+## Common Failure Patterns
+
+| What you see                           | Likely cause                                         | Fix                                                               |
+| -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| `totalReceived: 0`                     | Webhook not delivered; wrong URL or event not firing | Check application event publishing and webhook routing            |
+| `totalReceived > 0`, none match        | Webhooks arriving but matchers not matching          | Inspect `receivedWebhooks[0].body` — check field paths and values |
+| `matcherDetails` shows wrong path      | Template factory misconfigured                       | Print `error.toJSON()` and compare paths against actual payload   |
+| `totalReceived: 0` with `matched-only` | Another worker claimed and deleted the webhook first | Ensure template is scoped by entity ID                            |
+| Parse error in body                    | Webhook body is not valid JSON                       | Check `receivedWebhooks[n].parseError` and `rawBody`              |
+
+## matcherDetails Format per Matcher Type
+
+| Matcher                         | matcherDetails string |
+| ------------------------------- | --------------------- |
+| `matchField('event', 'x')`      | `field(event="x")`    |
+| `matchPartial({ a: 1 })`        | `partial({"a":1})`    |
+| `matchPredicate('my desc', fn)` | `predicate(my desc)`  |
+
+## Import
+
+```typescript
+import { WebhookTimeoutError } from '@seontechnologies/playwright-utils/webhook';
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — matcherDetails string format per matcher type
+- `webhook-waiting-querying.md` — waitFor and waitForCount throw this error on timeout