Configure Browser Automation

Configure Browser Automation

TEA can interact with live browsers during test generation: verify selectors, explore UIs, capture evidence, and debug failures. Two tools do this, and auto mode combines them.

The Four Modes

TEA’s browser automation is controlled by tea_browser_automation under [modules.tea] in _bmad/config.toml. bmad setup tea asks for it; run it again to change the answer, or edit the file:

tea_browser_automation = "auto" # auto | cli | mcp | none

Mode	Behavior
auto	TEA picks the right tool per action: CLI for quick lookups, MCP for complex flows. Falls back gracefully if only one tool is installed. (Recommended)
cli	CLI only. MCP ignored even if configured.
mcp	MCP only. CLI ignored even if installed. Same as the old tea_use_mcp_enhancements: true.
none	No browser interaction. TEA generates from docs and code analysis only.

Prerequisites

For CLI (cli or auto mode)

npm install -g @playwright/cli@latest    # Install globally (Node.js 18+)
playwright-cli install --skills          # Claude Code: .claude/skills/playwright-cli
# For Codex, use this skills layout:
playwright-cli install --skills=agents   # .agents/skills/playwright-cli

The global npm install is one-time. Run the skills install from your project root. playwright-cli install --skills uses the Claude Code layout; Codex uses playwright-cli install --skills=agents. See the Playwright CLI skills documentation for global installation options. Agents without skills support can still use the CLI directly via playwright-cli --help.

For MCP (mcp or auto mode)

Add these MCP server entries to your tool’s configuration file:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "playwright-test": {
      "type": "stdio",
      "command": "npx",
      "args": ["playwright", "run-test-mcp-server"]
    },
    "smartbear": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@smartbear/mcp@latest"],
      "env": {
        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
        "PACT_BROKER_TOKEN": "<your-api-token>"
      }
    }
  }
}

The smartbear server is optional. Add it only if you use the Pact MCP integration for contract testing skills. See the pact-mcp knowledge fragment for details.

Where to put the config

Tool	Config File	Format
Claude Code	~/.claude.json	JSON (mcpServers)
Codex	~/.codex/config.toml	TOML ([mcp_servers])
Gemini CLI	~/.gemini/settings.json	JSON (mcpServers)
Cursor	~/.cursor/mcp.json	JSON (mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json	JSON (mcpServers)
VS Code (Copilot)	.vscode/mcp.json	JSON (servers)

Use claude mcp add to register servers in Claude Code. Use -s user for all projects or -s project for a shared project configuration in .mcp.json. Omitting -s uses local scope, private to you in the current project.

CLI shortcuts

Claude Code and Codex support adding MCP servers from the command line:

# Claude Code: Playwright (user scope; use -s project to share with the project)
claude mcp add -s user --transport stdio playwright -- npx -y @playwright/mcp@latest
claude mcp add -s user --transport stdio playwright-test -- npx playwright run-test-mcp-server

# Claude Code: SmartBear (Pact). Use add-json for servers with env vars
claude mcp add-json -s user smartbear \
  '{"type":"stdio","command":"npx","args":["-y","@smartbear/mcp@latest"],"env":{"PACT_BROKER_BASE_URL":"https://{tenant}.pactflow.io","PACT_BROKER_TOKEN":"<your-token>"}}'

# Codex: Playwright
codex mcp add playwright -- npx -y @playwright/mcp@latest
codex mcp add playwright-test -- npx playwright run-test-mcp-server

# Codex: SmartBear (Pact)
codex mcp add smartbear -- npx -y @smartbear/mcp@latest

Codex TOML format

Use these TOML entries when editing Codex configuration manually:

[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest"]

[mcp_servers.playwright-test]
command = "npx"
args = ["playwright", "run-test-mcp-server"]

[mcp_servers.smartbear]
command = "npx"
args = ["-y", "@smartbear/mcp@latest"]

[mcp_servers.smartbear.env]
PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
PACT_BROKER_TOKEN = "<your-api-token>"

Use the mcp_servers table name in Codex.

How Auto Mode Works

An explicit request in your prompt wins (“use the CLI to explore this page”). Otherwise TEA takes the CLI for stateless work (snapshots, locator verification, evidence capture) and MCP for stateful flows (multi-tab, file uploads, repeated edits, self-healing). If only one tool is installed it uses that one; with neither it behaves as none.

Which Skills Benefit

Skill	Default Tool (auto)	Use Case
test-design	CLI	Page discovery, snapshots (stateless)
automate red mode	CLI + MCP	CLI for baseline capture, MCP for complex interactions
automate expand mode	CLI + MCP	CLI for selector verification, MCP for healing
test-review	CLI	Traces, screenshots, network (stateless evidence)
nfr-assess	CLI	Network monitoring, timing (stateless)

Overriding Per Request

Even in auto mode, you can override per-request:

"Use the CLI to snapshot the login page"
"Open MCP browser and walk through the checkout wizard"

Migrating from tea_use_mcp_enhancements

The old boolean flag tea_use_mcp_enhancements has been replaced:

• Old true: set tea_browser_automation = "mcp" to keep MCP-only behavior, or "auto" to opt into CLI and MCP selection (recommended).
• Old false: set tea_browser_automation = "none".

Nothing migrates the old flag automatically. Answer the browser automation question in bmad setup tea with the value you chose.

Troubleshooting

CLI Not Working

# Verify CLI is installed
playwright-cli --version

# Install if missing
npm install -g @playwright/cli@latest

# Install skills: Claude Code layout
playwright-cli install --skills
# Install skills: Codex layout
playwright-cli install --skills=agents

MCP Not Working

1. Check MCP servers are configured in your assistant
2. Restart the assistant after configuration changes
3. Confirm the assistant sees them: claude mcp list in Claude Code or codex mcp list in Codex should list playwright and playwright-test; other assistants show them in their MCP settings panel

Auto Mode Not Selecting Expected Tool

Auto mode logs its decisions:

• “Using CLI for snapshot (stateless discovery)”
• “Using MCP for multi-step recording (stateful flow)”

Check the skill output for these messages.

Session Cleanup Issues

If you see orphaned browser processes:

# List active sessions
playwright-cli list

# Close a specific session. TEA names each one tea-<workflow>-<run_key>;
# atdd and automate add a timestamp suffix, and ci and framework,
# which have no run_key, use tea-<workflow>-<timestamp>.
playwright-cli -s=tea-test-design-epic-3 close

# Emergency cleanup (kills ALL sessions -- use only manually)
playwright-cli close-all

Related

• TEA Overview: Optional Integrations
• Integrate Playwright Utils
• TEA Configuration Reference