browser-testing

Browser Testing

Browser MCP tools give you browser-level verification — navigate pages, read DOM content, check console errors, take screenshots, and interact with UI elements.

This skill applies to any agent or command that performs browser-based verification — the browser-verifier agent (dev and test modes) and the browser-test command (standalone regression testing).

---

Provider Detection (Do This First)

Bee supports two browser MCP providers. Try them in order — use whichever is available.

Step 1: Try Claude-in-Chrome (primary)

Call tabs_context_mcp (tool: mcp__claude-in-chrome__tabs_context_mcp).

• If it succeeds → use Claude-in-Chrome for this session. See the Claude-in-Chrome tool table below.
• If it fails or the tool is not found → continue to Step 2.

Step 2: Try chrome-devtools-mcp (fallback)

Use ToolSearch with query "+chrome-devtools-mcp" to discover chrome-devtools-mcp tools.

• If tools are found, call list_pages (tool: mcp__plugin_chrome-devtools-mcp_chrome-devtools__list_pages).
  • If it succeeds → use chrome-devtools-mcp for this session. See the chrome-devtools-mcp tool table below.
  • If it fails → plugin is installed but browser is not connected. Tell the user: "chrome-devtools-mcp is installed but the browser is not connected. See https://github.com/nicobailon/chrome-devtools-mcp for setup instructions."
• If no tools found → no browser MCP available. Degrade based on mode (see Graceful Degradation).

Step 3: No provider available

Tell the user:

"Browser verification requires a browser MCP provider. Install one of these:

1. Claude-in-Chrome extension — install from Chrome Web Store
2. chrome-devtools-mcp plugin — install from the Claude Code plugin marketplace: claude plugins install chrome-devtools-mcp"

Then degrade based on mode.

Important: Decide the provider ONCE at the start of the session. Do not re-check per operation. Use the chosen provider's tools consistently throughout.

---

Claude-in-Chrome Tools

Tools are prefixed with mcp__claude-in-chrome__.

Tool	What it does	When to use it
tabs_context_mcp	Get info about current browser tabs	Availability check
tabs_create_mcp	Create a new empty tab	Opening a fresh tab for testing
navigate	Navigate to a URL	Loading the app at the target URL
read_page	Get accessibility tree of page elements	Verifying element presence, structure, interactive states
find	Find elements by natural language description	Locating specific UI elements ("login button", "search bar")
get_page_text	Extract raw text content from the page	Verifying text content
computer	Mouse/keyboard interaction and screenshots	Clicking, typing, scrolling, taking screenshots
javascript_tool	Execute JavaScript in page context	Checking runtime state, custom assertions
read_console_messages	Read browser console output	Checking for runtime errors, exceptions, warnings

Workflow Pattern (Claude-in-Chrome)

1. tabs_context_mcp → check availability
2. tabs_create_mcp → open fresh tab
3. navigate → load the app URL
4. read_page → verify page structure
5. find / computer → interact with elements
6. read_page or computer (screenshot) → verify outcome
7. read_console_messages → check for errors

Screenshots (Claude-in-Chrome)

Use computer with action: "screenshot" to capture the current viewport.

---

chrome-devtools-mcp Tools

Tools are prefixed with mcp__plugin_chrome-devtools-mcp_chrome-devtools__.

