bmad-method-test-architecture-enterprise 1.5.1 → 1.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. package/docs/explanation/tea-overview.md +3 -3
  2. package/docs/explanation/testing-as-engineering.md +1 -1
  3. package/docs/reference/knowledge-base.md +11 -9
  4. package/docs/reference/troubleshooting.md +4 -4
  5. package/package.json +1 -1
  6. package/release_notes.md +9 -6
  7. package/src/testarch/knowledge/contract-testing.md +118 -111
  8. package/src/testarch/knowledge/pact-consumer-di.md +310 -0
  9. package/src/testarch/knowledge/pact-consumer-framework-setup.md +631 -0
  10. package/src/testarch/knowledge/pactjs-utils-consumer-helpers.md +59 -2
  11. package/src/testarch/knowledge/pactjs-utils-overview.md +9 -3
  12. package/src/testarch/tea-index.csv +4 -2
  13. package/src/workflows/testarch/ci/steps-c/step-02-generate-pipeline.md +6 -6
  14. package/src/workflows/testarch/framework/checklist.md +24 -0
  15. package/src/workflows/testarch/framework/steps-c/step-03-scaffold-framework.md +17 -13
  16. package/test/test-installation-components.js +1 -1
  17. package/test/test-knowledge-base.js +1 -1
package/docs/explanation/tea-overview.md CHANGED
@@ -345,7 +345,7 @@ Production-ready contract testing utilities that reduce raw Pact.js boilerplate
345
345
  - Install: `npm install -D @seontechnologies/pactjs-utils @pact-foundation/pact`
346
346
  - Config: `tea_use_pactjs_utils: true` (default is `true`)
347
347
  - Impacts: `framework`, `atdd`, `automate`, `test-design`, `test-review`, `ci`
348
- - Utilities include: createProviderState, toJsonMap, buildVerifierOptions, buildMessageVerifierOptions, createRequestFilter, noOpRequestFilter, handlePactBrokerUrlAndSelectors, getProviderVersionTags
348
+ - Utilities include: createProviderState, toJsonMap, setJsonBody, setJsonContent, buildVerifierOptions, buildMessageVerifierOptions, createRequestFilter, noOpRequestFilter, handlePactBrokerUrlAndSelectors, getProviderVersionTags
349
349
  - Supports local monorepo flow (`pactUrls`) and remote broker flow (`PACT_BROKER_BASE_URL`, `PACT_BROKER_TOKEN`)
350
350
 
351
351
  ### Browser Automation (Playwright CLI + MCP)
@@ -455,7 +455,7 @@ Optional MCP integration for design-time broker interaction in contract testing
455
455
  - [Test Quality Standards](/docs/explanation/test-quality-standards.md) - Definition of Done, determinism, isolation, explicit assertions
456
456
  - [Fixture Architecture](/docs/explanation/fixture-architecture.md) - Pure function → fixture → composition pattern
457
457
  - [Network-First Patterns](/docs/explanation/network-first-patterns.md) - Intercept-before-navigate, eliminating flakiness
458
- - [Knowledge Base System](/docs/explanation/knowledge-base-system.md) - Context engineering with tea-index.csv, 40 fragments
458
+ - [Knowledge Base System](/docs/explanation/knowledge-base-system.md) - Context engineering with tea-index.csv, 42 fragments
459
459
  - [Engagement Models](/docs/explanation/engagement-models.md) - TEA Lite, TEA Solo, TEA Integrated (5 models explained)
460
460
 
461
461
  ### Philosophy & Design
@@ -470,5 +470,5 @@ Optional MCP integration for design-time broker interaction in contract testing
470
470
 
471
471
  - [TEA Command Reference](/docs/reference/commands.md) - All 9 workflows: inputs, outputs, phases, frequency
472
472
  - [TEA Configuration Reference](/docs/reference/configuration.md) - Config options, file locations, setup examples
