ma-agents 3.6.2 → 3.8.0

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/pactjs-utils-zod-to-pact.md

@@ -0,0 +1,262 @@
+# Pact.js Utils Zod to Pact
+
+## Principle
+
+Use `zodToPactMatchers` from `@seontechnologies/pactjs-utils` to derive Pact V3 matchers directly from a Zod schema so you never maintain two representations of the same response shape. The schema is the source of truth for types; plain example values (or `.openapi({ example })` metadata) supply the concrete example data.
+
+## Rationale
+
+### Problems with hand-written matcher helpers
+
+- **Duplication**: Teams that already define response shapes in Zod (or generate OpenAPI from Zod) then redefine the same shape again as hand-written `{ id: integer(...), name: string(...) }` matcher objects.
+- **Silent drift**: Every schema change must be applied in both places; miss one and the contract drifts silently from the real response shape.
+- **Boilerplate helpers per test file**: Consumer tests end up with local `propMatcherFoo(x) => ({ ... })` helpers that mirror the type exactly.
+- **Over-specification**: Importing the provider's full 20-field schema produces a contract that forces the provider to return every field — breaking consumer-driven testing's core benefit (consumer only asserts what it reads).
+
+### Solutions
+
+- **`zodToPactMatchers(schema, example)`** — walks a Zod schema and emits the right `MatchersV3.*` call per field (`string()`, `integer()`, `decimal()`, `boolean()`, `nullValue()`, `eachLike(...)` for arrays, recursive objects, first option for unions, first value for enums, literal-typed matchers for literals).
+- **Three-step example resolution**: (1) the `example` arg wins, (2) `.openapi({ example })` metadata (if `@asteasolutions/zod-to-openapi` is installed), (3) a type-appropriate default (`'string'`, `1.0`, `true`, no-arg `integer()`).
+- **Consumer-curated schemas**: You choose which schema to pass, so you can include only the fields the consumer actually reads — keeping contracts lean and consumer-driven.
+
+## Pattern Examples
+
+### Example 1: Consumer-curated schema (mandatory pattern)
+
+```typescript
+// pact/http/helpers/consumer-schemas.ts
+import { z } from 'zod';
+
+// Only the fields this consumer actually reads — NOT the shared full-response schema
+export const ConsumerMovieSchema = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  year: z.number().int(),
+  rating: z.number(),
+  director: z.string(),
+});
+```
+
+### Example 2: Replacing hand-written matcher helpers
+
+```typescript
+// ❌ Before — hand-written helper duplicates the shape defined in Movie type
+const propMatcherNoId = (movie: Omit<Movie, 'id'>) => ({
+  name: string(movie.name),
+  year: integer(movie.year),
+  rating: decimal(movie.rating),
+  director: string(movie.director),
+});
+
+await pact
+  .addInteraction()
+  .given('No movies exist')
+  .uponReceiving('a request to add a new movie')
+  .withRequest('POST', '/movies', setJsonContent({ body: movieWithoutId }))
+  .willRespondWith(
+    200,
+    setJsonContent({
+      body: {
+        status: 200,
+        data: { id: integer(), ...propMatcherNoId(movieWithoutId) },
+      },
+    }),
+  );
+```
+
+```typescript
+// ✅ After — schema defines types, plain object provides examples
+import { zodToPactMatchers, setJsonContent } from '@seontechnologies/pactjs-utils';
+import { ConsumerMovieSchema } from '../helpers/consumer-schemas';
+
+await pact
+  .addInteraction()
+  .given('No movies exist')
+  .uponReceiving('a request to add a new movie')
+  .withRequest('POST', '/movies', setJsonContent({ body: movieWithoutId }))
+  .willRespondWith(
+    200,
+    setJsonContent({
+      body: {
+        status: 200,
+        data: zodToPactMatchers(ConsumerMovieSchema, { id: 1, ...movieWithoutId }),
+      },
+    }),
+  );
+```
+
+### Example 3: Array responses with `eachLike`
+
+```typescript
+import { PactV4, MatchersV3 } from '@pact-foundation/pact';
+import { zodToPactMatchers, setJsonContent } from '@seontechnologies/pactjs-utils';
+import { ConsumerMovieSchema } from '../helpers/consumer-schemas';
+
+const { eachLike } = MatchersV3;
+const pact = new PactV4({ consumer: 'Movies Web', provider: 'Movies API' });
+const movie = { id: 1, name: 'My movie', year: 1999, rating: 8.5, director: 'John Doe' };
+
+await pact
+  .addInteraction()
+  .given('Movies exist')
+  .uponReceiving('a request for all movies')
+  .withRequest('GET', '/movies')
+  .willRespondWith(
+    200,
+    setJsonContent({
+      body: {
+        status: 200,
+        data: eachLike(zodToPactMatchers(ConsumerMovieSchema, movie) as Parameters<typeof eachLike>[0]),
+      },
+    }),
+  );
+// data expands to: eachLike({ id: integer(1), name: string('My movie'), year: integer(1999), rating: decimal(8.5), director: string('John Doe') })
+```
+
+### Example 4: Message Pact tests (Kafka / async)
+
+```typescript
+import { PactV4, MatchersV3 } from '@pact-foundation/pact';
+import { zodToPactMatchers } from '@seontechnologies/pactjs-utils';
+import { ConsumerMovieSchema } from '../../http/helpers/consumer-schemas';
+
+const { string } = MatchersV3;
+
+// Schema-derived matchers — no manual matcher construction, no outer like() wrapper
+const movieValue = zodToPactMatchers(ConsumerMovieSchema, {
+  id: 1,
+  name: 'Inception',
+  year: 2010,
+  rating: 8.8,
+  director: 'Christopher Nolan',
+});
+
+await messagePact
+  .addAsynchronousInteraction()
+  .given('An existing movie exists')
+  .expectsToReceive('a movie-created event', (builder) => {
+    builder.withJSONContent({
+      topic: string('movie-created'),
+      messages: [{ key: string('1'), value: movieValue }],
+    });
+  });
+```
+
+Note: `zodToPactMatchers` on an object schema already wraps each field in the right matcher, so the extra `like()` wrapper from hand-written versions is not needed — each field carries its own type constraint.
+
+### Example 5: OpenAPI example metadata (optional peer)
+
+```typescript
+import { z } from 'zod';
+import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
+
+extendZodWithOpenApi(z);
+
+const MovieSchema = z.object({
+  name: z.string().openapi({ example: 'Inception' }),
+  year: z.number().int().openapi({ example: 2010 }),
+});
+
+// No second argument needed — examples come from the schema itself
+zodToPactMatchers(MovieSchema);
+// → { name: string('Inception'), year: integer(2010) }
+```
+
+## Zod to Pact V3 Mapping
+
+| Zod type                                      | Pact V3 matcher                           |
+| --------------------------------------------- | ----------------------------------------- |
+| `z.string()`                                  | `string(example ?? 'string')`             |
+| `z.number().int()`                            | `integer(example)` (no-arg if no example) |
+| `z.number()`                                  | `decimal(example ?? 1.0)`                 |
+| `z.boolean()`                                 | `boolean(example ?? true)`                |
+| `z.null()`                                    | `nullValue()`                             |
+| `z.object({...})`                             | recursive object of field matchers        |
+| `z.array(...)`                                | `eachLike(itemMatchers)`                  |
+| `z.union([...])`                              | first option's matcher                    |
+| `z.literal('x')` / number / bool              | typed matcher with literal value          |
+| `z.enum([...])`                               | `string(firstValue)`                      |
+| `z.optional()` / `.nullable()` / `.default()` | unwraps to the inner schema               |
+| anything else                                 | `like(example ?? null)` fallback          |
+
+## Key Points
+
+- **Consumer-curated schema is mandatory**: Define schemas that describe only what the consumer actually reads. Do **not** pass the shared full-response schema, and do **not** `import` the provider-side schema — that turns contract tests into schema tests and blocks the provider from deprecating unused fields.
+- **Example precedence**: `example` argument > `.openapi({ example })` metadata > type default. The example only sets the placeholder value; Pact matchers check type/shape, not exact values.
+- **Optional peer**: `@asteasolutions/zod-to-openapi` is an optional peer dependency. If it's not installed, openapi-example extraction silently becomes a no-op and only the `example` argument / defaults are used.
+- **Optional peer (zod)**: `zod` itself is declared as an optional peer of `@seontechnologies/pactjs-utils` so consumers who don't use `zodToPactMatchers` don't need it; consumers who do use it must have zod installed.
+- **Object wrapping**: When passing an object result into `eachLike(...)`, cast to `Parameters<typeof eachLike>[0]` — `zodToPactMatchers` returns `unknown` by design to stay compatible with both primitive and composite matcher shapes.
+- **Arrays without examples**: If the example array is empty, the first item's field matchers are derived from the schema (and `.openapi({ example })` metadata, if present).
+- **No extra `like()` wrapper**: For objects returned from `zodToPactMatchers`, do not wrap the whole object in `like()`; each field is already a matcher.
+- **Works for HTTP and message pacts**: The same function produces matchers for request/response bodies and for Kafka / async message payloads.
+- **TypeScript**: Import `z` as a runtime value when defining schemas (`import { z } from 'zod'`). If you need a schema type in helper signatures, import it separately (for example, `import type { ZodTypeAny } from 'zod'`).
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, utility table, decision tree
+- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `setJsonContent`, `setJsonBody`
+- `pactjs-utils-provider-verifier.md` — `buildVerifierOptions` integration
+- `contract-testing.md` — foundational patterns with raw Pact.js, Provider Scrutiny Protocol (required fields / enums / data types / nested structures)
+
+## Anti-Patterns
+
+### Wrong: Passing the provider's full response schema
+
+```typescript
+// ❌ Importing the shared server-side schema forces the provider to return every field
+import { FullMovieSchema } from '@shared/schemas/movie'; // 20 fields
+
+data: zodToPactMatchers(FullMovieSchema, movie);
+```
+
+This creates a contract that requires the provider to return all 20 fields, even the ones this consumer never reads — breaking consumer-driven testing and blocking future field deprecation.
+
+### Right: Consumer-curated schema beside the pact tests
+
+```typescript
+// ✅ pact/http/helpers/consumer-schemas.ts — only the fields this consumer reads
+export const ConsumerMovieSchema = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  year: z.number().int(),
+  rating: z.number(),
+  director: z.string(),
+});
+
+data: zodToPactMatchers(ConsumerMovieSchema, movie);
+```
+
+### Wrong: Hand-written matcher helper duplicating the schema
+
+```typescript
+// ❌ Local helper that mirrors the TS type — drifts silently on every schema change
+const propMatcherNoId = (movie: Omit<Movie, 'id'>) => ({
+  name: string(movie.name),
+  year: integer(movie.year),
+  rating: decimal(movie.rating),
+  director: string(movie.director),
+});
+```
+
+### Right: `zodToPactMatchers` with a consumer-curated schema
+
+```typescript
+// ✅ Schema is the single source of truth; plain object supplies examples
+data: zodToPactMatchers(ConsumerMovieSchema, { id: 1, ...movieWithoutId });
+```
+
+### Wrong: Wrapping the whole object result in `like()`
+
+```typescript
+// ❌ Redundant — each field is already a matcher
+value: like(zodToPactMatchers(ConsumerMovieSchema, movie));
+```
+
+### Right: Use the object directly
+
+```typescript
+// ✅ Each field carries its own type constraint
+value: zodToPactMatchers(ConsumerMovieSchema, movie);
+```
+
+_Source: @seontechnologies/pactjs-utils library, pactjs-utils docs (`docs/zod-to-pact/`), pact-js consumer sample repos, Pact docs on consumer-driven contracts_

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/webhook-module-setup.md

