bmad-method-test-architecture-enterprise 1.1.0 → 1.2.0

package/package.json

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

package/release_notes.md

@@ -1,15 +1,10 @@
-## 🚀 What's New in v1.1.0
+## 🚀 What's New in v1.2.0
 
 ### ✨ New Features
-- feat: prereq prompts part2
-
-### 🐛 Bug Fixes
-- fix: issues 22 23
+- feat:enhance api-request with operation-based overload and update documentation
 
 ### 📦 Other Changes
-- Merge pull request #25 from bmad-code-org/feat/prereq-prompts-part2
-- addressed PR comments
-- Merge pull request #26 from bmad-code-org/fix/issue-22-23
+- Merge pull request #28 from bmad-code-org/feat/knowledge-update-pw-utils-3-14-0
 
 
 ## 📦 Installation
@@ -19,4 +14,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.0.1...v1.1.0
+**Full Changelog**: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/compare/v1.1.0...v1.2.0

package/src/testarch/knowledge/api-request.md

@@ -371,6 +371,95 @@ test.describe('GraphQL API', () => {
 - Check `body.errors` for GraphQL errors (not status code)
 - Works for queries and mutations
 
+### Example 8: Operation-Based Overload (OpenAPI / Code Generators)
+
+**Context**: When using a code generator (orval, openapi-generator, custom scripts) that produces typed operation definitions from an OpenAPI spec, pass the operation object directly to `apiRequest`. This eliminates manual `method`/`path` extraction and `typeof` assertions while preserving full type inference for request body, response, and query parameters. Available since v3.14.0.
+
+**Implementation**:
+
+```typescript
+// Generated operation definition — structural typing, no import from playwright-utils needed
+// type OperationShape = { path: string; method: 'POST'|'GET'|'PUT'|'DELETE'|'PATCH'|'HEAD'; response: unknown; request: unknown; query?: unknown }
+
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// --- Basic usage: operation replaces method + path ---
+test('should upsert person via operation overload', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    operation: upsertPersonv2({ customerId }),
+    headers: getHeaders(customerId),
+    body: personInput, // compile-time typed as Schemas.PersonInput
+  });
+
+  expect(status).toBe(200);
+  expect(body.id).toBeDefined(); // body typed as Schemas.Person
+});
+
+// --- Typed query parameters (replaces string concatenation) ---
+test('should list people with typed query', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getPeoplev2({ customerId }),
+    headers: getHeaders(customerId),
+    query: { page: 0, page_size: 5 }, // typed from operation's query definition
+  });
+
+  expect(body.items).toHaveLength(5);
+});
+
+// --- Params escape hatch (pre-formatted query strings) ---
+test('should fetch billing history with raw params', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getBillingHistoryv2({ customerId }),
+    headers: getHeaders(customerId),
+    params: {
+      'filters[start_date]': getThisMonthTimestamp(),
+      'filters[date_type]': 'MONTH',
+    },
+  });
+
+  expect(body.entries.length).toBeGreaterThan(0);
+});
+
+// --- Works with recurse (polling) ---
+test('should poll until person is reviewed', async ({ apiRequest, recurse }) => {
+  await recurse(
+    async () =>
+      apiRequest({
+        operation: getPersonv2({ customerId, hash }),
+        headers: getHeaders(customerId),
+      }),
+    (res) => {
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('REVIEWED');
+    },
+    { timeout: 30000, interval: 1000 },
+  );
+});
+
+// --- Schema validation chains work identically ---
+test('should create movie with schema validation', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: createMovieOp,
+    headers: commonHeaders(authToken),
+    body: movie,
+  }).validateSchema(CreateMovieResponseSchema, {
+    shape: { status: 200, data: { name: movie.name } },
+  });
+
+  expect(body.data.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Pass `operation` instead of `method` + `path` — mutually exclusive at compile time
+- Response body, request body, and query types inferred from operation definition
+- Uses structural typing (duck typing) — works with any code generator producing `{ path, method, response, request, query? }`
+- `query` field auto-serializes to bracket notation (`filters[type]=pep`, `ids[0]=10`)
+- `params` escape hatch for pre-formatted strings — wins over `query` on conflict
+- Fully composable with `recurse`, `validateSchema`, and all existing features
+- `response`/`request`/`query` on the operation are type-level only — runtime never reads their values
+
 ## Comparison with Vanilla Playwright
 
 | Vanilla Playwright                             | playwright-utils apiRequest                                                        |
@@ -393,6 +482,7 @@ test.describe('GraphQL API', () => {
 - ✅ Tests requiring retry logic
 - ✅ Background API calls in UI tests
 - ✅ Contract testing support
+- ✅ Type-safe API testing with OpenAPI-generated operations (v3.14.0+)
 
 **Stick with vanilla Playwright for:**
 
@@ -440,3 +530,34 @@ const response: any = await apiRequest({ method: 'GET', path: '/users' });
 const { body } = await apiRequest<User[]>({ method: 'GET', path: '/users' });
 // body is typed as User[]
 ```
+
+**❌ Mixing operation overload with explicit generics:**
+
+```typescript
+// Don't pass a generic when using operation — types are inferred from the operation
+const { body } = await apiRequest<MyType>({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+```
+
+**✅ Let the operation infer the types:**
+
+```typescript
+const { body } = await apiRequest({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+// body type inferred from operation.response
+```
+
+**❌ Mixing operation with method/path:**
+
+```typescript
+// Compile error — operation and method/path are mutually exclusive
+await apiRequest({
+  operation: getPersonv2({ customerId }),
+  method: 'GET', // Error: method?: never
+  path: '/api/person', // Error: path?: never
+});
+```

package/src/testarch/knowledge/api-testing-patterns.md

@@ -197,6 +197,7 @@ test.describe('Orders API', () => {
 - `validateSchema` throws if response doesn't match
 - Built-in retry for transient failures
 - Type-safe `body` access
+- **Note**: If your project uses code-generated operations from an OpenAPI spec, see [Example 8](#example-8-operation-based-api-testing-openapi--code-generators) for the preferred `operation`-based overload (v3.14.0+)
 
 ### Example 3: Microservice-to-Microservice Testing
 
@@ -713,6 +714,69 @@ test.describe('Authenticated API Tests', () => {
 - Test auth, expired tokens, and RBAC
 - Pure API testing without UI
 
+### Example 8: Operation-Based API Testing (OpenAPI / Code Generators)
+
+**Context**: When your project uses code-generated operation definitions from an OpenAPI spec, leverage the operation-based overload of `apiRequest` (v3.14.0+) instead of manual `method`/`path` extraction. This eliminates `typeof` assertions and provides full type inference for request body, response, and query parameters.
+
+**Implementation**:
+
+```typescript
+// tests/api/operations.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.describe('API Tests with Generated Operations', () => {
+  test('should create entity with full type safety', async ({ apiRequest }) => {
+    // Operation object from code generator — contains path, method, and type info
+    const { status, body } = await apiRequest({
+      operation: createEntityOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: entityInput, // Compile-time typed from operation.request
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined(); // body typed from operation.response
+  });
+
+  test('should list with typed query parameters', async ({ apiRequest }) => {
+    // query field replaces manual string concatenation
+    const { body } = await apiRequest({
+      operation: listEntitiesOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      query: { page: 0, page_size: 10, status: 'active' },
+    });
+
+    expect(body.items).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+  });
+
+  test('should poll async operation until complete', async ({ apiRequest, recurse }) => {
+    const { body: job } = await apiRequest({
+      operation: startJobOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: { type: 'export' },
+    });
+
+    await recurse(
+      async () =>
+        apiRequest({
+          operation: getJobOp({ workspaceId, jobId: job.id }),
+          headers: getHeaders(workspaceId),
+        }),
+      (res) => res.body.status === 'completed',
+      { timeout: 60000, interval: 2000 },
+    );
+  });
+});
+```
+
+**Key Points**:
+
+- `operation` replaces `method` + `path` — mutually exclusive at compile time
+- Types for body, response, and query all inferred from the operation definition
+- Works with any code generator using structural typing (no imports from playwright-utils needed in generator)
+- Composable with `recurse`, `validateSchema`, and all existing `apiRequest` features
+- Preferred approach over `typeof operation.response` for generated operations
+
 ## API Test Configuration
 
 ### Playwright Config for API-Only Tests

package/src/testarch/knowledge/overview.md

@@ -38,17 +38,17 @@ npm install -D @seontechnologies/playwright-utils
 
 ### Core Testing Utilities
 
-| Utility                    | Purpose                                            | Test Context       |
-| -------------------------- | -------------------------------------------------- | ------------------ |
-| **api-request**            | Typed HTTP client with schema validation and retry | **API/Backend**    |
-| **recurse**                | Polling for async operations, background jobs      | **API/Backend**    |
-| **auth-session**           | Token persistence, multi-user, service-to-service  | **API/Backend/UI** |
-| **log**                    | Playwright report-integrated logging               | **API/Backend/UI** |
-| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation              | **API/Backend/UI** |
-| **burn-in**                | Smart test selection with git diff                 | **CI/CD**          |
-| **network-recorder**       | HAR record/playback for offline testing            | UI only            |
-| **intercept-network-call** | Network spy/stub with auto JSON parsing            | UI only            |
-| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                   | UI only            |
+| Utility                    | Purpose                                                                       | Test Context       |
+| -------------------------- | ----------------------------------------------------------------------------- | ------------------ |
+| **api-request**            | Typed HTTP client with schema validation, retry, and operation-based overload | **API/Backend**    |
+| **recurse**                | Polling for async operations, background jobs                                 | **API/Backend**    |
+| **auth-session**           | Token persistence, multi-user, service-to-service                             | **API/Backend/UI** |
+| **log**                    | Playwright report-integrated logging                                          | **API/Backend/UI** |
+| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                                         | **API/Backend/UI** |
+| **burn-in**                | Smart test selection with git diff                                            | **CI/CD**          |
+| **network-recorder**       | HAR record/playback for offline testing                                       | UI only            |
+| **intercept-network-call** | Network spy/stub with auto JSON parsing                                       | UI only            |
+| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                                              | UI only            |
 
 **Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
 

package/src/testarch/tea-index.csv

@@ -21,7 +21,7 @@ test-healing-patterns,Test Healing Patterns,"Common failure patterns and automat
 selector-resilience,Selector Resilience,"Robust selector strategies and debugging techniques","selectors,locators,debugging,ui",knowledge/selector-resilience.md
 timing-debugging,Timing Debugging,"Race condition identification and deterministic wait fixes","timing,async,debugging",knowledge/timing-debugging.md
 overview,Playwright Utils Overview,"Installation, design principles, fixture patterns for API and UI testing","playwright-utils,fixtures,api,backend,ui",knowledge/overview.md
-api-request,API Request,"Typed HTTP client, schema validation, retry logic for API and service testing","api,backend,service-testing,api-testing,playwright-utils",knowledge/api-request.md
+api-request,API Request,"Typed HTTP client, schema validation, retry logic, operation-based overload for API and service testing","api,backend,service-testing,api-testing,playwright-utils,openapi,codegen,operation",knowledge/api-request.md
 network-recorder,Network Recorder,"HAR record/playback, CRUD detection for offline UI testing","network,playwright-utils,ui,har",knowledge/network-recorder.md
 auth-session,Auth Session,"Token persistence, multi-user, API and browser authentication","auth,playwright-utils,api,backend,jwt,token",knowledge/auth-session.md
 intercept-network-call,Intercept Network Call,"Network spy/stub, JSON parsing for UI tests","network,playwright-utils,ui",knowledge/intercept-network-call.md