BMAD-METHOD/docs/tea/reference/configuration.md

title, description

title	description
TEA Configuration Reference	Complete reference for TEA configuration options and file locations

TEA Configuration Reference

Complete reference for all TEA (Test Architect) configuration options.

Configuration File Locations

User Configuration (Installer-Generated)

Location: _bmad/bmm/config.yaml

Purpose: Project-specific configuration values for your repository

Created By: BMad installer

Status: Typically gitignored (user-specific values)

Usage: Edit this file to change TEA behavior in your project

Example:

# _bmad/bmm/config.yaml
project_name: my-awesome-app
user_skill_level: intermediate
output_folder: _bmad-output
tea_use_playwright_utils: true
tea_use_mcp_enhancements: false

Canonical Schema (Source of Truth)

Location: src/bmm/module.yaml

Purpose: Defines available configuration keys, defaults, and installer prompts

Created By: BMAD maintainers (part of BMAD repo)

Status: Versioned in BMAD repository

Usage: Reference only (do not edit unless contributing to BMAD)

Note: The installer reads module.yaml to prompt for config values, then writes user choices to _bmad/bmm/config.yaml in your project.

---

TEA Configuration Options

tea_use_playwright_utils

Enable Playwright Utils integration for production-ready fixtures and utilities.

Schema Location: src/bmm/module.yaml:52-56

User Config: _bmad/bmm/config.yaml

Type: boolean

Default: false (set via installer prompt during installation)

Installer Prompt:

Are you using playwright-utils (@seontechnologies/playwright-utils) in your project?
You must install packages yourself, or use test architect's `framework` command.

Purpose: Enables TEA to:

• Include playwright-utils in framework scaffold
• Generate tests using playwright-utils fixtures
• Review tests against playwright-utils patterns
• Configure CI with burn-in and selective testing utilities

Affects Workflows:

• framework - Includes playwright-utils imports and fixture examples
• atdd - Uses fixtures like apiRequest, authSession in generated tests
• automate - Leverages utilities for test patterns
• test-review - Reviews against playwright-utils best practices
• ci - Includes burn-in utility and selective testing

Example (Enable):

tea_use_playwright_utils: true

Example (Disable):

tea_use_playwright_utils: false

Prerequisites:

npm install -D @seontechnologies/playwright-utils

Related:

• Integrate Playwright Utils Guide
• Playwright Utils on npm

---

tea_use_mcp_enhancements

Enable Playwright MCP servers for live browser verification during test generation.

Schema Location: src/bmm/module.yaml:47-50

User Config: _bmad/bmm/config.yaml

Type: boolean

Default: false

Installer Prompt:

Test Architect Playwright MCP capabilities (healing, exploratory, verification) are optionally available.
You will have to setup your MCPs yourself; refer to https://docs.bmad-method.org/explanation/features/tea-overview for configuration examples.
Would you like to enable MCP enhancements in Test Architect?

Purpose: Enables TEA to use Model Context Protocol servers for:

• Live browser automation during test design
• Selector verification with actual DOM
• Interactive UI discovery
• Visual debugging and healing

Affects Workflows:

• test-design - Enables exploratory mode (browser-based UI discovery)
• atdd - Enables recording mode (verify selectors with live browser)
• automate - Enables healing mode (fix tests with visual debugging)

MCP Servers Required:

Two Playwright MCP servers (actively maintained, continuously updated):

• playwright - Browser automation (npx @playwright/mcp@latest)
• playwright-test - Test runner with failure analysis (npx playwright run-test-mcp-server)

Configuration example:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "playwright-test": {
      "command": "npx",
      "args": ["playwright", "run-test-mcp-server"]
    }
  }
}

Configuration: Refer to your AI agent's documentation for MCP server setup instructions.

Example (Enable):

tea_use_mcp_enhancements: true

Example (Disable):

tea_use_mcp_enhancements: false

Prerequisites:

1. MCP servers installed in IDE configuration
2. @playwright/mcp package available globally or locally
3. Browser binaries installed (npx playwright install)

Related:

• Enable MCP Enhancements Guide
• TEA Overview - MCP Section
• Playwright MCP on npm

---

Core BMM Configuration (Inherited by TEA)

TEA also uses core BMM configuration options from _bmad/bmm/config.yaml:

output_folder

Type: string

Default: _bmad-output

Purpose: Where TEA writes output files (test designs, reports, traceability matrices)

Example:

output_folder: _bmad-output

TEA Output Files:

• test-design-architecture.md + test-design-qa.md (from test-design system-level - TWO documents)
• test-design-epic-N.md (from test-design epic-level)
• test-review.md (from test-review)
• traceability-matrix.md (from trace Phase 1)
• gate-decision-{gate_type}-{story_id}.md (from trace Phase 2)
• nfr-assessment.md (from nfr-assess)
• automation-summary.md (from automate)
• atdd-checklist-{story_id}.md (from atdd)

