chore: initial monorepo scaffold + WDS Phase 1+2 artifacts
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,704 @@
|
||||
# Pact Consumer CDC — Framework Setup
|
||||
|
||||
## Principle
|
||||
|
||||
When scaffolding a Pact.js consumer contract testing framework, align every artifact — directory layout, vitest config, package.json scripts, shell scripts, CI workflow, and test files — with the canonical `@seontechnologies/pactjs-utils` conventions. Consistency across repositories eliminates onboarding friction and ensures CI pipelines are copy-paste portable.
|
||||
|
||||
## Rationale
|
||||
|
||||
The TEA framework workflow generates scaffolding for consumer-driven contract (CDC) testing. Without opinionated, battle-tested conventions, each project invents its own structure — different script names, different env var patterns, different CI step ordering — making cross-repo maintenance expensive. This fragment codifies the production-proven patterns from the pactjs-utils reference implementation so that every new project starts correctly.
|
||||
|
||||
## Pattern Examples
|
||||
|
||||
### Example 1: Directory Structure & File Naming
|
||||
|
||||
**Context**: Consumer contract test project layout using pactjs-utils conventions.
|
||||
|
||||
**Implementation**:
|
||||
|
||||
```
|
||||
tests/contract/
|
||||
├── consumer/
|
||||
│ ├── get-filter-fields.pacttest.ts # Consumer test (one per endpoint group)
|
||||
│ ├── filter-transactions.pacttest.ts
|
||||
│ └── get-transaction-stats.pacttest.ts
|
||||
└── support/
|
||||
├── pact-config.ts # PactV4 factory (consumer/provider names, output dir)
|
||||
├── provider-states.ts # Provider state factory functions
|
||||
└── consumer-helpers.ts # Local shim (until pactjs-utils is published)
|
||||
|
||||
scripts/
|
||||
├── env-setup.sh # Shared env loader (sourced by all broker scripts)
|
||||
├── publish-pact.sh # Publish pact files to broker
|
||||
├── can-i-deploy.sh # Deployment safety check
|
||||
└── record-deployment.sh # Record deployment after merge
|
||||
|
||||
.github/
|
||||
├── actions/
|
||||
│ └── detect-breaking-change/
|
||||
│ └── action.yml # PR checkbox-driven breaking change detection
|
||||
└── workflows/
|
||||
└── contract-test-consumer.yml # Consumer CDC CI workflow
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
|
||||
- Consumer tests use `.pacttest.ts` extension (not `.pact.spec.ts` or `.contract.ts`)
|
||||
- Support files live in `tests/contract/support/`, not mixed with consumer tests
|
||||
- Shell scripts live in `scripts/` at project root, not nested inside test directories
|
||||
- CI workflow named `contract-test-consumer.yml` (not `pact-consumer.yml` or other variants)
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Vitest Configuration for Pact
|
||||
|
||||
**Context**: Minimal vitest config dedicated to contract tests — do NOT copy settings from the project's main `vitest.config.ts`.
|
||||
|
||||
**Implementation**:
|
||||
|
||||
```typescript
|
||||
// vitest.config.pact.ts
|
||||
// See pact-consumer-framework-setup.md Example 2 "Key Points" for rationale on
|
||||
// fileParallelism + pool:forks + singleFork. Do not remove those three settings.
|
||||
import { defineConfig } from 'vitest/config';
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
environment: 'node',
|
||||
include: ['tests/contract/**/*.pacttest.ts'],
|
||||
testTimeout: 30000,
|
||||
fileParallelism: false,
|
||||
pool: 'forks',
|
||||
poolOptions: { forks: { singleFork: true } },
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
|
||||
- **`fileParallelism: false` is required** — primary defense against non-deterministic pact generation. Without it, parallel workers race on the shared pact JSON file and corrupt interactions. Symptom: local runs pass, CI randomly fails with `Cannot change pact content for already published pact`. The `publish-pact.sh` `jq` sort (Example 4) provides byte-stability at publish time.
|
||||
- **`pool: 'forks'` + `singleFork: true` is required for multi-file consumer suites** — same config the provider side uses (`pactjs-utils-provider-verifier.md` Example 7). Best current understanding: the `@pact-foundation/pact` napi-rs binding is not robust across Vitest worker threads sharing a process; with the default threads pool (Vitest v1) and multiple `.pacttest.ts` files on the same consumer+provider pair, we observed reproducible "request was expected but not received" flakes on Linux CI only. `singleFork: true` serializes every pact file into one forked subprocess and eliminated the flake on two repos (`pactjs-utils`, `seon-mcp-server`). Vitest v2+ defaults to `forks`, but set the pool explicitly so the contract does not drift with Vitest version bumps.
|
||||
- **One `.pacttest.ts` per consumer+provider pair is the canonical pattern** — not just an observation. Two files for the same pair in one process (which `singleFork: true` guarantees) cause an FFI handle collision: the second file's `new PactV4(...)` call re-enters the FFI handle still holding stale state from the first file → "request was expected but not received" sporadically on Linux CI. The fix is structural — merge the files, not the config. `pool: 'forks'` is still required for pact JSON write safety but does NOT prevent same-pair file splits from colliding. Multiple files for **different** pairs (different consumer or provider name) are correct and safe. See Example 10 for the ✅/❌ pattern.
|
||||
- **Interacting settings**: leave `isolate` at its default (`true`). Do NOT set `sequence.concurrent: true`, `maxConcurrency > 1`, or `maxWorkers > 1` in this config — they defeat the serialization this rule relies on. `hookTimeout` may be raised if mock-server startup is slow, but keep `testTimeout` ≥ `hookTimeout`.
|
||||
- Do NOT add `setupFiles`, `coverage`, or other settings from the unit test config
|
||||
- Keep it minimal — Pact tests run in Node environment with extended timeout
|
||||
- 30 second timeout accommodates Pact mock server startup and interaction verification
|
||||
- Use a dedicated config file (`vitest.config.pact.ts`), not the main vitest config
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Package.json Script Naming
|
||||
|
||||
**Context**: Colon-separated naming matching pactjs-utils exactly. Scripts source `env-setup.sh` inline.
|
||||
|
||||
**Implementation**:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"test:pact:consumer": "vitest run --config vitest.config.pact.ts",
|
||||
"publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
|
||||
"can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
|
||||
"record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-frontend-app`).
|
||||
|
||||
**Key Points**:
|
||||
|
||||
- Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
|
||||
- Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
|
||||
- `PACTICIPANT` is set per-script invocation, not globally
|
||||
- Do NOT use `npx pact-broker` — use `pact-broker` directly (installed as a dependency)
|
||||
|
||||
---
|
||||
|
||||
### Example 4: Shell Scripts
|
||||
|
||||
**Context**: Reusable bash scripts aligned with pactjs-utils conventions.
|
||||
|
||||
#### `scripts/env-setup.sh` — Shared Environment Loader
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# -e: exit on error -u: error on undefined vars (catches typos/missing env vars in CI)
|
||||
set -eu
|
||||
|
||||
if [ -f .env ]; then
|
||||
set -a
|
||||
source .env
|
||||
set +a
|
||||
fi
|
||||
|
||||
export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
|
||||
export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
|
||||
```
|
||||
|
||||
#### `scripts/publish-pact.sh` — Publish Pacts to Broker
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Publish generated pact files to PactFlow/Pact Broker.
|
||||
#
|
||||
# Before publish, normalize each pact JSON: sort interactions by (description, provider state name,
|
||||
# method, path) and sort object keys via `jq -S`. This gives byte-stable output to the broker even
|
||||
# if the PactV4 generator produces ordering drift between runs. Ensures "Cannot change pact content"
|
||||
# from PactFlow never fires on ordering-only changes.
|
||||
#
|
||||
# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH, jq
|
||||
# -e: exit on error -u: error on undefined vars -o pipefail: fail if any pipe segment fails
|
||||
set -euo pipefail
|
||||
|
||||
. ./scripts/env-setup.sh
|
||||
|
||||
PACT_DIR="./pacts"
|
||||
|
||||
# Defense-in-depth: normalize interaction order for byte-stable publishes.
|
||||
for f in "$PACT_DIR"/*.json; do
|
||||
tmp="$(mktemp)"
|
||||
jq -S '.interactions |= sort_by(.description, (.providerStates[0].name // ""), .request.method, .request.path)' \
|
||||
"$f" > "$tmp"
|
||||
mv "$tmp" "$f"
|
||||
done
|
||||
|
||||
pact-broker publish "$PACT_DIR" \
|
||||
--consumer-app-version="$GITHUB_SHA" \
|
||||
--branch="$GITHUB_BRANCH" \
|
||||
--broker-base-url="$PACT_BROKER_BASE_URL" \
|
||||
--broker-token="$PACT_BROKER_TOKEN"
|
||||
```
|
||||
|
||||
#### `scripts/can-i-deploy.sh` — Deployment Safety Check
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Check if a pacticipant version can be safely deployed
|
||||
#
|
||||
# Requires: PACTICIPANT (set by caller), PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA
|
||||
# -e: exit on error -u: error on undefined vars -o pipefail: fail if any pipe segment fails
|
||||
set -euo pipefail
|
||||
|
||||
. ./scripts/env-setup.sh
|
||||
|
||||
PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
|
||||
ENVIRONMENT="${ENVIRONMENT:-dev}"
|
||||
|
||||
pact-broker can-i-deploy \
|
||||
--pacticipant "$PACTICIPANT" \
|
||||
--version="$GITHUB_SHA" \
|
||||
--to-environment "$ENVIRONMENT" \
|
||||
--retry-while-unknown=10 \
|
||||
--retry-interval=30
|
||||
```
|
||||
|
||||
#### `scripts/record-deployment.sh` — Record Deployment
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Record a deployment to an environment in Pact Broker
|
||||
# Only records on main/master branch (skips feature branches)
|
||||
#
|
||||
# Requires: PACTICIPANT, PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
|
||||
# -e: exit on error -u: error on undefined vars -o pipefail: fail if any pipe segment fails
|
||||
set -euo pipefail
|
||||
|
||||
. ./scripts/env-setup.sh
|
||||
|
||||
PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
|
||||
|
||||
if [ "$GITHUB_BRANCH" = "main" ] || [ "$GITHUB_BRANCH" = "master" ]; then
|
||||
pact-broker record-deployment \
|
||||
--pacticipant "$PACTICIPANT" \
|
||||
--version "$GITHUB_SHA" \
|
||||
--environment "${npm_config_env:-dev}"
|
||||
else
|
||||
echo "Skipping record-deployment: not on main branch (current: $GITHUB_BRANCH)"
|
||||
fi
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
|
||||
- `env-setup.sh` uses `set -eu` (no pipefail — it only sources `.env`, no pipes); broker scripts use `set -euo pipefail`
|
||||
- Use `pact-broker` directly, NOT `npx pact-broker`
|
||||
- Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
|
||||
- `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
|
||||
- `record-deployment` has branch guard (only records on main/master)
|
||||
- **`publish-pact.sh` normalizes interactions with `jq -S` + `sort_by(...)` before publishing** — ensures byte-stable payload to the broker regardless of generator ordering quirks.
|
||||
- Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
|
||||
|
||||
---
|
||||
|
||||
### Example 5: CI Workflow (`contract-test-consumer.yml`)
|
||||
|
||||
**Context**: GitHub Actions workflow for consumer CDC, matching pactjs-utils structure exactly.
|
||||
|
||||
**Implementation**:
|
||||
|
||||
```yaml
|
||||
name: Contract Test - Consumer
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened, edited]
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
env:
|
||||
PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
|
||||
PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
|
||||
GITHUB_SHA: ${{ github.sha }}
|
||||
GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
consumer-contract-test:
|
||||
if: github.actor != 'dependabot[bot]'
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version-file: '.nvmrc'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Detect Pact breaking change
|
||||
uses: ./.github/actions/detect-breaking-change
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
# (1) Generate pact files
|
||||
- name: Run consumer contract tests
|
||||
run: npm run test:pact:consumer
|
||||
|
||||
# (2) Publish pacts to broker (publish-pact.sh also normalizes interaction order as defense-in-depth)
|
||||
- name: Publish pacts to PactFlow
|
||||
run: npm run publish:pact
|
||||
|
||||
# After publish, PactFlow fires a webhook that triggers
|
||||
# the provider's contract-test-provider.yml workflow.
|
||||
# can-i-deploy retries while waiting for provider verification.
|
||||
|
||||
# (4) Check deployment safety (main only — on PRs, local verification is the gate)
|
||||
- name: Can I deploy consumer? (main only)
|
||||
if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
|
||||
run: npm run can:i:deploy:consumer
|
||||
|
||||
# (5) Record deployment (main only)
|
||||
- name: Record consumer deployment (main only)
|
||||
if: github.ref == 'refs/heads/main'
|
||||
run: npm run record:consumer:deployment --env=dev
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
|
||||
- **1:1 local/CI parity is a hard rule**: every CI step is `npm run <same-name-a-dev-uses>`. Never let CI invoke `vitest` or `pact-broker` directly — that divergence is how "works on my machine" slips in. Consumer tests, publish, can-i-deploy, and record-deployment are all the same commands a developer runs locally.
|
||||
- **Workflow-level `env` block** for broker secrets and git vars — not per-step
|
||||
- **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
|
||||
- **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
|
||||
- **can-i-deploy condition**: `github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'`
|
||||
- **Comment on (4)**: "on PRs, local verification is the gate"
|
||||
- **No upload-artifact step** — the broker is the source of truth for pact files
|
||||
- **`dependabot[bot]` skip** on the job (contract tests don't run for dependency updates)
|
||||
- **PR types include `edited`** — needed for breaking change checkbox detection in PR body
|
||||
- **`GITHUB_BRANCH`** uses `${{ github.head_ref || github.ref_name }}` — `head_ref` for PRs, `ref_name` for pushes
|
||||
|
||||
---
|
||||
|
||||
### Example 6: Detect Breaking Change Composite Action
|
||||
|
||||
**Context**: GitHub composite action that reads a `[x] Pact breaking change` checkbox from the PR body.
|
||||
|
||||
**Implementation**:
|
||||
|
||||
Create `.github/actions/detect-breaking-change/action.yml`:
|
||||
|
||||
```yaml
|
||||
name: 'Detect Pact Breaking Change'
|
||||
description: 'Reads the PR template checkbox to determine if this change is a Pact breaking change. Sets PACT_BREAKING_CHANGE env var.'
|
||||
|
||||
outputs:
|
||||
is_breaking_change:
|
||||
description: 'Whether the change is a breaking change (true/false)'
|
||||
value: ${{ steps.result.outputs.is_breaking_change }}
|
||||
|
||||
runs:
|
||||
using: 'composite'
|
||||
steps:
|
||||
# PR event path: read checkbox directly from current PR body.
|
||||
- name: Set PACT_BREAKING_CHANGE from PR description (PR only)
|
||||
if: github.event_name == 'pull_request'
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
const prBody = context.payload.pull_request.body || '';
|
||||
const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
|
||||
const isBreakingChange = breakingChangePattern.test(prBody);
|
||||
core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
|
||||
console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from PR description checkbox).`);
|
||||
|
||||
# Push-to-main path: resolve the merged PR and read the same checkbox.
|
||||
- name: Set PACT_BREAKING_CHANGE from merged PR (push to main)
|
||||
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
commit_sha: context.sha,
|
||||
});
|
||||
const merged = prs.find(pr => pr.merged_at);
|
||||
const mergedBody = merged?.body || '';
|
||||
const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
|
||||
const isBreakingChange = breakingChangePattern.test(mergedBody);
|
||||
core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
|
||||
console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from merged PR lookup).`);
|
||||
|
||||
- name: Export result
|
||||
id: result
|
||||
shell: bash
|
||||
run: echo "is_breaking_change=${PACT_BREAKING_CHANGE:-false}" >> "$GITHUB_OUTPUT"
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
|
||||
- Two separate conditional steps (better CI log readability than single if/else)
|
||||
- PR path: reads checkbox directly from PR body
|
||||
- Push-to-main path: resolves merged PR via GitHub API, reads same checkbox
|
||||
- Exports `PACT_BREAKING_CHANGE` env var for downstream steps
|
||||
- `outputs.is_breaking_change` available for consuming workflows
|
||||
- Uses a case-insensitive checkbox regex (`/\[\s*[xX]\s*\]\s*Pact breaking change/i`) to detect checked states robustly
|
||||
|
||||
---
|
||||
|
||||
### Example 7: Consumer Test Using PactV4 Builder
|
||||
|
||||
**Context**: Consumer pact test using PactV4 `addInteraction()` builder pattern. The test MUST call **real consumer code** (your actual API client/service functions) against the mock server — not raw `fetch()`. Using `fetch()` directly defeats the purpose of CDC testing because it doesn't verify your actual consumer code works with the contract.
|
||||
|
||||
**Implementation**:
|
||||
|
||||
The consumer code must expose a way to inject the base URL (e.g., `setApiUrl()`, constructor parameter, or environment variable). This is a prerequisite for contract testing.
|
||||
|
||||
```typescript
|
||||
// src/api/movie-client.ts — The REAL consumer code (already exists in your project)
|
||||
import axios from 'axios';
|
||||
|
||||
const axiosInstance = axios.create({
|
||||
baseURL: process.env.API_URL || 'http://localhost:3001',
|
||||
});
|
||||
|
||||
// Expose a way to override the base URL for Pact testing
|
||||
export const setApiUrl = (url: string) => {
|
||||
axiosInstance.defaults.baseURL = url;
|
||||
};
|
||||
|
||||
export const getMovies = async () => {
|
||||
const res = await axiosInstance.get('/movies');
|
||||
return res.data;
|
||||
};
|
||||
|
||||
export const getMovieById = async (id: number) => {
|
||||
const res = await axiosInstance.get(`/movies/${id}`);
|
||||
return res.data;
|
||||
};
|
||||
```
|
||||
|
||||
```typescript
|
||||
// tests/contract/consumer/get-movies.pacttest.ts
|
||||
import { MatchersV3 } from '@pact-foundation/pact';
|
||||
import type { V3MockServer } from '@pact-foundation/pact';
|
||||
import { createProviderState, setJsonBody, setJsonContent } from '../support/consumer-helpers';
|
||||
import { movieExists } from '../support/provider-states';
|
||||
import { createPact } from '../support/pact-config';
|
||||
// Import REAL consumer code — this is what we're actually testing
|
||||
import { getMovies, getMovieById, setApiUrl } from '../../../src/api/movie-client';
|
||||
|
||||
const { like, integer, string } = MatchersV3;
|
||||
|
||||
const pact = createPact();
|
||||
|
||||
describe('Movies API Consumer Contract', () => {
|
||||
const movieWithId = { id: 1, name: 'The Matrix', year: 1999, rating: 8.7, director: 'Wachowskis' };
|
||||
|
||||
it('should get a movie by ID', async () => {
|
||||
const [stateName, stateParams] = createProviderState(movieExists(movieWithId));
|
||||
|
||||
await pact
|
||||
.addInteraction()
|
||||
.given(stateName, stateParams)
|
||||
.uponReceiving('a request to get movie by ID')
|
||||
.withRequest(
|
||||
'GET',
|
||||
'/movies/1',
|
||||
setJsonContent({
|
||||
headers: { Accept: 'application/json' },
|
||||
}),
|
||||
)
|
||||
.willRespondWith(
|
||||
200,
|
||||
setJsonBody(
|
||||
like({
|
||||
id: integer(1),
|
||||
name: string('The Matrix'),
|
||||
year: integer(1999),
|
||||
rating: like(8.7),
|
||||
director: string('Wachowskis'),
|
||||
}),
|
||||
),
|
||||
)
|
||||
.executeTest(async (mockServer: V3MockServer) => {
|
||||
// Inject mock server URL into the REAL consumer code
|
||||
setApiUrl(mockServer.url);
|
||||
|
||||
// Call the REAL consumer function — this is what CDC testing validates
|
||||
const movie = await getMovieById(1);
|
||||
|
||||
expect(movie.id).toBe(1);
|
||||
expect(movie.name).toBe('The Matrix');
|
||||
});
|
||||
});
|
||||
|
||||
it('should handle movie not found', async () => {
|
||||
await pact
|
||||
.addInteraction()
|
||||
.given('No movies exist')
|
||||
.uponReceiving('a request for a non-existent movie')
|
||||
.withRequest('GET', '/movies/999')
|
||||
.willRespondWith(404, setJsonBody({ error: 'Movie not found' }))
|
||||
.executeTest(async (mockServer: V3MockServer) => {
|
||||
setApiUrl(mockServer.url);
|
||||
|
||||
await expect(getMovieById(999)).rejects.toThrow();
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
|
||||
- **CRITICAL**: Always test your REAL consumer code — import and call actual API client functions, never raw `fetch()`
|
||||
- Using `fetch()` directly only tests that Pact's mock server works, which is meaningless
|
||||
- Consumer code MUST expose a URL injection mechanism: `setApiUrl()`, env var override, or constructor parameter
|
||||
- If the consumer code doesn't support URL injection, add it — this is a design prerequisite for CDC testing
|
||||
- Use PactV4 `addInteraction()` builder (not PactV3 fluent API with `withRequest({...})` object)
|
||||
- **Interaction naming convention**: Use the pattern `"a request to <action> <resource> [<condition>]"` for `uponReceiving()`. Examples: `"a request to get a movie by ID"`, `"a request to delete a non-existing movie"`, `"a request to create a movie that already exists"`. These names appear in Pact Broker UI and verification logs — keep them descriptive and unique within the consumer-provider pair.
|
||||
- Use `setJsonContent` for request/response builder callbacks with query/header/body concerns; use `setJsonBody` for body-only response callbacks
|
||||
- Provider state factory functions (`movieExists`) return `ProviderStateInput` objects
|
||||
- `createProviderState` converts to `[stateName, stateParams]` tuple for `.given()`
|
||||
|
||||
**Common URL injection patterns** (pick whichever fits your consumer architecture):
|
||||
|
||||
| Pattern | Example | Best For |
|
||||
| -------------------- | -------------------------------------------- | --------------------- |
|
||||
| `setApiUrl(url)` | Mutates axios instance `baseURL` | Singleton HTTP client |
|
||||
| Constructor param | `new ApiClient({ baseUrl: mockServer.url })` | Class-based clients |
|
||||
| Environment variable | `process.env.API_URL = mockServer.url` | Config-driven apps |
|
||||
| Factory function | `createApi({ baseUrl: mockServer.url })` | Functional patterns |
|
||||
|
||||
---
|
||||
|
||||
### Example 8: Support Files
|
||||
|
||||
#### Pact Config Factory
|
||||
|
||||
```typescript
|
||||
// tests/contract/support/pact-config.ts
|
||||
import path from 'node:path';
|
||||
import { PactV4 } from '@pact-foundation/pact';
|
||||
|
||||
export const createPact = (overrides?: { consumer?: string; provider?: string }) =>
|
||||
new PactV4({
|
||||
dir: path.resolve(process.cwd(), 'pacts'),
|
||||
consumer: overrides?.consumer ?? 'MyConsumerApp',
|
||||
provider: overrides?.provider ?? 'MyProviderAPI',
|
||||
logLevel: 'warn',
|
||||
});
|
||||
```
|
||||
|
||||
#### Provider State Factories
|
||||
|
||||
```typescript
|
||||
// tests/contract/support/provider-states.ts
|
||||
import type { ProviderStateInput } from './consumer-helpers';
|
||||
|
||||
export const movieExists = (movie: { id: number; name: string; year: number; rating: number; director: string }): ProviderStateInput => ({
|
||||
name: 'An existing movie exists',
|
||||
params: movie,
|
||||
});
|
||||
|
||||
export const hasMovieWithId = (id: number): ProviderStateInput => ({
|
||||
name: 'Has a movie with a specific ID',
|
||||
params: { id },
|
||||
});
|
||||
```
|
||||
|
||||
#### Local Consumer Helpers Shim
|
||||
|
||||
```typescript
|
||||
// tests/contract/support/consumer-helpers.ts
|
||||
// TODO(temporary scaffolding): Replace local TemplateHeaders/TemplateQuery types
|
||||
// with '@seontechnologies/pactjs-utils' exports when available.
|
||||
|
||||
type TemplateHeaders = Record<string, string | number | boolean>;
|
||||
type TemplateQueryValue = string | number | boolean | Array<string | number | boolean>;
|
||||
type TemplateQuery = Record<string, TemplateQueryValue>;
|
||||
|
||||
export type ProviderStateInput = {
|
||||
name: string;
|
||||
params: Record<string, unknown>;
|
||||
};
|
||||
|
||||
type JsonMap = { [key: string]: boolean | number | string | null | JsonMap | Array<unknown> };
|
||||
type JsonContentBuilder = {
|
||||
headers: (headers: TemplateHeaders) => unknown;
|
||||
jsonBody: (body: unknown) => unknown;
|
||||
query?: (query: TemplateQuery) => unknown;
|
||||
};
|
||||
|
||||
export type JsonContentInput = {
|
||||
body?: unknown;
|
||||
headers?: TemplateHeaders;
|
||||
query?: TemplateQuery;
|
||||
};
|
||||
|
||||
export const toJsonMap = (obj: Record<string, unknown>): JsonMap =>
|
||||
Object.fromEntries(
|
||||
Object.entries(obj).map(([key, value]) => {
|
||||
if (value === null || value === undefined) return [key, 'null'];
|
||||
if (typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) return [key, JSON.stringify(value)];
|
||||
if (typeof value === 'number' || typeof value === 'boolean') return [key, value];
|
||||
if (value instanceof Date) return [key, value.toISOString()];
|
||||
return [key, String(value)];
|
||||
}),
|
||||
);
|
||||
|
||||
export const createProviderState = ({ name, params }: ProviderStateInput): [string, JsonMap] => [name, toJsonMap(params)];
|
||||
|
||||
export const setJsonContent =
|
||||
({ body, headers, query }: JsonContentInput) =>
|
||||
(builder: JsonContentBuilder): void => {
|
||||
if (query && builder.query) {
|
||||
builder.query(query);
|
||||
}
|
||||
|
||||
if (headers) {
|
||||
builder.headers(headers);
|
||||
}
|
||||
|
||||
if (body !== undefined) {
|
||||
builder.jsonBody(body);
|
||||
}
|
||||
};
|
||||
|
||||
export const setJsonBody = (body: unknown) => setJsonContent({ body });
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
|
||||
- If `@seontechnologies/pactjs-utils` is not yet installed, create a local shim that mirrors the API
|
||||
- Add a TODO comment noting to swap for the published package when available
|
||||
- The shim exports `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, and helper input types
|
||||
- Keep shim types local (or sourced from public exports only); do not import from internal Pact paths like `@pact-foundation/pact/src/*`
|
||||
|
||||
---
|
||||
|
||||
### Example 9: .gitignore Entries
|
||||
|
||||
**Context**: Pact-specific entries to add to `.gitignore`.
|
||||
|
||||
```
|
||||
# Pact contract testing artifacts
|
||||
/pacts/
|
||||
pact-logs/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 10: Test File Organization — One File Per Consumer+Provider Pair
|
||||
|
||||
**Context**: Avoiding Pact Rust FFI handle collisions when structuring consumer test files.
|
||||
|
||||
**Rule**: Every consumer+provider pair maps to exactly one `.pacttest.ts` file. Never split interactions for the same pair across multiple files.
|
||||
|
||||
**Root cause**: The Pact Rust FFI maintains one handle per consumer+provider pair per process. With `singleFork: true` (all files run sequentially in one forked process), two files for the same pair access the same FFI handle back-to-back. The second file's `new PactV4({ consumer, provider })` call re-enters the handle still holding stale interaction state from the first file. The first test in the second file starts the mock server in this corrupted state — "request was expected but not received" results, sporadic and Linux-CI-only (execution order differs between environments).
|
||||
|
||||
**Evidence**: In `pactjs-utils`, `movies-read.pacttest.ts` and `movies-write.pacttest.ts` both used `consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI'`. The vitest config and CI workflow were correct throughout. The fix was merging the two files into `movies.pacttest.ts`. The config was not changed.
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG — same consumer+provider pair split across two files
|
||||
// movies-read.pacttest.ts
|
||||
const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
|
||||
describe('Read Operations', () => { /* 4 tests: GET /movies, GET /movies/:id */ })
|
||||
|
||||
// movies-write.pacttest.ts ← second PactV4 for the SAME pair = FFI handle collision
|
||||
const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
|
||||
describe('Write Operations', () => { /* 5 tests: POST, PUT, DELETE */ })
|
||||
|
||||
// ✅ RIGHT — one file per consumer+provider pair, describe blocks for organization
|
||||
// movies.pacttest.ts
|
||||
const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
|
||||
describe('Movies API', () => {
|
||||
describe('Read Operations', () => { /* 4 tests */ })
|
||||
describe('Write Operations', () => { /* 5 tests */ })
|
||||
})
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
|
||||
- **File = contract**: A `.pacttest.ts` file represents one consumer+provider contract. One contract = one file.
|
||||
- **Describe blocks, not files**: Organize by operation type (`Read Operations`, `Write Operations`), resource, or feature — always within one file per pair.
|
||||
- **Different pairs = different files**: `ServiceA / BackendAPI` and `ServiceA / AuthAPI` are two contracts and correctly use two separate files. This rule only forbids splitting ONE pair.
|
||||
- **`singleFork: true` is not a fix for this**: It ensures correct pact JSON write semantics across files, but when two files share a pair it actually guarantees the FFI collision (both land in the same process). Without it you'd get file-write races instead. Neither is safe. The fix is one file per pair.
|
||||
- **Naming convention**: `{domain}.pacttest.ts` when one domain maps to one pair. `{consumer-kebab}-{provider-kebab}.pacttest.ts` when the filename must be self-describing about which pair it covers.
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Before presenting the consumer CDC framework to the user, verify:
|
||||
|
||||
- [ ] `vitest.config.pact.ts` is minimal **and sets `fileParallelism: false` AND `pool: 'forks'` with `poolOptions.forks.singleFork: true`** (`fileParallelism: false` prevents shared pact JSON corruption from parallel workers; forks + `singleFork: true` is required for pact JSON write safety across files — see Example 2 Key Points for mechanism and evidence)
|
||||
- [ ] Each consumer+provider pair is covered by exactly ONE `.pacttest.ts` file — never split interactions for the same pair across multiple files (two `PactV4` instances for the same pair in one process cause FFI handle collision → "request was expected but not received" on Linux CI; `singleFork: true` does NOT prevent this — it ensures both files share one process, which guarantees the collision; see Example 10)
|
||||
- [ ] `vitest.config.pact.ts` does NOT set `sequence.concurrent: true`, `maxConcurrency > 1`, `maxWorkers > 1`, or `isolate: false` — all four defeat the serialization the rule relies on
|
||||
- [ ] `scripts/publish-pact.sh` normalizes interactions with `jq -S '.interactions |= sort_by(.description, (.providerStates[0].name // ""), .request.method, .request.path)'` before the `pact-broker publish` call (ensures byte-stable payload to PactFlow regardless of generator ordering)
|
||||
- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
|
||||
- [ ] Scripts source `env-setup.sh` inline in package.json
|
||||
- [ ] Shell scripts use `pact-broker` not `npx pact-broker`
|
||||
- [ ] Shell scripts use `PACTICIPANT` env var pattern
|
||||
- [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
|
||||
- [ ] `record-deployment.sh` has branch guard
|
||||
- [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
|
||||
- [ ] CI workflow named `contract-test-consumer.yml`
|
||||
- [ ] CI has workflow-level env block (not per-step)
|
||||
- [ ] CI has `detect-breaking-change` step before install
|
||||
- [ ] CI step (1) generates pact files (calls `npm run test:pact:consumer`) — its own visible step, not folded into publish
|
||||
- [ ] CI steps are 1:1 with developer commands — every CI step calls `npm run <same-name>` a dev would run locally (no direct `vitest` or `pact-broker` invocation)
|
||||
- [ ] CI step numbering skips (3) — webhook-triggered provider verification
|
||||
- [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
|
||||
- [ ] CI has NO upload-artifact step
|
||||
- [ ] `.github/actions/detect-breaking-change/action.yml` exists
|
||||
- [ ] Consumer tests use `.pacttest.ts` extension
|
||||
- [ ] Consumer tests use PactV4 `addInteraction()` builder
|
||||
- [ ] `uponReceiving()` names follow `"a request to <action> <resource> [<condition>]"` pattern and are unique within the consumer-provider pair
|
||||
- [ ] Interaction callbacks use `setJsonContent` for query/header/body and `setJsonBody` for body-only responses
|
||||
- [ ] Request bodies use exact values (no `like()` wrapper) — Postel's Law: be strict in what you send
|
||||
- [ ] `like()`, `eachLike()`, `string()`, `integer()` matchers are only used in `willRespondWith` (responses), not in `withRequest` (requests) — matchers check type/shape, not exact values
|
||||
- [ ] Consumer tests call REAL consumer code (actual API client functions), NOT raw `fetch()`
|
||||
- [ ] Consumer code exposes URL injection mechanism (`setApiUrl()`, env var, or constructor param)
|
||||
- [ ] Local consumer-helpers shim present if pactjs-utils not installed
|
||||
- [ ] `.gitignore` includes `/pacts/` and `pact-logs/`
|
||||
|
||||
## Related Fragments
|
||||
|
||||
- `pactjs-utils-overview.md` — Library decision tree and installation
|
||||
- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, **one-interaction-per-`it()` rule**
|
||||
- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns; consumer and provider BOTH require `pool: 'forks'` + `singleFork: true` — same FFI-safety rule applies on both sides
|
||||
- `pactjs-utils-request-filter.md` — Auth injection for provider verification
|
||||
- `pact-broker-webhooks.md` — PactFlow → GitHub webhook auth pattern (dedicated user, classic PAT, PactFlow secret) and staleness monitoring
|
||||
- `contract-testing.md` — Foundational CDC patterns and resilience coverage
|
||||
Reference in New Issue
Block a user