ma-agents 3.6.2 → 3.9.0

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/resources/knowledge/pactjs-utils-consumer-helpers.md

@@ -185,6 +185,86 @@ await pact
 - Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
 - `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
 
+### Example 6: One `addInteraction()` per `it()` Block (PactV4 Determinism Rule)
+
+**Context**: PactV4's `pact.addInteraction()` feeds the Rust FFI layer that writes interactions to the pact JSON. Chaining multiple `.addInteraction()...executeTest()` blocks inside a single `it()` — or otherwise registering multiple interactions before a single `executeTest` — causes the FFI to **non-deterministically drop whole interactions** (not individual fields) in roughly 1 out of N runs. The pattern passes locally, then fails intermittently in CI or at publish time with `Cannot change pact content for already published pact` once the dropped interaction reappears on a re-run.
+
+**Rule**: Exactly one `pact.addInteraction()` per `it()` block. For N interactions, write N `it()` blocks, or use `it.each(...)`.
+
+```typescript
+// ❌ WRONG — two addInteraction() inside one it() — FFI non-deterministically drops one
+it('handles movie lookup scenarios', async () => {
+  await pact
+    .addInteraction()
+    .given('movie exists')
+    .uponReceiving('a request to get movie by id')
+    .withRequest('GET', '/movies/1')
+    .willRespondWith(200, setJsonBody({ id: integer(1), name: string('The Matrix') }))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+
+  // Sometimes this second interaction never makes it to the pact JSON:
+  await pact
+    .addInteraction()
+    .given('no movies exist')
+    .uponReceiving('a request for an empty list')
+    .withRequest('GET', '/movies')
+    .willRespondWith(200, setJsonBody([]))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+
+// ✅ RIGHT — one addInteraction() per it()
+it('gets a movie by id', async () => {
+  await pact
+    .addInteraction()
+    .given('movie exists')
+    .uponReceiving('a request to get movie by id')
+    .withRequest('GET', '/movies/1')
+    .willRespondWith(200, setJsonBody({ id: integer(1), name: string('The Matrix') }))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+
+it('returns empty list when no movies exist', async () => {
+  await pact
+    .addInteraction()
+    .given('no movies exist')
+    .uponReceiving('a request for an empty list')
+    .withRequest('GET', '/movies')
+    .willRespondWith(200, setJsonBody([]))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+
+// ✅ RIGHT — parameterized via it.each for data-driven coverage
+it.each([
+  { id: 1, name: 'The Matrix' },
+  { id: 2, name: 'Inception' },
+])('gets movie $id', async ({ id, name }) => {
+  await pact
+    .addInteraction()
+    .given('movie exists', { id, name })
+    .uponReceiving(`a request to get movie ${id}`)
+    .withRequest('GET', `/movies/${id}`)
+    .willRespondWith(200, setJsonBody({ id: integer(id), name: string(name) }))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+```
+
+**Key Points**:
+
+- **This rule stacks with two other MANDATORY vitest settings**: `fileParallelism: false` AND `pool: 'forks'` with `poolOptions.forks.singleFork: true`. All three are required and address different failure modes — `fileParallelism: false` prevents parallel workers from racing on the shared pact JSON; `pool: 'forks'` + `singleFork: true` prevents the Pact Rust FFI from leaking state across files (manifests as "request was expected but not received" flakes on Linux CI only); one-interaction-per-`it()` prevents the FFI from dropping interactions within a single test body.
+- Symptom of violating this rule: the pact file is byte-different between otherwise-identical runs; `scripts/check-pact-determinism.sh` flags drift; PactFlow rejects a republish with `Cannot change pact content`.
+- The rule applies to both HTTP consumer pacts (`PactV4`) and message consumer pacts (`MessageConsumerPact`).
+- See `pact-consumer-framework-setup.md` Example 10 for the determinism gate that automatically catches violations of this rule.
+
 ## Key Points
 
 - **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
@@ -198,11 +278,13 @@ await pact
 - **Body shorthand**: `setJsonBody` keeps body-only responses concise and readable
 - **Matchers check type, not value**: `string('My movie')` means "any string", `integer(1)` means "any integer". The example values are arbitrary — the provider can return different values and verification still passes as long as the type matches. Use matchers only in `.willRespondWith()` (responses), never in `.withRequest()` (requests) — Postel's Law applies.
 - **Reuse test values across files**: Interactions are uniquely identified by `uponReceiving` + `.given()`, not by placeholder values. Two test files can both use `testId: 100` without conflicting. On the provider side, shared values simplify state handlers — idempotent handlers (check if exists, create if not) only need to ensure one record exists. Use different values only when testing different states of the same entity type (e.g., `movieExists(100)` for happy paths vs. `movieNotFound(999)` for error paths).
+- **One `addInteraction()` per `it()` block (MANDATORY for PactV4)**: Multiple interactions inside one `it()` cause the Rust FFI to non-deterministically drop interactions. Use one `it()` per interaction or `it.each(...)` for parameterized cases. See Example 6 and the determinism gate in `pact-consumer-framework-setup.md` Example 10.
 
 ## Related Fragments
 
 - `pactjs-utils-overview.md` — installation, decision tree, design philosophy
-- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation
+- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation; same `pool: 'forks'` + `singleFork: true` rule as consumer
+- `pact-consumer-framework-setup.md` — Vitest `fileParallelism: false` + `pool: 'forks'` + `singleFork: true` config, determinism gate (Example 10), and CI wiring
 - `contract-testing.md` — foundational patterns with raw Pact.js
 
 ## Anti-Patterns
@@ -267,4 +349,32 @@ provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id:
 .willRespondWith(200, setJsonBody({ status: 200 }));
 ```
 
+### Wrong: Multiple `addInteraction()` in a single `it()`
+
+```typescript
+// ❌ PactV4 FFI non-deterministically drops one of these interactions ~1/N runs
+it('handles both success and empty list', async () => {
+  await pact.addInteraction().uponReceiving('get movie').withRequest(/* ... */).executeTest(/* ... */);
+  await pact.addInteraction().uponReceiving('empty list').withRequest(/* ... */).executeTest(/* ... */);
+});
+```
+
+### Right: One `addInteraction()` per `it()` (or use `it.each`)
+
+```typescript
+// ✅ Deterministic pact JSON — FFI receives one interaction per test
+it('gets a movie', async () => {
+  await pact
+    .addInteraction() /* ... */
+    .executeTest(/* ... */);
+});
+it('returns empty list', async () => {
+  await pact
+    .addInteraction() /* ... */
+    .executeTest(/* ... */);
+});
+```
+
+See Example 6 above for the full rationale and the determinism gate that enforces this rule.
+
 _Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/resources/knowledge/pactjs-utils-provider-verifier.md

@@ -220,6 +220,54 @@ const tags = getProviderVersionTags();
 //   tags = ['local']
 ```
 
+### Example 7: Provider Vitest Configuration (Required for Multi-File Verification)
+
+**Context**: The Pact Rust FFI that powers the JS `Verifier` holds process-wide state (native handles for messages, matchers, mocks). Vitest's default parallel file workers each spin up their own FFI instance and quickly corrupt that state — causing `MessagePact`/`Verifier` errors like `"Unable to get the MessageHandle"`, or non-deterministic verification passes/fails — as soon as you have more than one provider `.spec.ts` file.
+
+**Rule**: Provider verification suites **must** run in a single fork. Use Vitest's `forks` pool with `singleFork: true` in `vitest.config.contract.ts` (or equivalent).
+
+```typescript
+// vitest.config.contract.ts — provider verification config
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.spec.ts'],
+    testTimeout: 60000,
+    // MANDATORY for multi-file provider verification.
+    // The Pact Rust FFI backing the Verifier holds process-wide state; parallel workers corrupt it
+    // and produce flaky verification results / "Unable to get the MessageHandle" errors.
+    // This is especially important for message providers (Kafka/async) where verifier construction
+    // allocates native handles per file — singleFork keeps them in one process so state is coherent.
+    pool: 'forks',
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      },
+    },
+  },
+});
+```
+
+**Key Points**:
+
+- **Required for message providers** (`buildMessageVerifierOptions`) — the message-handle FFI state is almost guaranteed to corrupt under parallel workers.
+- **Required for HTTP providers with multiple contract test files** — even if each file works in isolation, running them together in parallel produces intermittent failures.
+- `pool: 'forks'` (rather than `threads`) + `singleFork: true` is the exact combo that keeps all verifier runs in a single child process with a single FFI instance.
+- Treat `pool: 'forks'` + `singleFork: true` as the required baseline for all provider suites, including single-file HTTP-only ones. A suite that works today with one file will flake the moment a second file is added, and removing the setting later introduces a regression window.
+- **The same `pool: 'forks'` + `singleFork: true` rule applies on the consumer side.** Consumer `vitest.config.pact.ts` sets it alongside `fileParallelism: false` — see `pact-consumer-framework-setup.md` Example 2. The rule is needed on either side wherever more than one pact test file exists per consumer+provider pair.
+- Use a dedicated `vitest.config.contract.ts` so unit tests still get full parallelism — only contract tests pay the serialization cost.
+- Related `package.json` entry:
+
+  ```json
+  {
+    "scripts": {
+      "test:pact:provider": "vitest run --config vitest.config.contract.ts"
+    }
+  }
+  ```
+
 ## Environment Variables Reference
 
 | Variable               | Required        | Description                                                                                                                           | Default     |
@@ -241,12 +289,15 @@ const tags = getProviderVersionTags();
 - **Webhook support**: `PACT_PAYLOAD_URL` takes precedence — verifies only the specific pact that triggered the webhook
 - **State handler types**: Both `async (params) => void` and `{ setup: async (params) => void, teardown: async () => void }` are supported
 - **Version publishing**: Verification results are published by default (`publishVerificationResult` defaults to `true`)
+- **Provider Vitest config is MANDATORY for multi-file suites**: Set `pool: 'forks'` + `poolOptions.forks.singleFork: true` in `vitest.config.contract.ts`. Without this the Rust FFI corrupts under parallel workers (see Example 7).
 
 ## Related Fragments
 
 - `pactjs-utils-overview.md` — installation, decision tree, design philosophy
-- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation
+- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation, **one-interaction-per-`it()` rule**
 - `pactjs-utils-request-filter.md` — auth injection for provider verification
+- `pact-consumer-framework-setup.md` — consumer-side framework setup, Vitest `fileParallelism: false`, determinism gate
+- `pact-broker-webhooks.md` — PactFlow → GitHub webhook auth/staleness for webhook-triggered provider verification (`contract_requiring_verification_published`)
 - `contract-testing.md` — foundational patterns with raw Pact.js
 
 ## Anti-Patterns
@@ -312,4 +363,35 @@ const opts = buildVerifierOptions({
 // Selectors chosen automatically based on environment
 ```
 
+### Wrong: Parallel Vitest workers for provider verification
+
+```typescript
+// ❌ vitest.config.contract.ts — uses default parallel workers
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.spec.ts'],
+    // NO pool/singleFork config — defaults to parallel file workers
+  },
+});
+// Symptoms: "Unable to get the MessageHandle", non-deterministic verification pass/fail,
+// green locally on single-file run but red in CI with multiple files
+```
+
+### Right: Single fork for provider verification
+
+```typescript
+// ✅ vitest.config.contract.ts — serializes provider verification files
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.spec.ts'],
+    pool: 'forks',
+    poolOptions: { forks: { singleFork: true } },
+  },
+});
+```
+
 _Source: @seontechnologies/pactjs-utils provider-verifier module, pact-js-example-provider CI workflows_

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/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/workflows/testarch/bmad-testarch-test-design/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-test-design/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