docs: expand TEA documentation with cheat sheets, MCP enhancements, a… (bmad-code-org#1289)

* docs: expand TEA documentation with cheat sheets, MCP enhancements, and API testing patterns

* docs: update TEA fragment counts and fix playwright-utils code examples

* docs: addressed PR review concerns

* docs: update TEA MCP configuration link to point to documentation site

Author: muratkeremozcan

docs/explanation/features/tea-overview.md

@@ -12,15 +12,17 @@ agent:
 
   persona:
     role: Master Test Architect
-    identity: Test architect specializing in CI/CD, automated frameworks, and scalable quality gates.
+    identity: Test architect specializing in API testing, backend services, UI automation, CI/CD pipelines, and scalable quality gates. Equally proficient in pure API/service-layer testing as in browser-based E2E testing.
     communication_style: "Blends data with gut instinct. 'Strong opinions, weakly held' is their mantra. Speaks in risk calculations and impact assessments."
     principles: |
       - Risk-based testing - depth scales with impact
       - Quality gates backed by data
-      - Tests mirror usage patterns
+      - Tests mirror usage patterns (API, UI, or both)
       - Flakiness is critical technical debt
       - Tests first AI implements suite validates
       - Calculate risk vs value for every testing decision
+      - Prefer lower test levels (unit > integration > E2E) when possible
+      - API tests are first-class citizens, not just UI support
 
   critical_actions:
     - "Consult {project-root}/_bmad/bmm/testarch/tea-index.csv to select knowledge fragments under knowledge/ and load only the files needed for the current task"
@@ -39,7 +41,7 @@ agent:
 
     - trigger: AT or fuzzy match on atdd
       workflow: "{project-root}/_bmad/bmm/workflows/testarch/atdd/workflow.yaml"
-      description: "[AT] Generate E2E tests first, before starting implementation"
+      description: "[AT] Generate API and/or E2E tests first, before starting implementation"
 
     - trigger: TA or fuzzy match on test-automate
       workflow: "{project-root}/_bmad/bmm/workflows/testarch/automate/workflow.yaml"

src/modules/bmm/agents/tea.agent.yaml

@@ -45,7 +45,7 @@ project_knowledge: # Artifacts from research, document-project output, other lon
   result: "{project-root}/{value}"
 
 tea_use_mcp_enhancements:
-  prompt: "Test Architect Playwright MCP capabilities (healing, exploratory, verification) are optionally available.\nYou will have to setup your MCPs yourself; refer to test-architecture.md for hints.\nWould you like to enable MCP enhancements in Test Architect?"
+  prompt: "Test Architect Playwright MCP capabilities (healing, exploratory, verification) are optionally available.\nYou will have to setup your MCPs yourself; refer to https://docs.bmad-method.org/explanation/features/tea-overview for configuration examples.\nWould you like to enable MCP enhancements in Test Architect?"
   default: false
   result: "{value}"
 

src/modules/bmm/module.yaml

@@ -2,7 +2,7 @@
 
 ## Principle
 
-Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support.
+Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support. **Works without a browser** - ideal for pure API/service testing.
 
 ## Rationale
 
@@ -21,6 +21,7 @@ The `apiRequest` utility provides:
 - **Schema validation**: Single-line validation (JSON Schema, Zod, OpenAPI)
 - **URL resolution**: Four-tier strategy (explicit > config > Playwright > direct)
 - **TypeScript generics**: Type-safe response bodies
+- **No browser required**: Pure API testing without browser overhead
 
 ## Pattern Examples
 
@@ -60,10 +61,11 @@ test('should fetch user data', async ({ apiRequest }) => {
 
 ```typescript
 import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
 
-test('should validate response schema', async ({ apiRequest }) => {
-  // JSON Schema validation
-  const response = await apiRequest({
+// JSON Schema validation
+test('should validate response schema (JSON Schema)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
     method: 'GET',
     path: '/api/users/123',
     validateSchema: {
@@ -77,22 +79,25 @@ test('should validate response schema', async ({ apiRequest }) => {
     },
   });
   // Throws if schema validation fails
+  expect(status).toBe(200);
+});
 
-  // Zod schema validation
-  import { z } from 'zod';
-
-  const UserSchema = z.object({
-    id: z.string(),
-    name: z.string(),
-    email: z.string().email(),
-  });
+// Zod schema validation
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
 
-  const response = await apiRequest({
+test('should validate response schema (Zod)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
     method: 'GET',
     path: '/api/users/123',
     validateSchema: UserSchema,
   });
   // Response body is type-safe AND validated
+  expect(status).toBe(200);
+  expect(body.email).toContain('@');
 });
 ```
 
@@ -236,6 +241,136 @@ test('should poll until job completes', async ({ apiRequest, recurse }) => {
 - `recurse` polls until predicate returns true
 - Composable utilities work together seamlessly
 
+### Example 6: Microservice Testing (Multiple Services)
+
+**Context**: Test interactions between microservices without a browser.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+const USER_SERVICE = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+const ORDER_SERVICE = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+
+test.describe('Microservice Integration', () => {
+  test('should validate cross-service user lookup', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE,
+      body: { name: 'Test User', email: '[email protected]' },
+    });
+
+    // Create order in order-service (validates user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('should reject order for invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+});
+```
+
+**Key Points**:
+
+- Test multiple services without browser
+- Use `baseUrl` to target different services
+- Validate cross-service communication
+- Pure API testing - fast and reliable
+
+### Example 7: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+test.describe('GraphQL API', () => {
+  const GRAPHQL_ENDPOINT = '/graphql';
+
+  test('should query users via GraphQL', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: { name: 'GraphQL User', email: '[email protected]' },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.data.createUser.id).toBeDefined();
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL via POST request
+- Variables in request body
+- Check `body.errors` for GraphQL errors (not status code)
+- Works for queries and mutations
+
 ## Comparison with Vanilla Playwright
 
 | Vanilla Playwright                             | playwright-utils apiRequest                                                        |
@@ -251,11 +386,13 @@ test('should poll until job completes', async ({ apiRequest, recurse }) => {
 
 **Use apiRequest for:**
 
-- ✅ API endpoint testing
-- ✅ Background API calls in UI tests
+- ✅ Pure API/service testing (no browser needed)
+- ✅ Microservice integration testing
+- ✅ GraphQL API testing
 - ✅ Schema validation needs
 - ✅ Tests requiring retry logic
-- ✅ Typed API responses
+- ✅ Background API calls in UI tests
+- ✅ Contract testing support
 
 **Stick with vanilla Playwright for:**
 
@@ -265,11 +402,13 @@ test('should poll until job completes', async ({ apiRequest, recurse }) => {
 
 ## Related Fragments
 
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
 - `overview.md` - Installation and design principles
 - `auth-session.md` - Authentication token management
 - `recurse.md` - Polling for async operations
 - `fixtures-composition.md` - Combining utilities with mergeTests
 - `log.md` - Logging API requests
+- `contract-testing.md` - Pact contract testing
 
 ## Anti-Patterns