bmad-template/.claude/skills/bmad-testarch-trace/resources/knowledge/webhook-module-setup.md

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.

// 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

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

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

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