---

user_skill_level

Type: enum

Options: beginner | intermediate | expert

Default: intermediate

Purpose: Affects how TEA explains concepts in chat responses

Example:

user_skill_level: beginner

Impact on TEA:

• Beginner: More detailed explanations, links to concepts, verbose guidance
• Intermediate: Balanced explanations, assumes basic knowledge
• Expert: Concise, technical, minimal hand-holding

---

project_name

Type: string

Default: Directory name

Purpose: Used in TEA-generated documentation and reports

Example:

project_name: my-awesome-app

Used in:

• Report headers
• Documentation titles
• CI configuration comments

---

communication_language

Type: string

Default: english

Purpose: Language for TEA chat responses

Example:

communication_language: english

Supported: Any language (TEA responds in specified language)

---

document_output_language

Type: string

Default: english

Purpose: Language for TEA-generated documents (test designs, reports)

Example:

document_output_language: english

Note: Can differ from communication_language - chat in Spanish, generate docs in English.

---

Environment Variables

TEA workflows may use environment variables for test configuration.

Test Framework Variables

Playwright:

# .env
BASE_URL=https://todomvc.com/examples/react/dist/
API_BASE_URL=https://api.example.com
TEST_USER_EMAIL=test@example.com
TEST_USER_PASSWORD=password123

Cypress:

# cypress.env.json or .env
CYPRESS_BASE_URL=https://example.com
CYPRESS_API_URL=https://api.example.com

CI/CD Variables

Set in CI platform (GitHub Actions secrets, GitLab CI variables):

# .github/workflows/test.yml
env:
  BASE_URL: ${{ secrets.STAGING_URL }}
  API_KEY: ${{ secrets.API_KEY }}
  TEST_USER_EMAIL: ${{ secrets.TEST_USER }}

---

Configuration Patterns

Development vs Production

Separate configs for environments:

# _bmad/bmm/config.yaml
output_folder: _bmad-output

# .env.development
BASE_URL=http://localhost:3000
API_BASE_URL=http://localhost:4000

# .env.staging
BASE_URL=https://staging.example.com
API_BASE_URL=https://api-staging.example.com

# .env.production (read-only tests only!)
BASE_URL=https://example.com
API_BASE_URL=https://api.example.com

Team vs Individual

Team config (committed):

# _bmad/bmm/config.yaml.example (committed to repo)
project_name: team-project
output_folder: _bmad-output
tea_use_playwright_utils: true
tea_use_mcp_enhancements: false

Individual config (typically gitignored):

# _bmad/bmm/config.yaml (user adds to .gitignore)
user_name: John Doe
user_skill_level: expert
tea_use_mcp_enhancements: true  # Individual preference

Monorepo Configuration

Root config:

# _bmad/bmm/config.yaml (root)
project_name: monorepo-parent
output_folder: _bmad-output

Package-specific:

# packages/web-app/_bmad/bmm/config.yaml
project_name: web-app
output_folder: ../../_bmad-output/web-app
tea_use_playwright_utils: true

# packages/mobile-app/_bmad/bmm/config.yaml
project_name: mobile-app
output_folder: ../../_bmad-output/mobile-app
tea_use_playwright_utils: false

---

Configuration Best Practices

1. Use Version Control Wisely

Commit:

_bmad/bmm/config.yaml.example    # Template for team
.nvmrc                            # Node version
package.json                      # Dependencies

Recommended for .gitignore:

_bmad/bmm/config.yaml            # User-specific values
.env                              # Secrets
.env.local                        # Local overrides

2. Document Required Setup

In your README:

## Setup

1. Install BMad

2. Copy config template:
   cp _bmad/bmm/config.yaml.example _bmad/bmm/config.yaml

3. Edit config with your values:
   - Set user_name
   - Enable tea_use_playwright_utils if using playwright-utils
   - Enable tea_use_mcp_enhancements if MCPs configured

3. Validate Configuration

Check config is valid:

# Check TEA config is set
cat _bmad/bmm/config.yaml | grep tea_use

# Verify playwright-utils installed (if enabled)
npm list @seontechnologies/playwright-utils

# Verify MCP servers configured (if enabled)
# Check your IDE's MCP settings

4. Keep Config Minimal

Don't over-configure:

# ❌ Bad - overriding everything unnecessarily
project_name: my-project
user_name: John Doe
user_skill_level: expert
output_folder: custom/path
planning_artifacts: custom/planning
implementation_artifacts: custom/implementation
project_knowledge: custom/docs
tea_use_playwright_utils: true
tea_use_mcp_enhancements: true
communication_language: english
document_output_language: english
# Overriding 11 config options when most can use defaults

