{"id":26880448,"url":"https://github.com/auto-browse/auto-browse-ts","last_synced_at":"2025-05-07T21:47:07.912Z","repository":{"id":285294761,"uuid":"956659161","full_name":"auto-browse/auto-browse-ts","owner":"auto-browse","description":"Auto-Browse: AI Enabled Browser Automation","archived":false,"fork":false,"pushed_at":"2025-04-09T02:50:31.000Z","size":768,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-07T21:46:57.295Z","etag":null,"topics":["ai","ai-test-generator","ai-testing-tool","auto-browser","automation","browser-agent","browser-automation","browser-use","computer-use","langchain","llm","mcp","openai","playwright","test-automation","testing"],"latest_commit_sha":null,"homepage":"https://auto-browse.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/auto-browse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-28T16:23:47.000Z","updated_at":"2025-04-29T06:26:53.000Z","dependencies_parsed_at":"2025-03-30T22:29:33.273Z","dependency_job_id":null,"html_url":"https://github.com/auto-browse/auto-browse-ts","commit_stats":null,"previous_names":["auto-browse/auto-browse-ts"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auto-browse%2Fauto-browse-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auto-browse%2Fauto-browse-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auto-browse%2Fauto-browse-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auto-browse%2Fauto-browse-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/auto-browse","download_url":"https://codeload.github.com/auto-browse/auto-browse-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252961858,"owners_count":21832192,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-test-generator","ai-testing-tool","auto-browser","automation","browser-agent","browser-automation","browser-use","computer-use","langchain","llm","mcp","openai","playwright","test-automation","testing"],"created_at":"2025-03-31T14:24:22.580Z","updated_at":"2025-05-07T21:47:07.901Z","avatar_url":"https://github.com/auto-browse.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Auto-Browse: AI Enabled Browser Automation\n\n**Auto Browse** is the easiest way to connect your AI agents with the browser using natural language.\n\n[![Auto-Browse Launch Video](https://img.youtube.com/vi/VxJg3RRShoY/maxresdefault.jpg)](https://youtu.be/VxJg3RRShoY)\n\n🎥 [Watch the launch video](https://youtu.be/VxJg3RRShoY)\n\n## Quick start\n\nAn AI-powered browser automation agent for automating browser tasks and Write Playwright tests that enables natural language interactions with web pages.\n\n## Examples\n\nCheck 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.\n\n## Installation\n\n```bash\nnpm install @auto-browse/auto-browse\n```\n\n## ⚠️ Important: Playwright Version Requirements\n\n\u003e **Note:** Auto Browse currently requires specific versions of Playwright. This requirement will be relaxed in future versions.\n\n### Required Versions\n\n```bash\n\"@playwright/test\": \"1.52.0-alpha-1743011787000\"\n\"playwright\": \"1.52.0-alpha-1743011787000\"\n```\n\n### Version Conflicts\n\nIf you're using Auto Browse alongside an existing Playwright setup, you must upgrade to these specific versions. Here's how to handle common issues:\n\n1. **Installation Conflicts**\n\n   ```bash\n   npm install --legacy-peer-deps\n   ```\n\n   This flag helps resolve peer dependency conflicts during installation.\n\n2. **Multiple Playwright Versions**\n\n   - Remove existing Playwright installations\n   - Clear npm cache if needed: `npm cache clean --force`\n   - Reinstall with the required versions\n\n3. **Project Compatibility**\n   - Update your project's Playwright configuration\n   - Ensure your existing tests are compatible with the alpha version\n   - Consider using a separate test environment if needed\n\n\u003e 🔄 Future releases will support a wider range of Playwright versions. Subscribe to our GitHub repository for updates.\n\n## Configuration\n\nAuto Browse requires environment variables for the LLM (Language Model) configuration. Create a `.env` file in your project root:\n\n```env\n# OpenAI (default)\nOPENAI_API_KEY=your_openai_api_key_here\nLLM_PROVIDER=openai  # Optional, defaults to openai\nAUTOBROWSE_LLM_MODEL=gpt-4o-mini  # Optional, defaults to gpt-4o-mini\n\n# Google AI\nGOOGLE_API_KEY=your_google_key_here\nLLM_PROVIDER=google\nAUTOBROWSE_LLM_MODEL=gemini-2.0-flash-lite\n\n# Azure OpenAI\nAZURE_OPENAI_API_KEY=your_azure_key_here\nAZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com/\nAZURE_OPENAI_API_VERSION=2024-12-01-preview\nAZURE_OPENAI_API_DEPLOYMENT_NAME=your-deployment-name\nLLM_PROVIDER=azure\n\n# Anthropic\nANTHROPIC_API_KEY=your_anthropic_key_here\nLLM_PROVIDER=anthropic\nAUTOBROWSE_LLM_MODEL=claude-3\n\n# Google Vertex AI\nGOOGLE_APPLICATION_CREDENTIALS=path/to/credentials.json\nLLM_PROVIDER=vertex\n\n# Ollama\nBASE_URL=http://localhost:11434  # Optional, defaults to this value\nLLM_PROVIDER=ollama\nAUTOBROWSE_LLM_MODEL=llama3.1\n```\n\nYou can find an example configuration in `example.env`.\n\n### Environment Variables\n\n| Variable                           | Description                            | Default                  | Required For |\n| ---------------------------------- | -------------------------------------- | ------------------------ | ------------ |\n| `LLM_PROVIDER`                     | LLM provider to use                    | `openai`                 | No           |\n| `AUTOBROWSE_LLM_MODEL`             | The LLM model to use                   | `gpt-4o-mini`            | No           |\n| `OPENAI_API_KEY`                   | OpenAI API key                         | -                        | OpenAI       |\n| `GOOGLE_API_KEY`                   | Google AI API key                      | -                        | Google AI    |\n| `AZURE_OPENAI_API_KEY`             | Azure OpenAI API key                   | -                        | Azure        |\n| `AZURE_OPENAI_ENDPOINT`            | Azure OpenAI endpoint URL              | -                        | Azure        |\n| `AZURE_OPENAI_API_VERSION`         | Azure OpenAI API version               | `2024-12-01-preview`     | Azure        |\n| `AZURE_OPENAI_API_DEPLOYMENT_NAME` | Azure OpenAI deployment name           | -                        | Azure        |\n| `ANTHROPIC_API_KEY`                | Anthropic API key                      | -                        | Anthropic    |\n| `GOOGLE_APPLICATION_CREDENTIALS`   | Path to Google Vertex credentials file | -                        | Vertex AI    |\n| `BASE_URL`                         | Ollama API endpoint                    | `http://localhost:11434` | No           |\n\n## Supported LLM Providers\n\nAuto Browse supports multiple LLM providers:\n\n- OpenAI (default) - GPT-4 and compatible models\n- Google AI - Gemini models\n- Azure OpenAI - GPT models on Azure\n- Anthropic - Claude models\n- Google Vertex AI - PaLM and Gemini models\n- Ollama - Run models locally\n\n## Usage\n\n### Standalone Mode (Without Playwright Test)\n\nAuto Browse can also be used outside of Playwright test context. Here's a complete form automation example:\n\n```typescript\nimport { auto } from \"@auto-browse/auto-browse\";\n\nasync function main() {\n\ttry {\n\t\t// Navigate to the form\n\t\tawait auto(\"go to https://httpbin.org/forms/post\");\n\n\t\t// Take a snapshot to analyze the page structure\n\t\tawait auto(\"take a snapshot\");\n\n\t\t// Fill out the form\n\t\tawait auto('type \"John Doe\" in the customer name field');\n\t\tawait auto('select \"Large\" for size');\n\t\tawait auto('select \"Mushroom\" for topping');\n\t\tawait auto('check \"cheese\" in extras');\n\n\t\t// Submit the form\n\t\tawait auto(\"click the Order button\");\n\n\t\t// Take a snapshot of the response page\n\t\tawait auto(\"take a snapshot of the response page\");\n\t} catch (error) {\n\t\tconsole.error(\"Error:\", error);\n\t}\n}\n\n// Run the script\nmain().catch(console.error);\n```\n\nIn standalone mode, Auto Browse automatically:\n\n- Manages browser lifecycle\n- Creates and configures pages\n- Handles cleanup\n\nTo run standalone scripts:\n\n```bash\nnpx ts-node your-script.ts\n```\n\n### Playwright Test Mode\n\n```typescript\nimport { test, expect } from \"@playwright/test\";\nimport { auto } from \"@auto-browse/auto-browse\";\n\ntest(\"example test\", async ({ page }) =\u003e {\n\tawait page.goto(\"https://example.com\");\n\n\t// Get text using natural language\n\tconst headerText = await auto(\"get the header text\", { page });\n\n\t// Type in an input using natural language\n\tawait auto('type \"Hello World\" in the search box', { page });\n\n\t// Click elements using natural language\n\tawait auto(\"click the login button\", { page });\n});\n```\n\n### Auto-Detection Mode\n\nThe package automatically detects the current page context, so you can skip passing the page parameter:\n\n```typescript\nimport { test, expect } from \"@playwright/test\";\nimport { auto } from \"@auto-browse/auto-browse\";\n\ntest(\"simplified example\", async ({ page }) =\u003e {\n\tawait page.goto(\"https://example.com\");\n\n\t// No need to pass page parameter\n\tconst headerText = await auto(\"get the header text\");\n\tawait auto('type \"Hello World\" in the search box');\n\tawait auto(\"click the login button\");\n});\n```\n\n### BDD Mode with Playwright-BDD\n\nAuto Browse seamlessly integrates with [playwright-bdd](https://github.com/vitalets/playwright-bdd) for behavior-driven development. This allows you to write expressive feature files and implement steps using natural language commands.\n\n#### Example Feature File\n\n```gherkin\n# features/homepage.feature\nFeature: Playwright Home Page\n\n  Scenario: Check title\n    Given navigate to https://playwright.dev\n    When click link \"Get started\"\n    Then assert title \"Installation\"\n```\n\n#### Step Definitions\n\n```typescript\nimport { auto } from \"@auto-browse/auto-browse\";\nimport { Given, When as aistep, Then } from \"./fixtures\";\n\n// Generic step that handles any natural language action\naistep(/^(.*)$/, async ({ page }, action: string) =\u003e {\n\tawait auto(action, { page });\n});\n```\n\n#### Setup Requirements\n\n1. Install dependencies:\n\n```bash\nnpm install --save-dev @playwright/test @cucumber/cucumber playwright-bdd\n```\n\n2. Configure `playwright.config.ts`:\n\n```typescript\nimport { PlaywrightTestConfig } from \"@playwright/test\";\n\nconst config: PlaywrightTestConfig = {\n\ttestDir: \"./features\",\n\tuse: {\n\t\tbaseURL: \"https://playwright.dev\"\n\t}\n};\n\nexport default config;\n```\n\nThis integration enables:\n\n- Natural language test scenarios\n- Reusable step definitions\n- Cucumber reporter integration\n- Built-in Playwright context management\n\n### Supported Actions\n\n1. **Clicking Elements**\n\n   ```typescript\n   await auto(\"click the submit button\");\n   await auto(\"click the link that says Learn More\");\n   ```\n\n2. **Typing Text**\n\n   ```typescript\n   await auto('type \"username\" in the email field');\n   await auto('enter \"password123\" in the password input');\n   ```\n\n## Features\n\nCore Features:\n\n- Natural language commands for browser automation\n- AI-powered computer and browser agent\n- Automate any browser task\n- Automatic page/context detection\n- TypeScript support\n- Playwright test integration\n- Zero configuration required\n\nSupported Operations:\n\n- Page Navigation (goto URL, back, forward)\n- Element Interactions (click, type, hover, drag-and-drop)\n- Form Handling (select options, file uploads, form submission)\n- Visual Verification (snapshots, screenshots, PDF export)\n- Keyboard Control (key press, text input)\n- Wait and Timing Control\n- Assertions and Validation\n\n## Best Practices\n\n1. **Be Descriptive**\n\n   ```typescript\n   // Good\n   await auto(\"click the submit button in the login form\");\n\n   // Less Clear\n   await auto(\"click submit\");\n   ```\n\n2. **Use Quotes for Input Values**\n\n   ```typescript\n   // Good\n   await auto('type \"John Doe\" in the name field');\n\n   // Not Recommended\n   await auto(\"type John Doe in the name field\");\n   ```\n\n3. **Leverage Existing Labels**\n   - Use actual labels and text from your UI in commands\n   - Maintain good accessibility practices in your app for better automation\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\nThanks to Playwright Team for creating Playwright MCP and Playwright BDD.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauto-browse%2Fauto-browse-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fauto-browse%2Fauto-browse-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauto-browse%2Fauto-browse-ts/lists"}