bmad-method-test-architecture-enterprise 1.3.0 → 1.3.1

package/docs/explanation/testing-as-engineering.md

@@ -1,9 +1,9 @@
 ---
 title: 'AI-Generated Testing: Why Most Approaches Fail'
-description: How Playwright-Utils, TEA workflows, and Playwright MCPs solve AI test quality problems
+description: How Playwright-Utils, pactjs-utils, TEA workflows, Playwright CLI, and MCPs solve AI test quality problems
 ---
 
-AI-generated tests frequently fail in production because they lack systematic quality standards. This document explains the problem and presents a solution combining three components: Playwright-Utils, TEA (Test Engineering Architect), and Playwright MCPs.
+AI-generated tests frequently fail in production because they lack systematic quality standards. This document explains the problem and presents a solution combining utility standards, TEA workflows, and automation interfaces across both UI, API and contract testing.
 
 :::note[Source]
 This article is adapted from [The Testing Meta Most Teams Have Not Caught Up To Yet](https://dev.to/muratkeremozcan/the-testing-meta-most-teams-have-not-caught-up-to-yet-5765) by Murat K Ozcan.
@@ -30,25 +30,22 @@ AI excels at generating code quickly, but testing requires precision and consist
 
 The solution combines three components that work together to enforce quality:
 
-### Playwright-Utils
+### 1. Utilities: Playwright-Utils + Pact.js Utils
 
-Bridges the gap between Cypress ergonomics and Playwright's capabilities by standardizing commonly reinvented primitives through utility functions.
+`@seontechnologies/playwright-utils` standardizes commonly reinvented testing primitives across UI, API, web, and non-web flows. `@seontechnologies/pactjs-utils` standardizes Pact.js contract-testing primitives for provider state setup, request filtering, and provider/message verifier configuration.
 
-| Utility                | Purpose                           |
-| ---------------------- | --------------------------------- |
-| api-request            | API calls with schema validation  |
-| auth-session           | Authentication handling           |
-| intercept-network-call | Network mocking and interception  |
-| recurse                | Retry logic and polling           |
-| log                    | Structured logging                |
-| network-recorder       | Record and replay network traffic |
-| burn-in                | Smart test selection for CI       |
-| network-error-monitor  | HTTP error detection              |
-| file-utils             | CSV/PDF handling                  |
+| Track              | Utility Layer                        | Purpose                                                  |
+| ------------------ | ------------------------------------ | -------------------------------------------------------- |
+| UI/API/Web/Non-web | `@seontechnologies/playwright-utils` | Reusable testing primitives and fixtures                 |
+| Contract           | `@seontechnologies/pactjs-utils`     | Reusable Pact consumer/provider helpers and verification |
 
-These utilities eliminate the need to reinvent authentication, API calls, retries, and logging for every project.
+**Playwright-Utils examples:** `api-request`, `auth-session`, `intercept-network-call`, `recurse`, `log`, `network-recorder`, `burn-in`, `network-error-monitor`, `file-utils`.
 
-### TEA (Test Architect Agent)
+**pactjs-utils examples:** `createProviderState`, `toJsonMap`, `createRequestFilter`, `noOpRequestFilter`, `buildVerifierOptions`, `buildMessageVerifierOptions`.
+
+Together, these utility libraries eliminate the need to reinvent core testing primitives across UI, API, web, non-web, and contract testing.
+
+### 2. Process: TEA (Test Architect Agent)
 
 A quality operating model packaged as eight executable workflows spanning test design, CI/CD gates, and release readiness. TEA encodes test architecture expertise into repeatable processes.
 
@@ -67,28 +64,35 @@ A quality operating model packaged as eight executable workflows spanning test d
 TEA doesn't just generate tests—it provides a complete quality operating model with workflows for planning, execution, and release gates.
 :::
 
-### Playwright MCPs
+### 3. Automation Interfaces: Playwright CLI + MCPs
+
+Automation interfaces enable real-time verification during test generation and review across browser and contract tracks:
+
+- **Playwright CLI**: token-efficient browser automation for stateless execution and fast checks in workflows.
+- **Playwright MCP**: stateful browser automation with richer context for interactive exploration and DOM validation.
+- **Pact MCP**: broker-aware contract automation for verification matrix queries, provider-state discovery, compatibility analysis, and `can-i-deploy` deployment decisions.
 
-Model Context Protocols enable real-time verification during test generation. Instead of inferring selectors and behavior from documentation, MCPs allow agents to:
+Instead of inferring behavior from documentation alone, these interfaces allow agents to:
 
-- Run flows and confirm the DOM against the accessibility tree
-- Validate network responses in real-time
-- Discover actual functionality through interactive exploration
-- Verify generated tests against live applications
+- Run browser flows and confirm the DOM against the accessibility tree
+- Validate UI/API network behavior in real-time
+- Query Pact verification matrix results across consumer/provider versions
+- Check provider states and contract compatibility before release
+- Execute `can-i-deploy` checks against target environments
 
 ## How They Work Together
 
 The three components form a quality pipeline:
 
-| Stage        | Component        | Action                                              |
-| ------------ | ---------------- | --------------------------------------------------- |
-| Standards    | Playwright-Utils | Provides production-ready patterns and utilities    |
-| Process      | TEA Workflows    | Enforces systematic test planning and review        |
-| Verification | Playwright MCPs  | Validates generated tests against live applications |
+| Stage        | Component                                  | Action                                                       |
+| ------------ | ------------------------------------------ | ------------------------------------------------------------ |
+| Standards    | Playwright-Utils + pactjs-utils            | Provides production-ready patterns for UI and contract tests |
+| Process      | TEA Workflows                              | Enforces systematic test planning and review                 |
+| Verification | Playwright CLI + Playwright MCP + Pact MCP | Validates tests and contracts against live systems           |
 
 **Before (AI-only):** 20 tests with redundant coverage, incorrect assertions, and flaky behavior.
 
-**After (Full Stack):** Risk-based selection, verified selectors, validated behavior, reviewable code.
+**After (Full Stack):** Risk-based selection, verified selectors, validated behavior, contract compatibility checks, reviewable code.
 
 ## Why This Matters
 
@@ -101,11 +105,11 @@ Traditional AI testing approaches fail because they:
 
 The three-part stack addresses each gap:
 
-| Gap             | Solution                                            |
-| --------------- | --------------------------------------------------- |
-| No standards    | Playwright-Utils provides production-ready patterns |
-| No planning     | TEA `test-design` creates risk-based test plans     |
-| No verification | Playwright MCPs validate against live applications  |
-| No review       | TEA `test-review` audits quality with scoring       |
+| Gap             | Solution                                                                 |
+| --------------- | ------------------------------------------------------------------------ |
+| No standards    | Playwright-Utils + pactjs-utils provide production-ready patterns        |
+| No planning     | TEA `test-design` creates risk-based test plans                          |
+| No verification | Playwright CLI + Playwright MCP + Pact MCP validate against live systems |
+| No review       | TEA `test-review` audits quality with scoring                            |
 
 This approach is sometimes called _context engineering_—loading domain-specific standards into AI context automatically rather than relying on prompts alone. TEA's `tea-index.csv` manifest loads relevant knowledge fragments so the AI doesn't relearn testing patterns each session.

package/docs/how-to/customization/configure-browser-automation.md

@@ -62,7 +62,7 @@ Add these MCP server entries to your tool's configuration file:
 }
 ```
 
-The `smartbear` server is optional — only needed if you use the [Pact MCP integration](/docs/how-to/customization/configure-browser-automation.md#related) for contract testing workflows. See the [pact-mcp knowledge fragment](../../src/testarch/knowledge/pact-mcp.md) for details.
+The `smartbear` server is optional — only needed if you use the [Pact MCP integration](/docs/reference/configuration.md#tea_pact_mcp) for contract testing workflows. See the [pact-mcp knowledge fragment](/docs/reference/knowledge-base.md#pact-contract-testing-integration) for details.
 
 #### Where to put the config
 

package/docs/reference/configuration.md

@@ -141,7 +141,7 @@ Enable Pact.js Utils integration for production-ready contract testing utilities
 
 **Type:** `boolean`
 
-**Default:** `false`
+**Default:** `true`
 
 **Installer Prompt:**
 
@@ -201,7 +201,7 @@ Pact MCP strategy for broker interaction during contract testing workflows.
 
 **Type:** `string`
 
-**Default:** `"none"`
+**Default:** `"mcp"`
 
 **Options:** `"mcp"` | `"none"`
 

package/docs/reference/troubleshooting.md

@@ -593,7 +593,7 @@ If the BMAD installer can run but cannot fetch the Test Architect module from Gi
 
 **Causes**:
 
-- All 40 fragments loading at once
+- Up to 40 fragments loading at once (depends on workflow and enabled integrations)
 - Large fragment file sizes
 - Disk I/O bottleneck
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",

package/release_notes.md

@@ -1,10 +1,13 @@
-## 🚀 What's New in v1.3.0
-
-### ✨ New Features
-- feat: pactjs utils support
+## 🚀 What's New in v1.3.1
 
 ### 📦 Other Changes
-- Merge pull request #41 from bmad-code-org/feat/pactjs-utils-support
+- docs: update pactjs utils
+- addressed review commments
+- Merge pull request #42 from bmad-code-org/docs/update-pactjs-utils
+- Merge pull request #43 from bmad-code-org/chore/refresh-lock
+
+### 🔧 Maintenance
+- chore: refresh lock
 
 
 ## 📦 Installation
@@ -14,4 +17,4 @@ npx bmad-method install
 # Select "Test Architect" from module menu
 ```
 
