13 KiB

Raw Blame History

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

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

Don't use if:

You're new to TEA (adds complexity)
You don't have MCP servers configured
Your tests work fine without it
You're testing APIs only (no UI)

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.

Installation

Step 1: Configure MCP Servers in IDE

Add this configuration to your IDE's MCP settings. See TEA Overview for IDE-specific configuration locations.

MCP Configuration:

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

Step 2: Install Playwright Browsers

npx playwright install

Step 3: Enable in TEA Config

Edit _bmad/bmm/config.yaml:

tea_use_mcp_enhancements: true

Step 4: Restart IDE

Restart your IDE to load MCP server configuration.

Step 5: Verify MCP Servers

Check MCP servers are running:

In Cursor:

Open command palette (Cmd/Ctrl + Shift + P)
Search "MCP"
Should see "Playwright" and "Playwright Test" servers listed

In VS Code:

Check Claude extension settings
Verify MCP servers are enabled

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
May use getByRole() that doesn't match actual app
Selectors might need adjustment

With MCP: TEA verifies selectors with live browser:

"Let me verify the login form selectors"

[TEA navigates to /login]
[Inspects 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."

Generated test:

await page.getByLabel('Email Address').fill('test@example.com');
await page.getByLabel('Your Password').fill('password');
await page.getByRole('button', { name: 'Sign In' }).click();
// Selectors verified against actual DOM

Benefits:

Accurate selectors from real DOM
Tests work on first run
No trial-and-error selector debugging

*automate: Healing Mode

Without MCP:

TEA analyzes test code only
Suggests fixes based on static analysis
Can't verify fixes work

With MCP: TEA uses visual debugging:

"This test is failing. Let me debug with trace viewer"

[TEA opens trace file]
[Analyzes screenshots]
[Identifies selector changed]

"The button selector changed from 'Save' to 'Save Changes'
I'll update the test and verify it works"

[TEA makes fix]
[Runs test with MCP]
[Confirms test passes]

Benefits:

Visual debugging during healing
Verified fixes (not guesses)
Faster resolution

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.

Configuration Options

MCP Server Arguments

Playwright MCP with custom port:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--port", "3000"]
    }
  }
}

Playwright Test with specific browser:

{
  "mcpServers": {
    "playwright-test": {
      "command": "npx",
      "args": ["playwright", "run-test-mcp-server", "--browser", "chromium"]
    }
  }
}

Environment Variables

# .env
PLAYWRIGHT_BROWSER=chromium     # Browser for MCP
PLAYWRIGHT_HEADLESS=false       # Show browser during MCP
PLAYWRIGHT_SLOW_MO=100          # Slow down for visibility

Troubleshooting

MCP Servers Not Running

Problem: TEA says MCP enhancements aren't available.

Causes:

MCP servers not configured in IDE
Config syntax error in JSON
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:

Playwright browsers not installed
Headless mode enabled
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:

Config not saved
Workflow run before config update
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:

Page not fully loaded
Element behind modal/overlay
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

Best Practices

Use MCP for Complex UIs

Simple UI (skip MCP):

Standard login form with email/password
TEA can infer selectors without MCP

Complex UI (use MCP):

Multi-step wizard with dynamic fields
Conditional UI elements
Third-party components
Custom form widgets

Start Without MCP, Enable When Needed

Learning path:

Week 1-2: TEA without MCP (learn basics)
Week 3: Enable MCP (explore advanced features)
Week 4+: Use MCP selectively (when it adds value)

Combine with Playwright Utils

Powerful combination:

tea_use_playwright_utils: true
tea_use_mcp_enhancements: true

Benefits:

Playwright Utils provides production-ready utilities
MCP verifies utilities work with actual app
Best of both worlds

Use for Test Healing

Scenario: Test suite has 50 failing tests after UI update.

With MCP:

*automate (healing mode)

TEA:
1. Opens trace viewer for each failure
2. Identifies changed selectors
3. Updates tests with corrected selectors
4. Verifies fixes with browser
5. Provides updated tests

Result: 45/50 tests auto-healed

Use for New Team Members

Onboarding:

New developer: "I don't know this codebase's UI"

Senior: "Run *test-design with MCP exploratory mode"

TEA explores UI and generates documentation:
- UI structure discovered
- Interactive elements mapped
- Test design created automatically

Security Considerations

MCP Servers Have Browser Access

What MCP can do:

Navigate to any URL
Click any element
Fill any form
Access browser storage
Read page content

Best practices:

Only configure MCP in trusted environments
Don't use MCP on production sites (use staging/dev)
Review generated tests before running on production
Keep MCP config in local files (not committed)

Protect Credentials

Don't:

"TEA, login with mypassword123"
# Password visible in chat history

Do:

"TEA, login using credentials from .env"
# Password loaded from environment, not in chat

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)

13 KiB Raw Blame History

Enable TEA MCP Enhancements

What are MCP Enhancements?

When to Use This

Prerequisites

Available MCP Servers

1. Playwright MCP - Browser Automation

2. Playwright Test MCP - Test Runner

Recommended: Configure Both

Installation

Step 1: Configure MCP Servers in IDE

Step 2: Install Playwright Browsers

Step 3: Enable in TEA Config

Step 4: Restart IDE

Step 5: Verify MCP Servers

How MCP Enhances TEA Workflows

*test-design: Exploratory Mode

*atdd: Recording Mode

*automate: Healing Mode

Usage Examples

Exploratory Mode Example

Recording Mode Example

Healing Mode Example

Configuration Options

MCP Server Arguments

Environment Variables

Troubleshooting

MCP Servers Not Running

Browser Doesn't Open

TEA Doesn't Use MCP

Selector Verification Fails

MCP Slows Down Workflows

Best Practices

Use MCP for Complex UIs

Start Without MCP, Enable When Needed

Combine with Playwright Utils

Use for Test Healing

Use for New Team Members

Security Considerations

MCP Servers Have Browser Access

Protect Credentials

Related Guides

Understanding the Concepts

Reference

13 KiB

Raw Blame History