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

title, description

title	description
Enable TEA MCP Enhancements	Configure Playwright MCP servers for live browser verification during TEA workflows

Enable TEA MCP Enhancements

Configure Model Context Protocol (MCP) servers to enable live browser verification, exploratory mode, and recording mode in TEA workflows.

What are MCP Enhancements?

MCP (Model Context Protocol) servers enable AI agents to interact with live browsers during test generation. This allows TEA to:

• Explore UIs interactively - Discover actual functionality through browser automation
• Verify selectors - Generate accurate locators from real DOM
• Validate behavior - Confirm test scenarios against live applications
• Debug visually - Use trace viewer and screenshots during generation

When to Use This

For UI Testing:

• Want exploratory mode in *test-design (browser-based UI discovery)
• Want recording mode in *atdd or *automate (verify selectors with live browser)
• Want healing mode in *automate (fix tests with visual debugging)
• Need accurate selectors from actual DOM
• Debugging complex UI interactions

For API Testing:

• Want healing mode in *automate (analyze failures with trace data)
• Need to debug test failures (network responses, request/response data, timing)
• Want to inspect trace files (network traffic, errors, race conditions)

For Both:

• Visual debugging (trace viewer shows network + UI)
• Test failure analysis (MCP can run tests and extract errors)
• Understanding complex test failures (network + DOM together)

Don't use if:

• You don't have MCP servers configured

Prerequisites

• BMad Method installed
• TEA agent available
• IDE with MCP support (Cursor, VS Code with Claude extension)
• Node.js v18 or later
• Playwright installed

Available MCP Servers

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

1. Playwright MCP - Browser Automation

Command: npx @playwright/mcp@latest

Capabilities:

• Navigate to URLs
• Click elements
• Fill forms
• Take screenshots
• Extract DOM information

Best for: Exploratory mode, recording mode

2. Playwright Test MCP - Test Runner

Command: npx playwright run-test-mcp-server

Capabilities:

• Run test files
• Analyze failures
• Extract error messages
• Show trace files

Best for: Healing mode, debugging

Recommended: Configure Both

Both servers work together to provide full TEA MCP capabilities.

Setup

1. Configure MCP Servers

Add to your IDE's MCP configuration:

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

See TEA Overview for IDE-specific config locations.

2. Enable in BMAD

Answer "Yes" when prompted during installation, or set in config:

# _bmad/bmm/config.yaml
tea_use_mcp_enhancements: true

3. Verify MCPs Running

Ensure your MCP servers are running in your IDE.

How MCP Enhances TEA Workflows

*test-design: Exploratory Mode

Without MCP:

• TEA infers UI functionality from documentation
• Relies on your description of features
• May miss actual UI behavior

With MCP: TEA can open live browser to:

"Let me explore the profile page to understand the UI"

[TEA navigates to /profile]
[Takes screenshot]
[Extracts accessible elements]

"I see the profile has:
- Name field (editable)
- Email field (editable)
- Avatar upload button
- Save button
- Cancel button

I'll design tests for these interactions."

Benefits:

• Accurate test design based on actual UI
• Discovers functionality you might not describe
• Validates test scenarios are possible

*atdd: Recording Mode

Without MCP:

• TEA generates selectors from best practices
• TEA infers API patterns from documentation

With MCP (Recording Mode):

For UI Tests:

[TEA navigates to /login with live browser]
[Inspects actual form fields]

"I see:
- Email input has label 'Email Address' (not 'Email')
- Password input has label 'Your Password'
- Submit button has text 'Sign In' (not 'Login')

I'll use these exact selectors."

For API Tests:

[TEA analyzes trace files from test runs]
[Inspects network requests/responses]

"I see the API returns:
- POST /api/login → 200 with { token, userId }
- Response time: 150ms
- Required headers: Content-Type, Authorization

I'll validate these in tests."

Benefits:

• UI: Accurate selectors from real DOM
• API: Validated request/response patterns from trace
• Both: Tests work on first run

*automate: Healing + Recording Modes

Without MCP:

• TEA analyzes test code only
• Suggests fixes based on static analysis
• Generates tests from documentation/code

With MCP:

Healing Mode (UI + API):

[TEA opens trace file]
[Analyzes screenshots + network tab]

UI failures: "Button selector changed from 'Save' to 'Save Changes'"
API failures: "Response structure changed, expected {id} got {userId}"

[TEA makes fixes]
[Verifies with trace analysis]

Recording Mode (UI + API):

UI: [Inspects actual DOM, generates verified selectors]
API: [Analyzes network traffic, validates request/response patterns]