@@ -0,0 +1,122 @@
+# Webhook Module Setup
+
+## Principle
+
+Wire the provider once in a central fixtures file using the `webhookProviderFixture + webhookFixture + mergeTests` pattern. Tests that request `webhookRegistry` get automatic setup and teardown; tests that don't pay nothing (Playwright lazy fixture evaluation).
+
+## Fixture Wiring Pattern
+
+### WireMock Provider (recommended for most setups)
+
+The WireMock provider works with any backend that implements the `/__admin/requests` API format — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as webhookFixture } from '@seontechnologies/playwright-utils/webhook/fixtures';
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+// Lazy-initialized by Playwright — no cost for tests that don't request webhookRegistry.
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+
+const test = mergeTests(
+  base,
+  // ...your other fixtures...
+  webhookFixture,
+  webhookProviderFixture,
+);
+
+// Use matched-only cleanup project-wide: each test only deletes the webhooks it
+// matched, so a parallel worker's teardown cannot wipe the shared journal while
+// another test is still mid-flight (fullyParallel: true race condition).
+test.use({ webhookConfig: { cleanupStrategy: 'matched-only' } });
+
+export { test };
+```
+
+This is the exact pattern used in the playwright-utils E2E suite (`playwright/support/merged-fixtures.ts`).
+
+### MockServer Provider
+
+```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 for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+### Mockoon Provider
+
+```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 for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## Cleanup Strategy Decision
+
+| Strategy                 | Behaviour                                                                            | When to choose                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `'full-reset'` (default) | Calls `provider.resetJournal()` — wipes the entire mock server journal               | Safe only for serial execution or when each worker has an isolated provider instance                                 |
+| `'matched-only'`         | Calls `provider.deleteById(id)` for each webhook matched by `waitFor`/`waitForCount` | Required for `fullyParallel: true` with a shared journal **when the provider supports `deleteById`** (e.g. WireMock) |
+
+**The race condition under `fullyParallel: true`**: Worker A finishes and calls `resetJournal()`. Worker B is mid-poll waiting for its webhook. Worker A's reset just deleted Worker B's webhook — the poll times out with `WebhookTimeoutError`. Use `matched-only` to avoid this — but only when the provider supports `deleteById`.
+
+**MockServer and Mockoon limitation**: Neither supports `deleteById` — their implementations are no-ops. The `startedAt` timestamp filter isolates _reads_ inside `waitFor`/`waitForCount`, but `cleanup()` with `full-reset` still calls `resetJournal()`, which wipes the entire journal. This means the teardown race exists for these providers too under `fullyParallel: true`. For parallel suites with MockServer or Mockoon, either run serially (`workers: 1`) or provision an isolated mock server instance per worker.
+
+## Fixture Lifecycle
+
+The fixture calls these in order:
+
+1. `provider.setup?.()` — optional health check or stub registration
+2. Tests run with `webhookRegistry` available
+3. `registry.cleanup()` — deletes matched webhooks (`matched-only`) or resets journal (`full-reset`)
+4. `provider.teardown?.()` — optional resource cleanup
+
+Both cleanup and teardown failures are caught and logged as warnings — they don't mask actual test failures.
+
+## WebhookRegistryConfig Options
+
+```typescript
+type WebhookRegistryConfig = {
+  defaultTimeout?: number; // default: 30000 ms
+  defaultInterval?: number; // default: 1000 ms
+  cleanupStrategy?: 'matched-only' | 'full-reset'; // default: 'full-reset'
+};
+```
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-template-matchers.md` — Template building and matcher patterns
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider details
+- `fixtures-composition.md` — mergeTests pattern

package/lib/bmad-cache/tea/src/agents/bmad-tea/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/agents/bmad-tea/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