# Browser

Browser Mode enables the AI to control a web browser, automating interactions with your web applications. It's designed for testing localhost development servers and verifying UI behavior.

## Overview

| Attribute   | Value                                        |
|-------------|----------------------------------------------|
| **Best for**| UI testing, form validation, automation     |
| **Shortcut**| `Shift+Tab` to cycle modes                   |

Browser Mode is optimized for **localhost applications**. Use it to test your local development server.

## Requirements

Before using Browser Mode, you need to install the browser automation components:

### Open Browser Settings

Go to **Settings → Browser** (in the Advanced section).

### Check installation status

You'll see whether the browser is **Installed** or **Not Installed**.

### Install if needed

Click **Install Browser** and wait for the download to complete. This installs Playwright browser binaries.

## What Browser Mode Can Do

### Navigation

- **Launch browser** and navigate to a URL
- **Navigate** to different pages
- **Close browser** when done

### Page Interaction

- **Click** buttons and links
- **Double-click** elements
- **Hover** over items
- **Fill** text inputs and forms
- **Select** dropdown options
- **Check/uncheck** checkboxes
- **Press keys** (Enter, Tab, Escape, etc.)

### Page Observation

- **Snapshot** — Quick status check (URL, title, element counts)
- **Observe** — Full page state with interactive elements indexed
- **Get text** — Extract text from specific elements
- **Screenshot** — Capture visual snapshots

### Debugging

- **Console logs** — Capture browser console output
- **Execute JavaScript** — Run custom scripts in the page
- **Inspect elements** — Check visibility, enabled state, etc.

### Manual Handoff

- **Wait for user** — Pause for you to handle passwords, 2FA, CAPTCHA

## How to Use Browser Mode

### Start your local server

Make sure your web application is running locally:

```
npm run dev
# Server running at http://localhost:3000
```

### Switch to Browser Mode

Click the **Mode Selector** and choose **Browser**, or press `Shift+Tab` until you see the green globe icon.

### Describe what to test

Tell the AI what you want to automate:

```
Go to http://localhost:3000 and test the login form with
email "test@example.com" and password "password123"
```

```
Navigate to the settings page and verify all form fields are visible
```

```
Fill out the contact form and check for validation errors
```

### Watch the automation

The AI will:

- Launch a browser session
- Navigate to your URL
- Perform the requested actions
- Report what it finds

## Visual Indicators

When Browser Mode is active:

- **Green border** around the input area
- **Globe icon** in the mode selector
- **Green send button**

During automation, each action shows:

- Action type (Launch, Click, Fill, etc.)
- Target element or URL
- Status (executing, complete, error)
- Results when applicable

## Wait for User

Sometimes the AI needs you to handle something manually—like entering a password or solving a CAPTCHA.

When this happens, you'll see:

- An **orange pulsing indicator**
- A message explaining what's needed
- **Continue** button — Resume after you've completed the action
- **Stop** button — Cancel the automation

You'll also receive a desktop notification when the AI is waiting for your input.

## Common Use Cases

### Form Testing

Test the signup form at [http://localhost:3000/signup](http://localhost:3000/signup):

- Try submitting with empty fields
- Enter an invalid email and check the error
- Fill all fields correctly and submit

### Navigation Testing

Verify all navigation links work on [http://localhost:3000](http://localhost:3000/):

- Click each menu item
- Confirm the correct page loads
- Check for any console errors

### Visual Verification

Take screenshots of the dashboard at different states:

- Empty state (no data)
- With sample data loaded
- Error state

### Multi-Step Workflows

Test the checkout flow:

- Add items to cart
- Go to checkout
- Fill shipping information
- Verify order summary

## Best Practices

### Start with Clear URLs

Always specify the full localhost URL:
[http://localhost:3000/login](http://localhost:3000/login)

### Be Specific About Elements

Help the AI find the right elements:
- Click the blue "Submit" button at the bottom of the form

### Handle Sensitive Data Carefully

For passwords and sensitive information:
- Navigate to login, then wait for me to enter credentials

### Check Console for Errors

Ask the AI to monitor for issues:
- Test the page and report any console errors or warnings.