# ✅ Good - only essential overrides
tea_use_playwright_utils: true
output_folder: docs/testing
# Only override what differs from defaults

Use defaults when possible - only override what you actually need to change.

---

Troubleshooting

Configuration Not Loaded

Problem: TEA doesn't use my config values.

Causes:

1. Config file in wrong location
2. YAML syntax error
3. Typo in config key

Solution:

# Check file exists
ls -la _bmad/bmm/config.yaml

# Validate YAML syntax
npm install -g js-yaml
js-yaml _bmad/bmm/config.yaml

# Check for typos (compare to module.yaml)
diff _bmad/bmm/config.yaml src/bmm/module.yaml

Playwright Utils Not Working

Problem: tea_use_playwright_utils: true but TEA doesn't use utilities.

Causes:

1. Package not installed
2. Config file not saved
3. Workflow run before config update

Solution:

# Verify package installed
npm list @seontechnologies/playwright-utils

# Check config value
grep tea_use_playwright_utils _bmad/bmm/config.yaml

# Re-run workflow in fresh chat
# (TEA loads config at workflow start)

MCP Enhancements Not Working

Problem: tea_use_mcp_enhancements: true but no browser opens.

Causes:

1. MCP servers not configured in IDE
2. MCP package not installed
3. Browser binaries missing

Solution:

# Check MCP package available
npx @playwright/mcp@latest --version

# Install browsers
npx playwright install

# Verify IDE MCP config
# Check ~/.cursor/config.json or VS Code settings

Config Changes Not Applied

Problem: Updated config but TEA still uses old values.

Cause: TEA loads config at workflow start.

Solution:

1. Save _bmad/bmm/config.yaml
2. Start fresh chat
3. Run TEA workflow
4. Config will be reloaded

TEA doesn't reload config mid-chat - always start fresh chat after config changes.

---

Configuration Examples

Recommended Setup (Full Stack)

# _bmad/bmm/config.yaml
project_name: my-project
user_skill_level: beginner  # or intermediate/expert
output_folder: _bmad-output
tea_use_playwright_utils: true   # Recommended
tea_use_mcp_enhancements: true   # Recommended

Why recommended:

• Playwright Utils: Production-ready fixtures and utilities
• MCP enhancements: Live browser verification, visual debugging
• Together: The three-part stack (see Testing as Engineering)

Prerequisites:

npm install -D @seontechnologies/playwright-utils
# Configure MCP servers in IDE (see Enable MCP Enhancements guide)

Best for: Everyone (beginners learn good patterns from day one)

---

Minimal Setup (Learning Only)

# _bmad/bmm/config.yaml
project_name: my-project
output_folder: _bmad-output
tea_use_playwright_utils: false
tea_use_mcp_enhancements: false

Best for:

• First-time TEA users (keep it simple initially)
• Quick experiments
• Learning basics before adding integrations

Note: Can enable integrations later as you learn

---

Monorepo Setup

Root config:

# _bmad/bmm/config.yaml (root)
project_name: monorepo
output_folder: _bmad-output
tea_use_playwright_utils: true

Package configs:

# apps/web/_bmad/bmm/config.yaml
project_name: web-app
output_folder: ../../_bmad-output/web

# apps/api/_bmad/bmm/config.yaml
project_name: api-service
output_folder: ../../_bmad-output/api
tea_use_playwright_utils: false  # Using vanilla Playwright only

---

Team Template

Commit this template:

# _bmad/bmm/config.yaml.example
# Copy to config.yaml and fill in your values

project_name: your-project-name
user_name: Your Name
user_skill_level: intermediate  # beginner | intermediate | expert
output_folder: _bmad-output
planning_artifacts: _bmad-output/planning-artifacts
implementation_artifacts: _bmad-output/implementation-artifacts
project_knowledge: docs

# TEA Configuration (Recommended: Enable both for full stack)
tea_use_playwright_utils: true   # Recommended - production-ready utilities
tea_use_mcp_enhancements: true   # Recommended - live browser verification

# Languages
communication_language: english
document_output_language: english

Team instructions:

## Setup for New Team Members

1. Clone repo
2. Copy config template:
   cp _bmad/bmm/config.yaml.example _bmad/bmm/config.yaml
3. Edit with your name and preferences
4. Install dependencies:
   npm install
5. (Optional) Enable playwright-utils:
   npm install -D @seontechnologies/playwright-utils
   Set tea_use_playwright_utils: true

---

See Also

How-To Guides

• Set Up Test Framework
• Integrate Playwright Utils
• Enable MCP Enhancements

Reference

• TEA Command Reference
• Knowledge Base Index
• Glossary

Explanation

• TEA Overview
• Testing as Engineering

---

Generated with BMad Method - TEA (Test Architect)