Auto-Browse: AI Enabled Browser Automation

Auto Browse is the easiest way to connect your AI agents with the browser using natural language.

🎥 Watch the launch video

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 to see a complete implementation using Auto Browse with BDD testing patterns.

Installation

npm install @auto-browse/auto-browse

⚠️ Important: Playwright Version Requirements

Auto Browse requires Playwright version 1.53.0 or higher.

Required Versions

"@playwright/test": ">=1.53.0"
"playwright": ">=1.53.0"

Installation

If you encounter version conflicts, use the legacy peer deps flag:

npm install --legacy-peer-deps

Quick Setup

1. Create a .env file in your project root:

# 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:

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:

npx ts-node your-script.ts

Playwright Test Mode

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:

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 for behavior-driven development:

# 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"

// 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

// 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 - 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