-**Full Changelog**: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/compare/v1.2.6...v1.3.0
+**Full Changelog**: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/compare/v1.3.0...v1.3.1

package/src/testarch/knowledge/pactjs-utils-consumer-helpers.md

@@ -154,6 +154,7 @@ await provider
 - **Null handling**: `null` becomes `"null"` string in JsonMap (Pact requirement)
 - **Date handling**: Date objects become ISO 8601 strings
 - **No nested objects in JsonMap**: Nested objects are JSON-stringified — provider state handlers must parse them
+- **Array serialization is lossy**: Arrays are converted via `String()` (e.g., `[1,2,3]` → `"1,2,3"`) — prefer passing arrays as JSON-stringified objects for round-trip safety
 - **Message pacts**: Works identically with `MessageConsumerPact` — same `.given()` API
 
 ## Related Fragments

package/src/testarch/knowledge/pactjs-utils-provider-verifier.md

@@ -265,8 +265,8 @@ const opts: VerifierOptions = {
   providerVersionBranch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
   consumerVersionSelectors:
     process.env.PACT_BREAKING_CHANGE === 'true'
-      ? [{ mainBranch: true }, { deployedOrReleased: true }]
-      : [{ mainBranch: true }, { deployedOrReleased: true }, { matchingBranch: true }],
+      ? [{ matchingBranch: true }]
+      : [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }],
   pactUrls: process.env.PACT_PAYLOAD_URL ? [process.env.PACT_PAYLOAD_URL] : undefined,
   stateHandlers: {
     /* ... */

package/src/testarch/knowledge/pactjs-utils-request-filter.md

@@ -198,20 +198,27 @@ const opts: VerifierOptions = {
 ### Right: Separate auth into createRequestFilter
 
 ```typescript
-// ✅ Clean separation
-const requestFilter = createRequestFilter({
-  tokenGenerator: () => fetchAuthToken(),
-});
+// ✅ Clean separation — async setup wraps token fetch (CommonJS-safe)
+async function setupVerifierOptions() {
+  const token = await fetchAuthToken(); // Resolve async token BEFORE creating filter
 
-const opts = buildVerifierOptions({
-  provider: 'my-api',
-  port: '3001',
-  includeMainAndDeployed: true,
-  requestFilter,
-  stateHandlers: {
-    /* ... */
-  },
-});
+  const requestFilter = createRequestFilter({
+    tokenGenerator: () => token, // Synchronous — returns pre-fetched value
+  });
+
+  return buildVerifierOptions({
+    provider: 'my-api',
+    port: '3001',
+    includeMainAndDeployed: true,
+    requestFilter,
+    stateHandlers: {
+      /* ... */
+    },
+  });
+}
+
+// In tests/hooks, callers can await setupVerifierOptions():
+// const opts = await setupVerifierOptions();
 ```
 
 _Source: @seontechnologies/pactjs-utils request-filter module, pact-js-example-provider verification tests_

package/src/workflows/testarch/framework/steps-c/step-03-scaffold-framework.md

@@ -59,7 +59,7 @@ Create the idiomatic test directory for the detected language:
 - **Ruby (RSpec)**: `spec/` with `spec/unit/`, `spec/integration/`, `spec/api/`, `spec/support/`
 - **Rust**: `tests/` for integration tests, inline `#[cfg(test)]` modules for unit tests
 
-**If `tea_use_pactjs_utils` is enabled** (and `{detected_stack}` is `backend` or `fullstack`):
+**If `config.tea_use_pactjs_utils` is enabled** (and `{detected_stack}` is `backend` or `fullstack`):
 
 Create contract testing directory structure:
 
@@ -180,7 +180,7 @@ Create helpers for:
 - Auth helpers
 - Test data factories (language-idiomatic patterns)
 
-**If `tea_use_pactjs_utils` is enabled** (and `{detected_stack}` is `backend` or `fullstack`):
+**If `config.tea_use_pactjs_utils` is enabled** (and `{detected_stack}` is `backend` or `fullstack`):
 
 Create contract test samples in `pact/` directory:
 

package/tools/validate-doc-links.js

@@ -279,7 +279,7 @@ function applyFixes(content, issues) {
     if (issue.status === 'auto-fixable' && issue.suggestedFix) {
       const oldLink = `[${issue.linkText}](${issue.href})`;
       const newLink = `[${issue.linkText}](${issue.suggestedFix})`;
-      updated = updated.replace(oldLink, newLink);
+      updated = updated.replaceAll(oldLink, newLink);
     }
   }
 

package/docs/how-to/customization/enable-tea-mcp-enhancements.md

@@ -1,23 +0,0 @@
----
-title: 'Enable TEA MCP Enhancements (Deprecated)'
-description: This guide has been superseded by Configure Browser Automation
----
-
-# Enable TEA MCP Enhancements
-
-> **Deprecated:** This guide has been replaced by [Configure Browser Automation](/docs/how-to/customization/configure-browser-automation.md).
-
-The `tea_use_mcp_enhancements` boolean flag has been replaced by `tea_browser_automation`, which supports four modes: `auto`, `cli`, `mcp`, and `none`.
-
-**Migration:**
-
-| Old Setting                       | New Equivalent                   |
-| --------------------------------- | -------------------------------- |
-| `tea_use_mcp_enhancements: true`  | `tea_browser_automation: "auto"` |
-| `tea_use_mcp_enhancements: false` | `tea_browser_automation: "none"` |
-
-Please see [Configure Browser Automation](/docs/how-to/customization/configure-browser-automation.md) for full setup instructions.
-
----
-
-Generated with [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)