Browser Testing MCP Server - Cursor AI Instructions

Setup Instructions

Install Python dependencies:

pip install mcp playwright python-dotenv playwright install chromium

Save the Python file as browser_testing_mcp.py
Make it executable:

chmod +x browser_testing_mcp.py

Configure MCP in Cursor: Add to your MCP configuration file:

{ "mcpServers": { "browser-testing": { "command": "python", "args": ["/full/path/to/browser_testing_mcp.py"] } } }

Instructions for Cursor AI

You have access to a Browser Testing MCP server that allows you to control a real browser to test web applications. This is particularly useful for verifying that web apps you create are functioning correctly.

Available Tools

You can use these tools to interact with a browser:

Browser Management

launch_browser - Start a browser instance (set headless=false to see it)
close_browser - Close the browser when done
navigate_to - Go to any URL

Interaction

click_element - Click any element by CSS selector
type_text - Type into input fields
fill_form - Fill multiple form fields at once
evaluate_javascript - Execute custom JavaScript

Monitoring & Debugging

get_console_logs - See JavaScript errors and console output
get_network_requests - Monitor API calls and responses
get_page_metrics - Check performance metrics
take_screenshot - Capture visual state

Verification

wait_for_selector - Wait for elements to appear
check_element_state - Verify element states (visible, enabled, etc.)
get_local_storage - Check stored data
get_cookies - Verify authentication cookies
get_page_content - Get HTML content

Testing Workflow Example

When testing a web application you've created, follow this pattern:

# 1. Launch browser in visible mode to see what's happening launch_browser(headless=False, viewport_width=1280, viewport_height=720) # 2. Navigate to the app navigate_to(url="http://localhost:3000", wait_until="networkidle") # 3. Test user registration/login fill_form(fields=[ {"selector": "#email", "value": "test@example.com", "field_type": "text"}, {"selector": "#password", "value": "SecurePass123", "field_type": "text"}, {"selector": "#agree", "value": "true", "field_type": "checkbox"} ]) click_element(selector="#submit-button") # 4. Wait for success wait_for_selector(selector=".dashboard", state="visible", timeout=5000) # 5. Check for errors get_console_logs(log_type="error") # Check for JavaScript errors # 6. Verify API calls worked get_network_requests(method="POST", url_pattern="/api/auth") # 7. Check authentication state get_local_storage(key="authToken") get_cookies(name="session") # 8. Test navigation click_element(selector="a[href='/profile']") wait_for_selector(selector=".profile-page") # 9. Verify content loaded check_element_state(selector=".user-data", checks=["visible", "enabled"]) # 10. Take screenshot for visual verification take_screenshot(full_page=True) # 11. Get performance metrics get_page_metrics() # 12. Close when done close_browser()

Common Testing Scenarios

Test Form Validation

# Try submitting empty form click_element(selector="#submit") wait_for_selector(selector=".error-message") get_page_content(selector=".error-message")

Test API Error Handling

# Check how app handles API failures navigate_to(url="http://localhost:3000/users") get_network_requests(url_pattern="/api/users") # Check if error state is displayed properly check_element_state(selector=".error-banner", checks=["visible"])

Test Authentication Flow

# Test login -> dashboard -> logout fill_form(fields=[ {"selector": "#username", "value": "testuser"}, {"selector": "#password", "value": "password123"} ]) click_element(selector="#login-btn") wait_for_selector(selector=".dashboard") get_local_storage(key="auth_token") # Verify token stored click_element(selector="#logout") wait_for_selector(selector=".login-page") get_local_storage(key="auth_token") # Verify token cleared

Test Responsive Design

# Test mobile view launch_browser(headless=False, viewport_width=375, viewport_height=667) navigate_to(url="http://localhost:3000") check_element_state(selector=".mobile-menu", checks=["visible"]) check_element_state(selector=".desktop-menu", checks=["hidden"])

Debugging Tips

Always check console logs after interactions to catch JavaScript errors
Monitor network requests to ensure APIs are called correctly
Use screenshots to visually verify UI state
Check localStorage/cookies to verify data persistence
Use wait_for_selector before interacting with dynamically loaded content
Run with headless=False to see what's happening during debugging

Error Handling

If you encounter errors:

"Browser not launched" - Call launch_browser first
"Element not found" - Check selector is correct, use wait_for_selector first
"Timeout" - Increase timeout value or check if element actually appears
Network issues - Check if the app is running on the expected port

Best Practices

Always close the browser when done testing
Use descriptive selectors (IDs or data-testid attributes)
Wait for elements before interacting with them
Check both success and error cases
Verify API calls match expected patterns
Take screenshots at key points for visual verification
Check performance metrics to ensure app loads efficiently

This tool allows you to thoroughly test any web application you create, ensuring all features work correctly before considering the task complete.

Browser Testing MCP Server