473
- - [Knowledge Base Index](/docs/reference/knowledge-base.md) - 40 fragments categorized and explained
473
+ - [Knowledge Base Index](/docs/reference/knowledge-base.md) - 42 fragments categorized and explained
474
474
  - [Glossary - TEA Section](/docs/glossary/index.md#test-architect-tea-concepts) - 20 TEA-specific terms defined
package/docs/explanation/testing-as-engineering.md CHANGED
@@ -41,7 +41,7 @@ The solution combines three components that work together to enforce quality:
41
41
 
42
42
  **Playwright-Utils examples:** `api-request`, `auth-session`, `intercept-network-call`, `recurse`, `log`, `network-recorder`, `burn-in`, `network-error-monitor`, `file-utils`.
43
43
 
44
- **pactjs-utils examples:** `createProviderState`, `toJsonMap`, `createRequestFilter`, `noOpRequestFilter`, `buildVerifierOptions`, `buildMessageVerifierOptions`.
44
+ **pactjs-utils examples:** `createProviderState`, `toJsonMap`, `setJsonBody`, `setJsonContent`, `createRequestFilter`, `noOpRequestFilter`, `buildVerifierOptions`, `buildMessageVerifierOptions`.
45
45
 
46
46
  Together, these utility libraries eliminate the need to reinvent core testing primitives across UI, API, web, non-web, and contract testing.
47
47
 
package/docs/reference/knowledge-base.md CHANGED
@@ -175,14 +175,16 @@ Feature flag testing and pure API testing patterns.
175
175
 
176
176
  Contract testing fundamentals plus Pact.js Utils and Pact MCP integrations.
177
177
 
178
- | Fragment | Description | Key Topics |
179
- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------- |
180
- | [contract-testing](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/contract-testing.md) | Raw Pact patterns, publishing, verification, resilience | Contract testing, Pact fundamentals |
181
- | [pactjs-utils-overview](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-overview.md) | Installation, flow decision tree, utility map | pactjs-utils, CDCT/BDCT, integration strategy |
182
- | [pactjs-utils-consumer-helpers](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-consumer-helpers.md) | `createProviderState`, `toJsonMap` for consumer-side provider states | pactjs-utils, consumer testing, provider state |
183
- | [pactjs-utils-provider-verifier](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-provider-verifier.md) | `buildVerifierOptions`, `buildMessageVerifierOptions`, broker selectors, tagging | pactjs-utils, provider verification, CI |
184
- | [pactjs-utils-request-filter](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-request-filter.md) | `createRequestFilter`, `noOpRequestFilter` auth/header patterns | pactjs-utils, request filter, auth injection |
185
- | [pact-mcp](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pact-mcp.md) | SmartBear MCP tools for provider states, review, can-i-deploy, matrix | pact-mcp, broker interaction, pactflow |
178
+ | Fragment | Description | Key Topics |
179
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
180
+ | [contract-testing](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/contract-testing.md) | Raw Pact patterns, publishing, verification, resilience | Contract testing, Pact fundamentals |
181
+ | [pactjs-utils-overview](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-overview.md) | Installation, flow decision tree, utility map | pactjs-utils, CDCT/BDCT, integration strategy |
182
+ | [pactjs-utils-consumer-helpers](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-consumer-helpers.md) | Provider-state helpers: `createProviderState`, `toJsonMap`; request/response callback helpers: `setJsonBody`, `setJsonContent` | pactjs-utils, consumer testing, provider state |
183
+ | [pactjs-utils-provider-verifier](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-provider-verifier.md) | `buildVerifierOptions`, `buildMessageVerifierOptions`, broker selectors, tagging | pactjs-utils, provider verification, CI |
184
+ | [pactjs-utils-request-filter](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-request-filter.md) | `createRequestFilter`, `noOpRequestFilter` auth/header patterns | pactjs-utils, request filter, auth injection |
185
+ | [pact-mcp](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pact-mcp.md) | SmartBear MCP tools for provider states, review, can-i-deploy, matrix | pact-mcp, broker interaction, pactflow |
186
+ | [pact-consumer-framework-setup](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pact-consumer-framework-setup.md) | Consumer CDC framework scaffolding: directory layout, scripts, CI workflow, and PactV4 test patterns | pactjs-utils, consumer CDC, framework setup |
187
+ | [pact-consumer-di](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pact-consumer-di.md) | Dependency-injection pattern for Pact consumer tests using real client code | pact, consumer, DI, contract accuracy |
186
188
 
187
189
  **Used in:** `framework`, `test-design`, `atdd`, `automate`, `test-review`, `ci` (conditioned by `tea_use_pactjs_utils` and `tea_pact_mcp`)
188
190
 
@@ -255,7 +257,7 @@ Fragments are loaded based on workflow needs and tier priority:
255
257
  - **Extended tier**: Loaded when the workflow context requires them (e.g., `auth-session.md` when tests involve authentication)
256
258
  - **Specialized tier**: Only loaded when the specific use case matches (e.g., contract-testing for microservices, email-auth for email flows)
257
259
 
258
- **Fragment Location:** `src/testarch/knowledge/` (all 40 fragments in a single directory)
260
+ **Fragment Location:** `src/testarch/knowledge/` (all 42 fragments in a single directory)
259
261
 
260
262
  **Manifest:** `src/testarch/tea-index.csv`
261
263
 
package/docs/reference/troubleshooting.md CHANGED
@@ -308,7 +308,7 @@ If the BMAD installer can run but cannot fetch the Test Architect module from Gi
308
308
 
309
309
  ```bash
310
310
  cat _bmad/tea/testarch/tea-index.csv | wc -l
311
- # Should show 41 lines (header + 40 fragments)
311
+ # Should show 43 lines (header + 42 fragments)
312
312
  ```
313
313
 
314
314
  2. Check knowledge fragment files:
@@ -613,7 +613,7 @@ If the BMAD installer can run but cannot fetch the Test Architect module from Gi
613
613
 
614
614
  **Causes**:
615
615
 
616
- - Up to 40 fragments loading at once (depends on workflow and enabled integrations)
616
+ - Up to 42 fragments loading at once (depends on workflow and enabled integrations)
617
617
  - Large fragment file sizes
618
618
  - Disk I/O bottleneck
619
619
 
@@ -691,7 +691,7 @@ Check these first:
691
691
  - [ ] TEA is installed: `ls -la _bmad/tea/`
692
692
  - [ ] Using the correct invocation for your tool: slash namespace `/bmad:tea:*` (not `/bmad:bmm:tea:*`) or Codex skill equivalents (`$bmad-tea-*`)
693
693
  - [ ] Module.yaml exists and is valid
694
- - [ ] Knowledge base files present (40 fragments)
694
+ - [ ] Knowledge base files present (42 fragments)
695
695
  - [ ] Output directory exists and is writable
696
696
  - [ ] No disk space issues: `df -h`
697
697
  - [ ] Node version >=20.0.0: `node --version`
@@ -755,7 +755,7 @@ done
755
755
 
756
756
  # Check knowledge base
757
757
  fragment_count=$(ls _bmad/tea/testarch/knowledge/*.md 2>/dev/null | wc -l)
758
- echo "Knowledge fragments: $fragment_count (expected: 40)"
758
+ echo "Knowledge fragments: $fragment_count (expected: 42)"
759
759
 
760
760
  # Check tea-index.csv
761
761
  csv_lines=$(wc -l < _bmad/tea/testarch/tea-index.csv 2>/dev/null || echo "0")
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/package.json",
3
3
  "name": "bmad-method-test-architecture-enterprise",
4
- "version": "1.5.1",
4
+ "version": "1.5.2",
5
5
  "description": "Master Test Architect for quality strategy, test automation, and release gates",
6
6
  "keywords": [
7
7
  "bmad",
package/release_notes.md CHANGED
@@ -1,10 +1,13 @@
1
- ## 🚀 What's New in v1.5.1
1
+ ## 🚀 What's New in v1.5.2
2
+
3
+ ### ✨ New Features
4
+ - feat: harden pact framework and knowledge
5
+
6
+ ### 🐛 Bug Fixes
7
+ - fix: pr comments
2
8
 
3
9
  ### 📦 Other Changes
4
- - docs: update codex skill mode
5
- - review comment
6
- - review comments 2
7
- - Merge pull request #50 from bmad-code-org/docs/update-codex-skill-mode
10
+ - Merge pull request #51 from bmad-code-org/feat/harden-pact-framework-flow
8
11
 
9
12
 
10
13
  ## 📦 Installation
@@ -14,4 +17,4 @@ npx bmad-method install
14
17
  # Select "Test Architect" from module menu
15
18
  ```
16
19
 
17
- **Full Changelog**: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/compare/v1.5.0...v1.5.1
20
+ **Full Changelog**: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/compare/v1.5.1...v1.5.2
package/src/testarch/knowledge/contract-testing.md CHANGED
@@ -162,13 +162,13 @@ describe('User API Contract', () => {
162
162
  });
163
163
  ```
164
164
 
165
- **package.json scripts**:
165
+ **package.json scripts** (when using pactjs-utils conventions, prefer `test:pact:consumer` naming — see `pact-consumer-framework-setup.md`):
166
166
 
167
167
  ```json
168
168
  {
169
169
  "scripts": {
170
- "test:contract": "jest tests/contract --testTimeout=30000",
171
- "pact:publish": "pact-broker publish ./pacts --consumer-app-version=$GITHUB_SHA --broker-base-url=$PACT_BROKER_BASE_URL --broker-token=$PACT_BROKER_TOKEN"
170
+ "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
171
+ "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
172
172
  }
173
173
  }
174
174
  ```
@@ -224,10 +224,10 @@ describe('Pact Provider Verification', () => {
224
224
  providerBaseUrl: `http://localhost:${PORT}`,
225
225
 
226
226
  // Pact Broker configuration
227
- pactBrokerUrl: process.env.PACT_BROKER_URL,
227
+ pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
228
228
  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
229
229
  publishVerificationResult: process.env.CI === 'true',
230
- providerVersion: process.env.GIT_SHA || 'dev',
230
+ providerVersion: process.env.GITHUB_SHA || 'dev',
231
231
 
232
232
  // State handlers: Setup provider state for each interaction
233
233
  stateHandlers: {
@@ -279,7 +279,8 @@ describe('Pact Provider Verification', () => {
279
279
  **CI integration**:
280
280
 
281
281
  ```yaml
282
- # .github/workflows/pact-provider.yml
282
+ # .github/workflows/contract-test-provider.yml
283
+ # NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
283
284
  name: Pact Provider Verification
284
285
  on:
285
286
  pull_request:
@@ -307,22 +308,16 @@ jobs:
307
308
  run: npm run db:migrate
308
309
 
309
310
  - name: Verify pacts
310
- run: npm run test:contract:provider
311
+ run: npm run test:pact:provider:remote:contract
311
312
  env:
312
- PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
313
+ PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
313
314
  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
314
- GIT_SHA: ${{ github.sha }}
315
- CI: true
315
+ GITHUB_SHA: ${{ github.sha }}
316
+ GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
316
317
 
317
318
  - name: Can I Deploy?
318
- run: |
319
- npx pact-broker can-i-deploy \
320
- --pacticipant user-api-service \
321
- --version ${{ github.sha }} \
322
- --to-environment production
323
- env:
324
- PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_URL }}
325
- PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
319
+ if: github.ref == 'refs/heads/main'
320
+ run: npm run can:i:deploy:provider
326
321
  ```
327
322
 
328
323
  **Key Points**:
@@ -337,12 +332,13 @@ jobs:
337
332
 
338
333
  ### Example 3: Contract CI Integration (Consumer & Provider Workflow)
339
334
 
340
- **Context**: Complete CI/CD workflow coordinating consumer pact publishing and provider verification.
335
+ **Context**: Simplified overview of consumer and provider CI coordination. For the complete consumer CI workflow with env blocks, concurrency, and breaking-change detection, see `pact-consumer-framework-setup.md` Example 5.
341
336
 
342
337
  **Implementation**:
343
338
 
344
339
  ```yaml
345
- # .github/workflows/pact-consumer.yml (Consumer side)
340
+ # .github/workflows/contract-test-consumer.yml (Consumer side)
341
+ # NOTE: Canonical naming is contract-test-consumer.yml per pactjs-utils conventions
346
342
  name: Pact Consumer Tests
347
343
  on:
348
344
  pull_request:
@@ -364,30 +360,23 @@ jobs:
364
360
  run: npm ci
365
361
 
366
362
  - name: Run consumer contract tests
367
- run: npm run test:contract
363
+ run: npm run test:pact:consumer
368
364
 
369
365
  - name: Publish pacts to broker
370
- if: github.ref == 'refs/heads/main' || github.event_name == 'pull_request'
371
- run: |
372
- npx pact-broker publish ./pacts \
373
- --consumer-app-version ${{ github.sha }} \
374
- --branch ${{ github.head_ref || github.ref_name }} \
375
- --broker-base-url ${{ secrets.PACT_BROKER_URL }} \
376
- --broker-token ${{ secrets.PACT_BROKER_TOKEN }}
377
-
378
- - name: Tag pact with environment (main branch only)
366
+ run: npm run publish:pact
367
+
368
+ - name: Can I deploy consumer? (main only)
369
+ if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
370
+ run: npm run can:i:deploy:consumer
371
+
372
+ - name: Record consumer deployment (main only)
379
373
  if: github.ref == 'refs/heads/main'
380
- run: |
381
- npx pact-broker create-version-tag \
382
- --pacticipant user-management-web \
383
- --version ${{ github.sha }} \
384
- --tag production \
385
- --broker-base-url ${{ secrets.PACT_BROKER_URL }} \
386
- --broker-token ${{ secrets.PACT_BROKER_TOKEN }}
374
+ run: npm run record:consumer:deployment --env=dev
387
375
  ```
388
376
 
389
377
  ```yaml
390
- # .github/workflows/pact-provider.yml (Provider side)
378
+ # .github/workflows/contract-test-provider.yml (Provider side)
379
+ # NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
391
380
  name: Pact Provider Verification
392
381
  on:
393
382
  pull_request:
@@ -414,38 +403,20 @@ jobs:
414
403
  run: docker-compose up -d
415
404
 
416
405
  - name: Run provider verification
417
- run: npm run test:contract:provider
406
+ run: npm run test:pact:provider:remote:contract
418
407
  env:
419
- PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
408
+ PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
420
409
  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
421
- GIT_SHA: ${{ github.sha }}
422
- CI: true
410
+ GITHUB_SHA: ${{ github.sha }}
411
+ GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
423
412
 
424
- - name: Publish verification results
425
- if: always()
426
- run: echo "Verification results published to broker"
413
+ - name: Can I deploy provider? (main only)
414
+ if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
415
+ run: npm run can:i:deploy:provider
427
416
 
428
- - name: Can I Deploy to Production?
417
+ - name: Record provider deployment (main only)
429
418
  if: github.ref == 'refs/heads/main'
430
- run: |
431
- npx pact-broker can-i-deploy \
432
- --pacticipant user-api-service \
433
- --version ${{ github.sha }} \
434
- --to-environment production \
435
- --broker-base-url ${{ secrets.PACT_BROKER_URL }} \
436
- --broker-token ${{ secrets.PACT_BROKER_TOKEN }} \
437
- --retry-while-unknown 6 \
438
- --retry-interval 10
439
-
440
- - name: Record deployment (if can-i-deploy passed)
441
- if: success() && github.ref == 'refs/heads/main'
442
- run: |
443
- npx pact-broker record-deployment \
444
- --pacticipant user-api-service \
445
- --version ${{ github.sha }} \
446
- --environment production \
447
- --broker-base-url ${{ secrets.PACT_BROKER_URL }} \
448
- --broker-token ${{ secrets.PACT_BROKER_TOKEN }}
419
+ run: npm run record:provider:deployment --env=dev
449
420
  ```
450
421
 
451
422
  **Pact Broker Webhook Configuration**:
@@ -726,7 +697,7 @@ export async function getUserById(
726
697
 
727
698
  ---
728
699
 
729
- ### Example 4: Pact Broker Housekeeping & Lifecycle Management
700
+ ### Example 5: Pact Broker Housekeeping & Lifecycle Management
730
701
 
731
702
  **Context**: Automated broker maintenance to prevent contract sprawl and noise.
732
703
 
@@ -741,9 +712,9 @@ export async function getUserById(
741
712
  * - Tag releases for environment tracking
742
713
  */
743
714
 
744
- import { execSync } from 'child_process';
715
+ import { execFileSync } from 'node:child_process';
745
716
 
746
- const PACT_BROKER_URL = process.env.PACT_BROKER_URL!;
717
+ const PACT_BROKER_BASE_URL = process.env.PACT_BROKER_BASE_URL!;
747
718
  const PACT_BROKER_TOKEN = process.env.PACT_BROKER_TOKEN!;
748
719
  const PACTICIPANT = 'user-api-service';
749
720
 
@@ -753,13 +724,21 @@ const PACTICIPANT = 'user-api-service';
753
724
  function tagRelease(version: string, environment: 'staging' | 'production') {
754
725
  console.log(`🏷️ Tagging ${PACTICIPANT} v${version} as ${environment}`);
755
726
 
756
- execSync(
757
- `npx pact-broker create-version-tag \
758
- --pacticipant ${PACTICIPANT} \
759
- --version ${version} \
760
- --tag ${environment} \
761
- --broker-base-url ${PACT_BROKER_URL} \
762
- --broker-token ${PACT_BROKER_TOKEN}`,
727
+ execFileSync(
728
+ 'pact-broker',
729
+ [
730
+ 'create-version-tag',
731
+ '--pacticipant',
732
+ PACTICIPANT,
733
+ '--version',
734
+ version,
735
+ '--tag',
736
+ environment,
737
+ '--broker-base-url',
738
+ PACT_BROKER_BASE_URL,
739
+ '--broker-token',
740
+ PACT_BROKER_TOKEN,
741
+ ],
763
742
  { stdio: 'inherit' },
764
743
  );
765
744
  }
@@ -770,13 +749,21 @@ function tagRelease(version: string, environment: 'staging' | 'production') {
770
749
  function recordDeployment(version: string, environment: 'staging' | 'production') {
771
750
  console.log(`📝 Recording deployment of ${PACTICIPANT} v${version} to ${environment}`);
772
751
 
773
- execSync(
774
- `npx pact-broker record-deployment \
775
- --pacticipant ${PACTICIPANT} \
776
- --version ${version} \
777
- --environment ${environment} \
778
- --broker-base-url ${PACT_BROKER_URL} \
779
- --broker-token ${PACT_BROKER_TOKEN}`,
752
+ execFileSync(
753
+ 'pact-broker',
754
+ [
755
+ 'record-deployment',
756
+ '--pacticipant',
757
+ PACTICIPANT,
758
+ '--version',
759
+ version,
760
+ '--environment',
761
+ environment,
762
+ '--broker-base-url',
763
+ PACT_BROKER_BASE_URL,
764
+ '--broker-token',
765
+ PACT_BROKER_TOKEN,
766
+ ],
780
767
  { stdio: 'inherit' },
781
768
  );
782
769
  }
@@ -788,13 +775,21 @@ function recordDeployment(version: string, environment: 'staging' | 'production'
788
775
  function cleanupOldPacts() {
789
776
  console.log(`🧹 Cleaning up old pacts for ${PACTICIPANT}`);
790
777
 
791
- execSync(
792
- `npx pact-broker clean \
793
- --pacticipant ${PACTICIPANT} \
794
- --broker-base-url ${PACT_BROKER_URL} \
795
- --broker-token ${PACT_BROKER_TOKEN} \
796
- --keep-latest-for-branch 1 \
797
- --keep-min-age 30`,
778
+ execFileSync(
779
+ 'pact-broker',
780
+ [
781
+ 'clean',
782
+ '--pacticipant',
783
+ PACTICIPANT,
784
+ '--broker-base-url',
785
+ PACT_BROKER_BASE_URL,
786
+ '--broker-token',
787
+ PACT_BROKER_TOKEN,
788
+ '--keep-latest-for-branch',
789
+ '1',
790
+ '--keep-min-age',
791
+ '30',
792
+ ],
798
793
  { stdio: 'inherit' },
799
794
  );
800
795
  }
@@ -806,15 +801,25 @@ function canIDeploy(version: string, toEnvironment: string): boolean {
806
801
  console.log(`🔍 Checking if ${PACTICIPANT} v${version} can deploy to ${toEnvironment}`);
807
802
 
808
803
  try {
809
- execSync(
810
- `npx pact-broker can-i-deploy \
811
- --pacticipant ${PACTICIPANT} \
812
- --version ${version} \
813
- --to-environment ${toEnvironment} \
814
- --broker-base-url ${PACT_BROKER_URL} \
815
- --broker-token ${PACT_BROKER_TOKEN} \
816
- --retry-while-unknown 6 \
817
- --retry-interval 10`,
804
+ execFileSync(
805
+ 'pact-broker',
806
+ [
807
+ 'can-i-deploy',
808
+ '--pacticipant',
809
+ PACTICIPANT,
810
+ '--version',
811
+ version,
812
+ '--to-environment',
813
+ toEnvironment,
814
+ '--broker-base-url',
815
+ PACT_BROKER_BASE_URL,
816
+ '--broker-token',
817
+ PACT_BROKER_TOKEN,
818
+ '--retry-while-unknown',
819
+ '10',
820
+ '--retry-interval',
821
+ '30',
822
+ ],
818
823
  { stdio: 'inherit' },
819
824
  );
820
825
  return true;
@@ -890,7 +895,7 @@ jobs:
890
895
  - name: Check pact compatibility
891
896
  run: npm run pact:can-deploy ${{ github.ref_name }} production
892
897
  env:
893
- PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
898
+ PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
894
899
  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
895
900
 
896
901
  deploy:
@@ -903,7 +908,7 @@ jobs:
903
908
  - name: Record deployment in Pact Broker
904
909
  run: npm run pact:record ${{ github.ref_name }} production
905
910
  env:
906
- PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
911
+ PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
907
912
  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
908
913
  ```
909
914
 
@@ -925,7 +930,7 @@ jobs:
925
930
  - name: Cleanup old pacts
926
931
  run: npm run pact:cleanup
927
932
  env:
928
- PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
933
+ PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
929
934
  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
930
935
  ```
931
936
 
@@ -955,7 +960,7 @@ Before implementing contract testing, verify:
955
960
  ## Integration Points
956
961
 
957
962
  - Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
958
- - Related fragments: `test-levels-framework.md`, `ci-burn-in.md`
963
+ - Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
959
964
  - Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
960
965
 
961
966
  ---
@@ -964,15 +969,17 @@ Before implementing contract testing, verify:
964
969
 
965
970
  When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
966
971
 
967
- | Manual Pattern (raw Pact.js) | Pact.js Utils Equivalent | Benefit |
968
- | ------------------------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------ |
969
- | Manual `JsonMap` casting for `.given()` params | `createProviderState({ name, params })` | Type-safe, auto-conversion of Date/null/nested objects |
970
- | 30+ lines of `VerifierOptions` assembly | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection |
971
- | Manual broker URL + selector logic from env vars | `handlePactBrokerUrlAndSelectors({ ..., options })` | Mutates options in-place with broker URL and selectors |
972
- | DIY Express middleware for auth injection | `createRequestFilter({ tokenGenerator })` | Bearer prefix contract prevents double-prefix bugs |
973
- | Manual CI branch/tag extraction | `getProviderVersionTags()` | CI-aware (GitHub Actions, GitLab CI, etc.) |
974
- | Message verifier config assembly | `buildMessageVerifierOptions({ provider, messageProviders })` | Same one-call pattern for Kafka/async contracts |
975
- | Inline no-op filter `(req, res, next) => next()` | `noOpRequestFilter` | Pre-built pass-through for no-auth providers |
972
+ | Manual Pattern (raw Pact.js) | Pact.js Utils Equivalent | Benefit |
973
+ | -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
974
+ | Manual `JsonMap` casting for `.given()` params | `createProviderState({ name, params })` | Type-safe, auto-conversion of Date/null/nested objects |
975
+ | Repeated builder callbacks for query/header/body | `setJsonContent({ query, headers, body })` | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)` |
976
+ | Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)` | Body-only shorthand for cleaner response builders |
977
+ | 30+ lines of `VerifierOptions` assembly | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection |
978
+ | Manual broker URL + selector logic from env vars | `handlePactBrokerUrlAndSelectors({ ..., options })` | Mutates options in-place with broker URL and selectors |
979
+ | DIY Express middleware for auth injection | `createRequestFilter({ tokenGenerator })` | Bearer prefix contract prevents double-prefix bugs |
980
+ | Manual CI branch/tag extraction | `getProviderVersionTags()` | CI-aware (GitHub Actions, GitLab CI, etc.) |
981
+ | Message verifier config assembly | `buildMessageVerifierOptions({ provider, messageProviders })` | Same one-call pattern for Kafka/async contracts |
982
+ | Inline no-op filter `(req, res, next) => next()` | `noOpRequestFilter` | Pre-built pass-through for no-auth providers |
976
983
 
977
984
  See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
978
985