ma-agents 3.6.2 → 3.9.0

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/resources/knowledge/pactjs-utils-overview.md

@@ -28,6 +28,7 @@ Use production-ready utilities from `@seontechnologies/pactjs-utils` to eliminat
 - **`getProviderVersionTags`**: CI-aware version tagging (extracts branch/tag from GitHub Actions, GitLab CI, etc.)
 - **`createRequestFilter`**: Pluggable token generator pattern — prevents double-Bearer bugs by contract
 - **`noOpRequestFilter`**: Pass-through for providers that don't require auth injection
+- **`zodToPactMatchers`**: Converts a Zod schema (+ optional example values or `.openapi({ example })` metadata) into Pact V3 matchers — single source of truth for response shape, no hand-written matcher helpers
 
 ## Installation
 
@@ -42,18 +43,19 @@ npm install -D @pact-foundation/pact
 
 ## Available Utilities
 
-| Category          | Function                          | Description                                          | Use Case                                                         |
-| ----------------- | --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
-| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`          |
-| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                 |
-| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders  |
-| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                      |
-| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))` |
-| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                |
-| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                   |
-| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                   |
-| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                         |
-| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                              |
+| Category          | Function                          | Description                                          | Use Case                                                                                                  |
+| ----------------- | --------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`                                                   |
+| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                                                          |
+| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders                                           |
+| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                                                               |
+| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))`                                          |
+| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                                                         |
+| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                                                            |
+| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                                                            |
+| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                                                                  |
+| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                                                                       |
+| Schema → Matchers | `zodToPactMatchers`               | Derives Pact V3 matchers from a Zod schema           | Consumer tests: response body matchers from a consumer-curated Zod schema instead of hand-written helpers |
 
 ## Decision Tree: Which Flow?
 
@@ -153,6 +155,7 @@ await new Verifier(opts).verifyProvider();
 - `pactjs-utils-consumer-helpers.md` — detailed createProviderState, toJsonMap, setJsonContent, and setJsonBody usage
 - `pactjs-utils-provider-verifier.md` — detailed buildVerifierOptions and broker configuration
 - `pactjs-utils-request-filter.md` — detailed createRequestFilter and auth patterns
+- `pactjs-utils-zod-to-pact.md` — detailed zodToPactMatchers usage, consumer-curated schema pattern, and anti-patterns
 - `contract-testing.md` — foundational contract testing patterns (raw Pact.js approach)
 - `test-levels-framework.md` — where contract tests fit in the testing pyramid
 

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