[Generates tests with verified patterns]
[Tests work on first run]

Benefits:

• Visual debugging + trace analysis (not just UI)
• Verified selectors (UI) + network patterns (API)
• Tests verified against actual application behavior

Usage Examples

Exploratory Mode Example

User: Run *test-design

TEA: What feature are you designing tests for?

User: The checkout flow at https://shop.example.com

TEA: [With MCP] Let me explore the checkout flow
[Opens browser]
[Navigates to checkout]
[Takes screenshots]
[Identifies all interactive elements]

TEA: I've explored the checkout flow. I found:
- 4-step wizard (Cart → Shipping → Payment → Confirm)
- Shipping options (Standard, Express, Overnight)
- Payment methods (Credit Card, PayPal)
- Promo code field
- Order summary with real-time totals

Test design will cover all these scenarios.

Recording Mode Example

User: Run *atdd for user registration feature

TEA: [With MCP] Let me verify the registration form selectors
[Opens browser at /register]
[Inspects form]

TEA: I see the actual form has:
- "Full Name" label (not "Name")
- "Email Address" label (not "Email")
- "Create Password" label (not "Password")
- "I agree to Terms" checkbox
- "Create Account" button (not "Register")

Generating tests with verified selectors...

Healing Mode Example

User: Run *automate with healing mode

TEA: [With MCP] Running tests and checking for failures
[Runs test suite]
[Test fails: selector not found]

TEA: Test failed on selector '.submit-btn'
[Opens trace viewer]
[Sees button class changed to '.submit-button']

Fixing selector and verifying...
[Updates test]
[Re-runs with MCP]
[Test passes]

Updated test with corrected selector.

Troubleshooting

MCP Servers Not Running

Problem: TEA says MCP enhancements aren't available.

Causes:

1. MCP servers not configured in IDE
2. Config syntax error in JSON
3. IDE not restarted after config

Solution:

# Verify MCP config file exists
ls ~/.cursor/config.json

# Validate JSON syntax
cat ~/.cursor/config.json | python -m json.tool

# Restart IDE
# Cmd+Q (quit) then reopen

Browser Doesn't Open

Problem: MCP enabled but browser never opens.

Causes:

1. Playwright browsers not installed
2. Headless mode enabled
3. MCP server crashed

Solution:

# Install browsers
npx playwright install

# Check MCP server logs (in IDE)
# Look for error messages

# Try manual MCP server
npx @playwright/mcp@latest
# Should start without errors

TEA Doesn't Use MCP

Problem: tea_use_mcp_enhancements: true but TEA doesn't use browser.

Causes:

1. Config not saved
2. Workflow run before config update
3. MCP servers not running

Solution:

# Verify config
grep tea_use_mcp_enhancements _bmad/bmm/config.yaml
# Should show: tea_use_mcp_enhancements: true

# Restart IDE (reload MCP servers)

# Start fresh chat (TEA loads config at start)

Selector Verification Fails

Problem: MCP can't find elements TEA is looking for.

Causes:

1. Page not fully loaded
2. Element behind modal/overlay
3. Element requires authentication

Solution: TEA will handle this automatically:

• Wait for page load
• Dismiss modals if present
• Handle auth if needed

If persistent, provide TEA more context:

"The element is behind a modal - dismiss the modal first"
"The page requires login - use credentials X"

MCP Slows Down Workflows

Problem: Workflows take much longer with MCP enabled.

Cause: Browser automation adds overhead.

Solution: Use MCP selectively:

• Enable for: Complex UIs, new projects, debugging
• Disable for: Simple features, well-known patterns, API-only testing

Toggle quickly:

# For this feature (complex UI)
tea_use_mcp_enhancements: true

# For next feature (simple API)
tea_use_mcp_enhancements: false

Related Guides

Getting Started:

• TEA Lite Quickstart Tutorial - Learn TEA basics first

Workflow Guides (MCP-Enhanced):

• How to Run Test Design - Exploratory mode with browser
• How to Run ATDD - Recording mode for accurate selectors
• How to Run Automate - Healing mode for debugging

Other Customization:

• Integrate Playwright Utils - Production-ready utilities

Understanding the Concepts

• TEA Overview - MCP enhancements in lifecycle
• Engagement Models - When to use MCP enhancements

Reference

• TEA Configuration - tea_use_mcp_enhancements option
• TEA Command Reference - MCP-enhanced workflows
• Glossary - MCP Enhancements term

---

Generated with BMad Method - TEA (Test Architect)