docs: addressed review comments

This commit is contained in:
murat 2026-01-13 13:39:12 -06:00
parent 950ea9be2e
commit 638892289a
14 changed files with 78 additions and 71 deletions

View File

@ -21,7 +21,7 @@ Fixture architecture is TEA's pattern for building reusable, testable, and compo
- Composition happens at fixture level
- Reusability maximized
#### Fixture Architecture Flow
### Fixture Architecture Flow
```mermaid
%%{init: {'theme':'base', 'themeVariables': { 'fontSize':'14px'}}}%%
@ -217,11 +217,11 @@ import { test, expect } from '../support/fixtures';
test('should update profile', async ({ apiRequest, authToken, log }) => {
log.info('Starting profile update test');
// Use API request fixture with auth token
// Use API request fixture (matches pure function signature)
const { status, body } = await apiRequest({
method: 'PATCH',
path: '/api/profile',
body: { name: 'New Name' }, // 'body' not 'data'
url: '/api/profile', // Pure function uses 'url' (not 'path')
data: { name: 'New Name' }, // Pure function uses 'data' (not 'body')
headers: { Authorization: `Bearer ${authToken}` }
});
@ -232,6 +232,8 @@ test('should update profile', async ({ apiRequest, authToken, log }) => {
});
```
**Note:** This example uses the vanilla pure function signature (`url`, `data`). Playwright Utils uses different parameter names (`path`, `body`). See [Integrate Playwright Utils](/docs/how-to/customization/integrate-playwright-utils.md) for the utilities API.
**Note:** `authToken` requires auth-session fixture setup with provider configuration. See [auth-session documentation](https://seontechnologies.github.io/playwright-utils/auth-session.html).
**Benefits:**

View File

@ -203,6 +203,7 @@ Benefits it provides
- [Link to related fragment]
```
<!-- markdownlint-disable MD024 -->
### Example: test-quality.md Fragment
```markdown
@ -246,6 +247,7 @@ await page.waitForTimeout(3000);
```
**Total:** 24.5 KB, 12 code examples
<!-- markdownlint-enable MD024 -->
## How TEA Uses the Knowledge Base

View File

@ -324,21 +324,30 @@ await expect(page.locator('.order-confirmation')).toContainText(order.id);
### HAR Recording for Offline Testing
**Vanilla Playwright (Manual HAR Handling):**
```typescript
test('offline testing', async ({ page, context }) => {
// Record mode: Save HAR manually
// First run: Record mode (saves HAR file)
test('offline testing - RECORD', async ({ page, context }) => {
// Record mode: Save network traffic to HAR
await context.routeFromHAR('./hars/dashboard.har', {
url: '**/api/**',
update: true // Update HAR file
});
await page.goto('/dashboard');
// All network traffic saved to dashboard.har
});
// Playback: Load HAR manually
// Subsequent runs: Playback mode (uses saved HAR)
test('offline testing - PLAYBACK', async ({ page, context }) => {
// Playback mode: Use saved network traffic
await context.routeFromHAR('./hars/dashboard.har', {
url: '**/api/**',
update: false // Use existing HAR
update: false // Use existing HAR, no network calls
});
await page.goto('/dashboard');
// Uses recorded responses, no backend needed
});
```

View File

@ -577,7 +577,7 @@ flowchart TD
## Reference
- [TEA Command Reference](/docs/reference/tea/commands.md) - *test-design, *nfr-assess, *trace
- [TEA Command Reference](/docs/reference/tea/commands.md) - `*test-design`, `*nfr-assess`, `*trace`
- [Knowledge Base Index](/docs/reference/tea/knowledge-base.md) - Risk governance fragments
- [Glossary](/docs/reference/glossary/index.md#test-architect-tea-concepts) - Risk-based testing term

View File

@ -53,9 +53,9 @@ test('user can do stuff', async ({ page }) => {
**Result:** PR review comments: "This test is flaky, please fix" → never merged → test deleted → coverage lost
### The Slop Factory
### AI-Generated Tests Without Standards
AI-generated tests without quality standards:
AI-generated tests without quality guardrails:
```typescript
// AI generates 50 tests like this:
@ -74,7 +74,7 @@ test('test2', async ({ page }) => {
// ... 48 more similar tests
```
**Result:** 50 tests, 80% redundant, 90% flaky, 0% trusted by team.
**Result:** 50 tests, 80% redundant, 90% flaky, 0% trusted by team - low-quality outputs that create maintenance burden.
## The Solution: TEA's Quality Standards
@ -524,13 +524,13 @@ flowchart LR
### Score Interpretation
| Score | Interpretation | Action |
|-------|----------------|--------|
| **90-100** | Excellent | Production-ready, minimal changes |
| **80-89** | Good | Minor improvements recommended |
| **70-79** | Acceptable | Address recommendations before release |
| **60-69** | Needs Work | Fix critical issues |
| **< 60** | Critical | Significant refactoring needed |
| Score | Interpretation | Action |
| ---------- | -------------- | -------------------------------------- |
| **90-100** | Excellent | Production-ready, minimal changes |
| **80-89** | Good | Minor improvements recommended |
| **70-79** | Acceptable | Address recommendations before release |
| **60-69** | Needs Work | Fix critical issues |
| **< 60** | Critical | Significant refactoring needed |
## Comparison: Good vs Bad Tests
@ -633,7 +633,7 @@ test('should create user with valid data', async ({ apiRequest }) => {
const { status, body } = await apiRequest({
method: 'POST',
path: '/api/users',
data: { email: testEmail, name: 'Test User' }
body: { email: testEmail, name: 'Test User' }
});
// Explicit assertions
@ -652,7 +652,7 @@ test('should create user with valid data', async ({ apiRequest }) => {
## How TEA Enforces Standards
### During Test Generation (*atdd, *automate)
### During Test Generation (`*atdd`, `*automate`)
TEA generates tests following standards by default:

View File

@ -20,7 +20,7 @@ A production-ready utility library that provides:
- Burn-in testing utilities
- Network error monitoring
**Repository:** https://github.com/seontechnologies/playwright-utils
**Repository:** [https://github.com/seontechnologies/playwright-utils](https://github.com/seontechnologies/playwright-utils)
**npm Package:** `@seontechnologies/playwright-utils`
@ -133,7 +133,7 @@ test('api test', async ({ apiRequest, log }) => {
});
```
### *atdd and *automate Workflows
### `*atdd` and `*automate` Workflows
**Without Playwright Utils:**
```typescript

View File

@ -90,7 +90,9 @@ TEA will ask what test levels to generate:
- E2E tests (browser-based, full user journey)
- API tests (backend only, faster)
- Component tests (UI components in isolation)
- Mix of levels (recommended)
- Mix of levels
**Recommended approach:** Generate API tests first, then E2E tests (see [API Tests First, E2E Later](#api-tests-first-e2e-later) tip below).
### Component Testing by Framework
@ -398,16 +400,18 @@ Run `*test-design` before `*atdd` for better results:
*atdd # Generate tests based on design
```
### Use Recording Mode (Optional)
### Recording Mode Note
If MCP enhancements are enabled (`tea_use_mcp_enhancements: true` in config):
**Recording mode is NOT typically used with ATDD** because ATDD generates tests for features that don't exist yet (no UI to record against).
When prompted during `*atdd`, select "recording mode" to:
- Verify selectors against actual UI with live browser
- Capture network requests in real-time
- Generate accurate locators from actual DOM
If you have a skeleton UI or are refining existing tests, use `*automate` with recording mode instead. See [How to Run Automate](/docs/how-to/workflows/run-automate.md).
See [Enable MCP Enhancements](/docs/how-to/customization/enable-tea-mcp-enhancements.md)
**Recording mode is only applicable for ATDD in the rare case where:**
- You have skeleton/mockup UI already implemented
- You want to verify selector patterns before full implementation
- You're doing "UI-first" development (unusual for TDD)
For most ATDD workflows, **skip recording mode** - TEA will infer selectors from best practices.
### Focus on P0/P1 Scenarios

View File

@ -285,7 +285,7 @@ scenarios: (100.00%) 1 scenario, 500 max VUs, 10m30s max duration
**APM Data:**
- Tool: Datadog
- Dashboard: https://app.datadoghq.com/dashboard/abc123
- Dashboard: <https://app.datadoghq.com/dashboard/abc123>
**Conclusion:** Performance issues identified with mitigation plan. Re-assess after optimization.

View File

@ -9,7 +9,7 @@ Terminology reference for the BMad Method.
| Term | Definition |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agent** | Specialized AI persona with specific expertise (PM, Architect, SM, DEV, TEA) that guides users through workflows and creates deliverables. |
| **BMad** | Breakthrough Method of Agile AI Driven Development — AI-driven agile framework with specialized agents, guided workflows, and scale-adaptive intelligence. |
| **BMad** | Breakthrough Method of Agile AI-Driven Development — AI-driven agile framework with specialized agents, guided workflows, and scale-adaptive intelligence. |
| **BMad Method** | Complete methodology for AI-assisted software development, encompassing planning, architecture, implementation, and quality assurance workflows that adapt to project complexity. |
| **BMM** | BMad Method Module — core orchestration system providing comprehensive lifecycle management through specialized agents and workflows. |
| **Scale-Adaptive System** | Intelligent workflow orchestration that adjusts planning depth and documentation requirements based on project needs through three planning tracks. |

View File

@ -591,16 +591,18 @@ test('should display profile page', async ({ page }) => {
});
```
### Optional: Recording Mode
### Recording Mode Note
If MCP enhancements enabled (`tea_use_mcp_enhancements: true` in config):
**Recording mode is NOT typically used with ATDD** because ATDD generates tests for features that don't exist yet.
When prompted, select "recording mode" to:
- Verify selectors against actual UI with live browser
- Capture network requests in real-time
- Generate accurate locators from actual DOM
Use `*automate` with recording mode for existing features instead. See [`*automate`](#automate).
Note: Recording mode assumes feature partially exists (use for refinement).
**Only use recording mode with ATDD if:**
- You have skeleton/mockup UI implemented
- You want to verify selectors before full implementation
- You're doing UI-first development (rare for TDD)
For typical ATDD (feature doesn't exist), skip recording mode.
### TDD Workflow

View File

@ -60,7 +60,7 @@ Core patterns for test infrastructure and fixture composition.
| [playwright-config](../../../src/modules/bmm/testarch/knowledge/playwright-config.md) | Environment switching, timeout standards, artifact outputs | Configuration, environments, CI |
| [fixtures-composition](../../../src/modules/bmm/testarch/knowledge/fixtures-composition.md) | mergeTests composition patterns for combining utilities | Fixture merging, utility composition |
**Used in:** *framework, *test-design, *atdd, *automate, *test-review
**Used in:** `*framework`, `*test-design`, `*atdd`, `*automate`, `*test-review`
---
@ -74,7 +74,7 @@ Patterns for test data generation, authentication, and setup.
| [email-auth](../../../src/modules/bmm/testarch/knowledge/email-auth.md) | Magic link extraction, state preservation, negative flows | Authentication, email testing |
| [auth-session](../../../src/modules/bmm/testarch/knowledge/auth-session.md) | Token persistence, multi-user, API/browser authentication | Auth patterns, session management |
**Used in:** *framework, *atdd, *automate, *test-review
**Used in:** `*framework`, `*atdd`, `*automate`, `*test-review`
---
@ -89,7 +89,7 @@ Network interception, error handling, and reliability patterns.
| [error-handling](../../../src/modules/bmm/testarch/knowledge/error-handling.md) | Scoped exception handling, retry validation, telemetry logging | Error patterns, resilience |
| [network-error-monitor](../../../src/modules/bmm/testarch/knowledge/network-error-monitor.md) | HTTP 4xx/5xx detection for UI tests | Error detection, monitoring |
**Used in:** *atdd, *automate, *test-review
**Used in:** `*atdd`, `*automate`, `*test-review`
---
@ -103,7 +103,7 @@ CI/CD patterns, burn-in testing, and selective test execution.
| [burn-in](../../../src/modules/bmm/testarch/knowledge/burn-in.md) | Smart test selection, git diff for CI optimization | Test selection, performance |
| [selective-testing](../../../src/modules/bmm/testarch/knowledge/selective-testing.md) | Tag/grep usage, spec filters, diff-based runs | Test filtering, optimization |
**Used in:** *ci, *test-review
**Used in:** `*ci`, `*test-review`
---
@ -119,7 +119,7 @@ Test quality standards, test level selection, and TDD patterns.
| [test-healing-patterns](../../../src/modules/bmm/testarch/knowledge/test-healing-patterns.md) | Common failure patterns and automated fixes | Debugging, healing, fixes |
| [component-tdd](../../../src/modules/bmm/testarch/knowledge/component-tdd.md) | Red→green→refactor workflow, provider isolation | TDD, component testing |
**Used in:** *test-design, *atdd, *automate, *test-review, *trace
**Used in:** `*test-design`, `*atdd`, `*automate`, `*test-review`, `*trace`
---
@ -133,7 +133,7 @@ Risk assessment, governance, and gate decision frameworks.
| [probability-impact](../../../src/modules/bmm/testarch/knowledge/probability-impact.md) | Probability × impact scale for scoring matrix | Risk scoring, impact analysis |
| [nfr-criteria](../../../src/modules/bmm/testarch/knowledge/nfr-criteria.md) | Security, performance, reliability, maintainability status | NFRs, compliance, enterprise |
**Used in:** *test-design, *nfr-assess, *trace
**Used in:** `*test-design`, `*nfr-assess`, `*trace`
---
@ -147,7 +147,7 @@ Selector resilience, race condition debugging, and visual debugging.
| [timing-debugging](../../../src/modules/bmm/testarch/knowledge/timing-debugging.md) | Race condition identification and deterministic fixes | Race conditions, timing issues |
| [visual-debugging](../../../src/modules/bmm/testarch/knowledge/visual-debugging.md) | Trace viewer usage, artifact expectations | Debugging, trace viewer, artifacts |
**Used in:** *atdd, *automate, *test-review
**Used in:** `*atdd`, `*automate`, `*test-review`
---
@ -161,7 +161,7 @@ Feature flag testing, contract testing, and API testing patterns.
| [contract-testing](../../../src/modules/bmm/testarch/knowledge/contract-testing.md) | Pact publishing, provider verification, resilience | Contract testing, Pact |
| [api-testing-patterns](../../../src/modules/bmm/testarch/knowledge/api-testing-patterns.md) | Pure API patterns without browser | API testing, backend testing |
**Used in:** *test-design, *atdd, *automate
**Used in:** `*test-design`, `*atdd`, `*automate`
---
@ -185,9 +185,9 @@ Patterns for using `@seontechnologies/playwright-utils` package (11 utilities).
**Note:** All 11 playwright-utils fragments are in the same `knowledge/` directory as other fragments.
**Used in:** *framework (if `tea_use_playwright_utils: true`), *atdd, *automate, *test-review, *ci
**Used in:** `*framework` (if `tea_use_playwright_utils: true`), `*atdd`, `*automate`, `*test-review`, `*ci`
**Official Docs:** https://seontechnologies.github.io/playwright-utils/
**Official Docs:** <https://seontechnologies.github.io/playwright-utils/>
---

View File

@ -18,7 +18,7 @@ By the end of this 30-minute tutorial, you'll have:
- Node.js installed (v18 or later)
- 30 minutes of focused time
- We'll use TodoMVC (https://todomvc.com/examples/react/) as our demo app
- We'll use TodoMVC (<https://todomvc.com/examples/react/>) as our demo app
## TEA Approaches Explained
@ -36,7 +36,7 @@ This tutorial focuses on **TEA Lite** - the fastest way to see TEA in action.
We'll test TodoMVC, a standard demo app used across testing documentation.
**Demo App:** https://todomvc.com/examples/react/
**Demo App:** <https://todomvc.com/examples/react/>
No installation needed - TodoMVC runs in your browser. Open the link above and:
1. Add a few todos (type and press Enter)
@ -173,7 +173,7 @@ In your chat with TEA, run:
```
**Q: What are you testing?**
A: "TodoMVC React app at https://todomvc.com/examples/react/ - focus on the test design we just created"
A: "TodoMVC React app at <https://todomvc.com/examples/react/> - focus on the test design we just created"
**Q: Reference existing docs?**
A: "Yes, use test-design-epic-1.md"
@ -452,8 +452,8 @@ use: {
### Need Help?
- **Documentation:** https://docs.bmad-method.org
- **GitHub Issues:** https://github.com/bmad-code-org/bmad-method/issues
- **Documentation:** <https://docs.bmad-method.org>
- **GitHub Issues:** <https://github.com/bmad-code-org/bmad-method/issues>
- **Discord:** Join the BMAD community
---

13
package-lock.json generated
View File

@ -244,7 +244,6 @@
"integrity": "sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==",
"dev": true,
"license": "MIT",
"peer": true,
"dependencies": {
"@babel/code-frame": "^7.27.1",
"@babel/generator": "^7.28.5",
@ -3643,7 +3642,6 @@
"integrity": "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA==",
"devOptional": true,
"license": "MIT",
"peer": true,
"dependencies": {
"undici-types": "~7.16.0"
}
@ -3983,7 +3981,6 @@
"integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
"dev": true,
"license": "MIT",
"peer": true,
"bin": {
"acorn": "bin/acorn"
},
@ -4290,7 +4287,6 @@
"integrity": "sha512-6mF/YrvwwRxLTu+aMEa5pwzKUNl5ZetWbTyZCs9Um0F12HUmxUiF5UHiZPy4rifzU3gtpM3xP2DfdmkNX9eZRg==",
"dev": true,
"license": "MIT",
"peer": true,
"dependencies": {
"@astrojs/compiler": "^2.13.0",
"@astrojs/internal-helpers": "0.7.5",
@ -5358,7 +5354,6 @@
}
],
"license": "MIT",
"peer": true,
"dependencies": {
"baseline-browser-mapping": "^2.9.0",
"caniuse-lite": "^1.0.30001759",
@ -6689,7 +6684,6 @@
"integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==",
"dev": true,
"license": "MIT",
"peer": true,
"dependencies": {
"@eslint-community/eslint-utils": "^4.8.0",
"@eslint-community/regexpp": "^4.12.1",
@ -10304,7 +10298,6 @@
"integrity": "sha512-p3JTemJJbkiMjXEMiFwgm0v6ym5g8K+b2oDny+6xdl300tUKySxvilJQLSea48C6OaYNmO30kH9KxpiAg5bWJw==",
"dev": true,
"license": "MIT",
"peer": true,
"dependencies": {
"globby": "15.0.0",
"js-yaml": "4.1.1",
@ -12378,7 +12371,6 @@
}
],
"license": "MIT",
"peer": true,
"dependencies": {
"nanoid": "^3.3.11",
"picocolors": "^1.1.1",
@ -12444,7 +12436,6 @@
"integrity": "sha512-v6UNi1+3hSlVvv8fSaoUbggEM5VErKmmpGA7Pl3HF8V6uKY7rvClBOJlH6yNwQtfTueNkGVpOv/mtWL9L4bgRA==",
"dev": true,
"license": "MIT",
"peer": true,
"bin": {
"prettier": "bin/prettier.cjs"
},
@ -13273,7 +13264,6 @@
"integrity": "sha512-3nk8Y3a9Ea8szgKhinMlGMhGMw89mqule3KWczxhIzqudyHdCIOHw8WJlj/r329fACjKLEh13ZSk7oE22kyeIw==",
"dev": true,
"license": "MIT",
"peer": true,
"dependencies": {
"@types/estree": "1.0.8"
},
@ -14837,7 +14827,6 @@
"integrity": "sha512-+Oxm7q9hDoLMyJOYfUYBuHQo+dkAloi33apOPP56pzj+vsdJDzr+j1NISE5pyaAuKL4A3UD34qd0lx5+kfKp2g==",
"dev": true,
"license": "MIT",
"peer": true,
"dependencies": {
"esbuild": "^0.25.0",
"fdir": "^6.4.4",
@ -15111,7 +15100,6 @@
"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz",
"integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==",
"license": "ISC",
"peer": true,
"bin": {
"yaml": "bin.mjs"
},
@ -15303,7 +15291,6 @@
"integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
"dev": true,
"license": "MIT",
"peer": true,
"funding": {
"url": "https://github.com/sponsors/colinhacks"
}

View File

@ -34,6 +34,7 @@
"flatten": "node tools/flattener/main.js",
"format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
"format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
"format:fix:staged": "prettier --write",
"install:bmad": "node tools/cli/bmad-cli.js install",
"lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
"lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
@ -53,14 +54,14 @@
"lint-staged": {
"*.{js,cjs,mjs}": [
"npm run lint:fix",
"npm run format:fix"
"npm run format:fix:staged"
],
"*.yaml": [
"eslint --fix",
"npm run format:fix"
"npm run format:fix:staged"
],
"*.json": [
"npm run format:fix"
"npm run format:fix:staged"
],
"*.md": [
"markdownlint-cli2"