Content
# Auto-Browse: AI Enabled Browser Automation
**Auto Browse** is the easiest way to connect your AI agents with the browser using natural language.
[](https://youtu.be/VxJg3RRShoY)
🎥 [Watch the launch video](https://youtu.be/VxJg3RRShoY)
## Quick start
An AI-powered browser automation agent for automating browser tasks and Write Playwright tests that enables natural language interactions with web pages.
## Examples
Check out our [TypeScript BDD Example Repository](https://github.com/auto-browse/auto-browse-typescript-bdd-example) to see a complete implementation using Auto Browse with BDD testing patterns.
## Installation
```bash
npm install @auto-browse/auto-browse
```
## ⚠️ Important: Playwright Version Requirements
Auto Browse requires Playwright version 1.53.0 or higher.
### Required Versions
```bash
"@playwright/test": ">=1.53.0"
"playwright": ">=1.53.0"
```
### Installation
If you encounter version conflicts, use the legacy peer deps flag:
```bash
npm install --legacy-peer-deps
```
## Quick Setup
1. Create a `.env` file in your project root:
```env
# For OpenAI (default)
OPENAI_API_KEY=your_openai_api_key_here
LLM_PROVIDER=openai # Optional
AUTOBROWSE_LLM_MODEL=gpt-4o-mini # Optional
# Or for Google AI
GOOGLE_API_KEY=your_google_key_here
LLM_PROVIDER=google
AUTOBROWSE_LLM_MODEL=gemini-2.0-flash-lite
```
2. Start automating!
## Supported LLM Providers
- **OpenAI** (default) - GPT-4 and compatible models
- **Google AI** - Gemini models
- **Azure OpenAI** - GPT models on Azure
- **Anthropic** - Claude models
- **Google Vertex AI** - PaLM and Gemini models
- **Ollama** - Run models locally
## Usage
### Standalone Mode (Without Playwright Test)
Auto Browse can also be used outside of Playwright test context. Here's a complete form automation example:
```typescript
import { auto } from "@auto-browse/auto-browse";
async function main() {
try {
// Navigate to the form
await auto("go to https://httpbin.org/forms/post");
// Take a snapshot to analyze the page structure
await auto("take a snapshot");
// Fill out the form
await auto('type "John Doe" in the customer name field');
await auto('select "Large" for size');
await auto('select "Mushroom" for topping');
await auto('check "cheese" in extras');
// Submit the form
await auto("click the Order button");
// Take a snapshot of the response page
await auto("take a snapshot of the response page");
} catch (error) {
console.error("Error:", error);
}
}
// Run the script
main().catch(console.error);
```
In standalone mode, Auto Browse automatically:
- Manages browser lifecycle
- Creates and configures pages
- Handles cleanup
To run standalone scripts:
```bash
npx ts-node your-script.ts
```
### Playwright Test Mode
```typescript
import { test, expect } from "@playwright/test";
import { auto } from "@auto-browse/auto-browse";
test("example test", async ({ page }) => {
await page.goto("https://example.com");
// Get text using natural language
const headerText = await auto("get the header text", { page });
// Type in an input using natural language
await auto('type "Hello World" in the search box', { page });
// Click elements using natural language
await auto("click the login button", { page });
});
```
### Auto-Detection Mode
The package automatically detects the current page context, so you can skip passing the page parameter:
```typescript
import { test, expect } from "@playwright/test";
import { auto } from "@auto-browse/auto-browse";
test("simplified example", async ({ page }) => {
await page.goto("https://example.com");
// No need to pass page parameter
const headerText = await auto("get the header text");
await auto('type "Hello World" in the search box');
await auto("click the login button");
});
```
### BDD Mode with Playwright-BDD
Auto Browse integrates with [playwright-bdd](https://github.com/vitalets/playwright-bdd) for behavior-driven development:
```gherkin
# features/homepage.feature
Feature: Playwright Home Page
Scenario: Check title
Given navigate to https://playwright.dev
When click link "Get started"
Then assert title "Installation"
```
```typescript
// One step definition handles all actions
import { auto } from "@auto-browse/auto-browse";
import { Given, When as aistep, Then } from "./fixtures";
aistep(/^(.*)$/, async ({ page }, action: string) => {
await auto(action, { page });
});
```
### Key Actions
```typescript
// Navigation
await auto("go to https://example.com");
// Clicking
await auto("click the submit button");
// Typing
await auto('type "username" in the email field');
// Verification
await auto("verify the success message is visible");
// Taking snapshots
await auto("take a snapshot");
```
## Core Features
- **Natural Language Commands** - Write automation in plain English
- **AI-Powered Intelligence** - Smart element detection and interaction
- **Auto Context Detection** - Automatically manages browser and page contexts
- **Multiple LLM Support** - Works with OpenAI, Google AI, Anthropic, and more
- **Playwright Integration** - Seamless integration with Playwright tests
- **TypeScript Support** - Full type safety and IntelliSense
- **Zero Configuration** - Works out of the box with minimal setup
## Documentation
📚 [Full Documentation](https://typescript.docs.auto-browse.com/quickstart) - Complete guides, examples, and API reference
## Best Practices
- **Be descriptive**: `"click the submit button in the login form"` vs `"click submit"`
- **Use quotes for values**: `'type "John Doe" in the name field'`
- **Take snapshots**: `"take a snapshot"` helps the AI understand page context
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Thanks to Playwright Team for creating Playwright MCP and Playwright BDD.
## License
MIT