Tool	What it does	When to use it
list_pages	List available browser pages/tabs	Availability check
new_page	Open a new browser page	Opening a fresh page for testing
navigate_page	Navigate to a URL	Loading the app at the target URL
take_snapshot	Get page structure with element uids (text-based, fast)	Verifying element presence; getting uids for interaction
take_screenshot	Capture visual screenshot	Visual verification, audit trail
click	Click an element by uid	Buttons, links, checkboxes
fill	Fill an input field by uid	Text inputs, textareas
fill_form	Fill multiple form fields at once	Forms with multiple inputs
type_text	Type text (keyboard-level)	Typing into focused elements
press_key	Press a specific key	Enter, Escape, Tab, arrow keys
hover	Hover over an element by uid	Hover states, tooltips
select_page	Switch to a different page/tab	Multi-page workflows
evaluate_script	Execute JavaScript in page context	Runtime state, custom assertions
list_console_messages	List browser console messages	Runtime errors, exceptions, warnings
get_console_message	Get details of a specific console message	Inspecting a particular error
list_network_requests	List network requests	Checking API calls, failed requests
get_network_request	Get details of a specific request	Inspecting request/response payloads
wait_for	Wait for a condition (element, text, network idle)	Ensuring page is loaded before interacting
resize_page	Resize the browser viewport	Testing responsive layouts
close_page	Close a browser page	Cleanup after testing
lighthouse_audit	Run a Lighthouse audit	Performance and accessibility checks

Workflow Pattern (chrome-devtools-mcp)

1. list_pages → check availability
2. new_page → open fresh page
3. navigate_page → load the app URL
4. wait_for → ensure content is loaded
5. take_snapshot → get element uids
6. click / fill / press_key → interact using uids from snapshot
7. take_snapshot or take_screenshot → verify outcome
8. list_console_messages → check for errors

Screenshots (chrome-devtools-mcp)

Use take_screenshot. For large pages, use the filePath parameter to save directly to disk.

---

Dev Server Detection

Detection follows a priority order. Stop at the first successful detection.

Step 1: Context sources (primary)

Check these first — developers often document their dev commands:

• CLAUDE.md in the target project — look for dev server commands, URLs, or run instructions
• Prior chat context — the developer may have mentioned the command or URL earlier in the conversation

Step 2: Ecosystem analysis (fallback)

If context sources don't have the info, analyze the project:

Ecosystem	Files to check	Common dev commands	Default URL
Node.js / npm	package.json scripts	npm run dev, npm start, next dev, vite	http://localhost:3000
Python	manage.py, pyproject.toml	python manage.py runserver, flask run, uvicorn	http://localhost:8000
Ruby	Gemfile, Procfile	rails server, bundle exec rails s	http://localhost:3000
Go	go.mod, Makefile	go run ., make dev	http://localhost:8080
Rust	Cargo.toml	cargo run, trunk serve	http://localhost:8080
Java	pom.xml, build.gradle	./mvnw spring-boot:run, ./gradlew bootRun	http://localhost:8080
Elixir	mix.exs	mix phx.server	http://localhost:4000

Step 3: Ask the developer

After detection (or if nothing found), always confirm: "Should I run {detected-command} and test on {default-uri}, or do you want to provide a different starting point URI?"

If nothing was detected, ask directly: "What command starts the dev server, and what URL should I test on?"

---

Graceful Degradation

Dev mode (called from bee:sdd)

• Report: "Browser verification skipped — no browser MCP provider available"
• Do not block the build. The regular verifier result (PASS) stands.
• The slice still passes. Browser verification is additive, not required.

Test mode (called from bee:browser-test)

• Report the specific issue (no provider found, or browser not connected) with the install instructions from Provider Detection Step 3.
• Stop. There is no fallback — browser testing is the entire purpose of this command.

---

Screenshot Conventions

When to capture

• Dev mode: Only on failure — screenshot the failing state for developer review
• Test mode: Both pass and fail — full audit trail for regression reports

Storage path

Screenshots are stored alongside test reports:

tests/executions/{YYYY-MM-DD}/{specname}-screenshot-{ac-number}.png

Create the directory structure if it doesn't exist.

Referencing in reports

In the test mode report, reference screenshots by relative path:

- [x] PASS: User can log in with email/password
  Screenshot: `user-auth-screenshot-1.png`
- [ ] FAILED: Dashboard shows recent activity
  Screenshot: `user-auth-screenshot-2.png`
  Expected: Recent activity section visible with at least one entry
  Observed: Section not rendered, console error: "TypeError: Cannot read property 'map' of undefined"