# Browser Pilot 🎯
A streamlined browser automation framework that uses AI-powered agents to execute natural language test scenarios.
[](https://www.python.org/downloads/)
[](https://pypi.org/project/browser-pilot-llm/)
[](https://github.com/smiao-icims/browser-pilot/actions)
[](LICENSE)
[](https://codecov.io/gh/smiao-icims/browser-pilot)
## 🎯 Getting Started in 3 Minutes
### Option 1: Install from PyPI (Recommended)
```bash
# 1. Install Browser Pilot from PyPI
pip install browser-pilot-llm
# 2. Run the setup wizard (2 minutes)
browser-pilot --setup-wizard
# 3. Create a test file (test.md)
cat > test.md << 'EOF'
# My First Test
1. Go to https://www.google.com
2. Search for "Browser Pilot AI testing"
3. Click on the first result
4. Take a screenshot
EOF
# 4. Run your test!
browser-pilot test.md
```
### Option 2: Install from Source
```bash
# 1. Clone and install
git clone https://github.com/smiao-icims/browser-pilot.git
cd browser-pilot
uv sync
# 2. Run the setup wizard
uv run browser-pilot --setup-wizard
# 3. Create and run your test
uv run browser-pilot test.md
```
That's it! You've just automated your first browser test. 🎉
## ✨ Features
- 🤖 **AI-Powered**: Uses LLMs to understand and execute test instructions written in plain English
- 🎯 **Simple**: Write tests in markdown - no coding required
- 🚀 **Efficient**: Single agent architecture with token optimization (20-30% reduction)
- 🔧 **Flexible**: Supports multiple LLM providers via [ModelForge](https://github.com/smiao-icims/model-forge) ([PyPI](https://pypi.org/project/model-forge-llm/))
- 📊 **Insightful**: Enhanced reports with timing, token usage, and cost analysis
- 🌐 **Cross-Browser**: Supports Chromium, Chrome, Firefox, Safari, Edge, and WebKit
- 🔍 **Verbose Mode**: Step-by-step debugging with dual console/file logging
- 💰 **Cost Optimization**: Built-in token optimization to reduce API costs
- 📝 **Multiple Formats**: Export results as JSON, YAML, XML, JUnit, HTML, or Markdown
- 🎛️ **Customizable**: System prompts, browser settings, and optimization levels
- 🧙 **Setup Wizard**: Interactive configuration with arrow-key navigation
## 🚀 Quick Start - Get Testing in 3 Minutes!
### 1️⃣ Install Browser Pilot
#### Option A: Install from PyPI (Recommended)
```bash
# Install with pip
pip install browser-pilot-llm
# Or with uv (faster)
uv pip install browser-pilot-llm
```
#### Option B: Install from Source
```bash
# Clone and install
git clone https://github.com/smiao-icims/browser-pilot.git
cd browser-pilot
curl -LsSf https://astral.sh/uv/install.sh | sh # Install uv if needed
uv sync # Install dependencies
```
### 2️⃣ Run Setup Wizard (2 minutes)
```bash
# If installed from PyPI:
browser-pilot --setup-wizard
# If installed from source:
uv run browser-pilot --setup-wizard
```
The wizard will guide you through:
- 🤖 Selecting an LLM provider (GitHub Copilot recommended - no API key!)
- 🔐 Authentication setup
- 🌐 Browser configuration
- ✅ Validation with a test prompt
### 3️⃣ Create Your First Test
Create a file `my-test.md` with natural language instructions:
```markdown
# My First Test
1. Navigate to https://www.wikipedia.org
2. Search for "artificial intelligence"
3. Verify the page shows results about AI
4. Take a screenshot
```
### 4️⃣ Run Your Test!
```bash
# If installed from PyPI:
browser-pilot my-test.md
# If installed from source:
uv run browser-pilot my-test.md
# That's it! 🎉 You've just automated your first browser test.
```
### 🎯 Try Our Example Tests
> **Note**: If you installed from PyPI, first download the examples:
> ```bash
> # Download examples
> curl -O https://raw.githubusercontent.com/smiao-icims/browser-pilot/main/examples/saucedemo-shopping.md
> curl -O https://raw.githubusercontent.com/smiao-icims/browser-pilot/main/examples/google-ai-search.md
> ```
#### E-commerce Shopping Flow
```bash
# Run a complete shopping cart test
browser-pilot saucedemo-shopping.md
# Or from source repository:
uv run browser-pilot examples/saucedemo-shopping.md
```
This example demonstrates:
- Login with test credentials
- Adding products to cart
- Checkout process with form filling
- Order confirmation
#### AI-Powered Search
```bash
# Test Google's AI search features
browser-pilot google-ai-search.md
# Or from source repository:
uv run browser-pilot examples/google-ai-search.md
```
This example shows:
- Navigating to Google
- Using AI-powered search
- Verifying AI-generated responses
- Taking screenshots of results
👉 **Check out more examples in the `examples/` directory!**
### 💡 Pro Tips for Quick Success
```bash
# Save typing with an alias
alias bp="browser-pilot" # For PyPI installation
# or
alias bp="uv run browser-pilot" # For source installation
# Run any test headless
bp your-test.md --headless
# Get beautiful HTML reports
bp your-test.md --output-format html --output-file report.html
# Save money with token optimization
bp your-test.md --compression-level high # 30% less tokens!
# Debug failing tests
bp failing-test.md --verbose --save-trace
```
👉 **[See More Examples](docs/COMMON_USE_CASES.md)** | 📘 **[Full Quick Start Guide](docs/QUICK_START.md)**
## 📝 Writing Tests
Tests are written in simple markdown format with numbered steps:
```markdown
# Login Test
1. Navigate to https://example.com/login
2. Click on the email input field
3. Type "user@example.com"
4. Click on the password field
5. Type "securepassword123"
6. Click the "Login" button
7. Verify that the dashboard page is displayed
8. Take a screenshot of the dashboard
```
## 📊 Example Output
```
╔═══════════════════════════════════════════╗
║ Browser Pilot v2.0 ║
║ Simple • Reliable • Token Efficient ║
╚═══════════════════════════════════════════╝
📄 Test Suite: login_test.md
Size: 245 chars
🤖 Provider: github_copilot
Model: gpt-4o
🚀 Executing test...
Browser: chromium
Mode: Headed
--------------------------------------------------
Status: ✅ PASSED
Duration: 28.3s
Steps: 15
📊 Token Usage:
Total: 12,847
Prompt: 12,214
Completion: 633
Cost: $0.0421
💡 Token Optimization:
Reduction: 23.5%
Tokens Saved: 3,200
Cost Savings: $0.0096
Strategies: whitespace, phrases, redundancy
📝 Results saved:
- report: report_20250726_173422.md
- results: results_20250726_173422.json
```
## 🆕 New Features in v2.0
### 🔍 Enhanced Verbose Mode
```bash
# Enable detailed step-by-step logging
browser-pilot test.md --verbose
# Logs are saved to ~/.browser_pilot/logs/
# Both console and file output for debugging
```
### 💰 Token Optimization
```bash
# Control optimization level
browser-pilot test.md --compression-level high # 30% reduction
browser-pilot test.md --compression-level medium # 20% reduction (default)
browser-pilot test.md --compression-level low # 10% reduction
browser-pilot test.md --no-token-optimization # Disable
```
### 📤 Flexible Output Options
```bash
# Different output formats
browser-pilot test.md --output-format json
browser-pilot test.md --output-format yaml
browser-pilot test.md --output-format xml
browser-pilot test.md --output-format junit
browser-pilot test.md --output-format html
browser-pilot test.md --output-format markdown
# Output to file instead of console
browser-pilot test.md --output-file results.json
```
### 🎛️ Custom System Prompts
```bash
# Use custom instructions
browser-pilot test.md --system-prompt custom-prompt.txt
# Example prompt file:
cat > prompt.txt << EOF
You are a meticulous QA engineer.
Always take screenshots before and after actions.
Wait 2 seconds after each navigation.
EOF
```
### 🔧 Configuration Management
```bash
# Save current settings as defaults
browser-pilot test.md --provider openai --model gpt-4 --save-config
# Use custom config file
browser-pilot test.md --config my-config.json
# Environment variables (override config file)
export BROWSER_PILOT_PROVIDER=anthropic
export BROWSER_PILOT_MODEL=claude-3-opus
export BROWSER_PILOT_BROWSER=firefox
```
## 🔧 Configuration
### Prerequisites
1. **Python 3.11+** (required by ModelForge)
2. **Node.js** (for Playwright MCP server)
3. **uv** - Fast Python package installer and resolver
4. **ModelForge** configured with at least one LLM provider
### Command Line Options
```
positional arguments:
test_scenario Test scenario file path or '-' for stdin
options:
-h, --help Show help message
--provider PROVIDER LLM provider (uses ModelForge discovery if not specified)
--model MODEL Model name (uses provider default if not specified)
--browser BROWSER Browser: chromium, chrome, firefox, safari, edge
--headless Run browser in headless mode
--viewport-width W Browser viewport width (default: 1920)
--viewport-height H Browser viewport height (default: 1080)
-v, --verbose Enable verbose output with step-by-step debugging
-q, --quiet Suppress all output except errors
--output-format FMT Output format: json, yaml, xml, junit, html, markdown
--output-file FILE Save results to file (stdout if not specified)
--system-prompt FILE Custom system prompt file
--timeout SECONDS Test execution timeout
--retry COUNT Number of retries on failure
--no-screenshots Disable screenshot capture
--no-token-optimization Disable token optimization
--config FILE Path to configuration file
--save-config Save current settings as defaults
```
### Setting up ModelForge
```bash
# ModelForge is already installed with Browser Pilot (via model-forge-llm package)
# Just configure a provider:
# Configure a provider (e.g., GitHub Copilot)
modelforge config add --provider github_copilot --model gpt-4o
# Check configuration
modelforge config show
```
## 📁 Project Structure
```
browser-pilot/
├── browser_pilot/ # Main package
│ ├── __init__.py
│ ├── __main__.py # CLI entry point
│ ├── core.py # Core automation engine
│ ├── cli.py # Command-line interface
│ ├── reporter.py # Report generation
│ ├── config_manager.py # Configuration management
│ ├── storage_manager.py # Local storage handling
│ ├── io_handlers.py # Input/output formatting
│ ├── verbose_logger.py # Enhanced logging
│ ├── token_optimizer.py # Token optimization
│ └── test_enhancer.py # Test suite enhancement
├── examples/ # Example test suites
│ ├── google-ai-search.md # Google AI search test
│ └── saucedemo-shopping.md # E-commerce shopping cart test
├── docs/ # Documentation
│ └── specs/ # Technical specifications
└── tests/ # Unit tests
```
## 📂 Local Storage
Browser Pilot stores data in platform-specific locations:
- **macOS**: `~/Library/Application Support/browser_pilot/`
- **Windows**: `%LOCALAPPDATA%\browser_pilot\`
- **Linux**: `~/.browser_pilot/`
Storage structure:
```
~/.browser_pilot/
├── logs/ # Verbose execution logs
├── settings/ # Configuration files
├── reports/ # Test reports
├── screenshots/ # Captured screenshots
├── cache/ # Temporary files
└── memory/ # Future: persistent memory
## 🎓 Learn More
- 📘 **[Quick Start Guide](docs/QUICK_START.md)** - Get running in 5 minutes
- 🧙 **[Configuration Wizard Guide](docs/WIZARD_GUIDE.md)** - Interactive setup walkthrough
- 🎯 **[Common Use Cases](docs/COMMON_USE_CASES.md)** - Real-world testing examples
- 🔍 **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Solve common issues
- 🛠️ **[Configuration Guide](docs/CONFIGURATION.md)** - Advanced configuration
- 📊 **[Performance Guide](docs/PERFORMANCE.md)** - Optimization tips
## 🌟 Example Test Suites
Learn from our comprehensive examples in the `examples/` directory:
### 🛒 `saucedemo-shopping.md`
Complete e-commerce workflow including:
- User authentication
- Product browsing and selection
- Shopping cart management
- Multi-step checkout process
- Order confirmation
### 🔍 `google-ai-search.md`
AI-powered search testing:
- Google AI mode activation
- Search query execution
- AI response validation
- Screenshot capture
- Different search scenarios
Run any example:
```bash
# With PyPI installation (after downloading examples):
browser-pilot saucedemo-shopping.md
browser-pilot google-ai-search.md --headless
# With source installation:
uv run browser-pilot examples/saucedemo-shopping.md
uv run browser-pilot examples/google-ai-search.md --headless
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Install with dev dependencies
uv sync --extra dev
# Run tests
uv run pytest
# Run linting
uv run ruff check .
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with [LangChain](https://github.com/langchain-ai/langchain) and [LangGraph](https://github.com/langchain-ai/langgraph)
- Browser automation powered by [Playwright](https://playwright.dev/) via [MCP](https://github.com/modelcontextprotocol)
- LLM management by [ModelForge](https://github.com/smiao-icims/model-forge)
---
<p align="center">
<strong>Browser Pilot</strong> - Making browser testing as easy as writing a todo list 📝
<br>
Made with ❤️ by the Browser Pilot Team
</p>
Raw data
{
"_id": null,
"home_page": null,
"name": "browser-pilot-llm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "ai, automation, browser, llm, playwright, testing",
"author": null,
"author_email": "Browser Pilot Team <browser-pilot@example.com>",
"download_url": "https://files.pythonhosted.org/packages/e5/64/8b1d2b965a97a57aaa982799f20eeb0a6bca0dd6b9dbd364f9b38ef370c9/browser_pilot_llm-1.0.1.tar.gz",
"platform": null,
"description": "# Browser Pilot \ud83c\udfaf\n\nA streamlined browser automation framework that uses AI-powered agents to execute natural language test scenarios.\n\n[](https://www.python.org/downloads/)\n[](https://pypi.org/project/browser-pilot-llm/)\n[](https://github.com/smiao-icims/browser-pilot/actions)\n[](LICENSE)\n[](https://codecov.io/gh/smiao-icims/browser-pilot)\n\n## \ud83c\udfaf Getting Started in 3 Minutes\n\n### Option 1: Install from PyPI (Recommended)\n```bash\n# 1. Install Browser Pilot from PyPI\npip install browser-pilot-llm\n\n# 2. Run the setup wizard (2 minutes)\nbrowser-pilot --setup-wizard\n\n# 3. Create a test file (test.md)\ncat > test.md << 'EOF'\n# My First Test\n1. Go to https://www.google.com\n2. Search for \"Browser Pilot AI testing\"\n3. Click on the first result\n4. Take a screenshot\nEOF\n\n# 4. Run your test!\nbrowser-pilot test.md\n```\n\n### Option 2: Install from Source\n```bash\n# 1. Clone and install\ngit clone https://github.com/smiao-icims/browser-pilot.git\ncd browser-pilot\nuv sync\n\n# 2. Run the setup wizard\nuv run browser-pilot --setup-wizard\n\n# 3. Create and run your test\nuv run browser-pilot test.md\n```\n\nThat's it! You've just automated your first browser test. \ud83c\udf89\n\n## \u2728 Features\n\n- \ud83e\udd16 **AI-Powered**: Uses LLMs to understand and execute test instructions written in plain English\n- \ud83c\udfaf **Simple**: Write tests in markdown - no coding required\n- \ud83d\ude80 **Efficient**: Single agent architecture with token optimization (20-30% reduction)\n- \ud83d\udd27 **Flexible**: Supports multiple LLM providers via [ModelForge](https://github.com/smiao-icims/model-forge) ([PyPI](https://pypi.org/project/model-forge-llm/))\n- \ud83d\udcca **Insightful**: Enhanced reports with timing, token usage, and cost analysis\n- \ud83c\udf10 **Cross-Browser**: Supports Chromium, Chrome, Firefox, Safari, Edge, and WebKit\n- \ud83d\udd0d **Verbose Mode**: Step-by-step debugging with dual console/file logging\n- \ud83d\udcb0 **Cost Optimization**: Built-in token optimization to reduce API costs\n- \ud83d\udcdd **Multiple Formats**: Export results as JSON, YAML, XML, JUnit, HTML, or Markdown\n- \ud83c\udf9b\ufe0f **Customizable**: System prompts, browser settings, and optimization levels\n- \ud83e\uddd9 **Setup Wizard**: Interactive configuration with arrow-key navigation\n\n## \ud83d\ude80 Quick Start - Get Testing in 3 Minutes!\n\n### 1\ufe0f\u20e3 Install Browser Pilot\n\n#### Option A: Install from PyPI (Recommended)\n```bash\n# Install with pip\npip install browser-pilot-llm\n\n# Or with uv (faster)\nuv pip install browser-pilot-llm\n```\n\n#### Option B: Install from Source\n```bash\n# Clone and install\ngit clone https://github.com/smiao-icims/browser-pilot.git\ncd browser-pilot\ncurl -LsSf https://astral.sh/uv/install.sh | sh # Install uv if needed\nuv sync # Install dependencies\n```\n\n### 2\ufe0f\u20e3 Run Setup Wizard (2 minutes)\n\n```bash\n# If installed from PyPI:\nbrowser-pilot --setup-wizard\n\n# If installed from source:\nuv run browser-pilot --setup-wizard\n```\n\nThe wizard will guide you through:\n- \ud83e\udd16 Selecting an LLM provider (GitHub Copilot recommended - no API key!)\n- \ud83d\udd10 Authentication setup\n- \ud83c\udf10 Browser configuration\n- \u2705 Validation with a test prompt\n\n### 3\ufe0f\u20e3 Create Your First Test\n\nCreate a file `my-test.md` with natural language instructions:\n\n```markdown\n# My First Test\n\n1. Navigate to https://www.wikipedia.org\n2. Search for \"artificial intelligence\"\n3. Verify the page shows results about AI\n4. Take a screenshot\n```\n\n### 4\ufe0f\u20e3 Run Your Test!\n\n```bash\n# If installed from PyPI:\nbrowser-pilot my-test.md\n\n# If installed from source:\nuv run browser-pilot my-test.md\n\n# That's it! \ud83c\udf89 You've just automated your first browser test.\n```\n\n### \ud83c\udfaf Try Our Example Tests\n\n> **Note**: If you installed from PyPI, first download the examples:\n> ```bash\n> # Download examples\n> curl -O https://raw.githubusercontent.com/smiao-icims/browser-pilot/main/examples/saucedemo-shopping.md\n> curl -O https://raw.githubusercontent.com/smiao-icims/browser-pilot/main/examples/google-ai-search.md\n> ```\n\n#### E-commerce Shopping Flow\n```bash\n# Run a complete shopping cart test\nbrowser-pilot saucedemo-shopping.md\n\n# Or from source repository:\nuv run browser-pilot examples/saucedemo-shopping.md\n```\n\nThis example demonstrates:\n- Login with test credentials\n- Adding products to cart\n- Checkout process with form filling\n- Order confirmation\n\n#### AI-Powered Search\n```bash\n# Test Google's AI search features\nbrowser-pilot google-ai-search.md\n\n# Or from source repository:\nuv run browser-pilot examples/google-ai-search.md\n```\n\nThis example shows:\n- Navigating to Google\n- Using AI-powered search\n- Verifying AI-generated responses\n- Taking screenshots of results\n\n\ud83d\udc49 **Check out more examples in the `examples/` directory!**\n\n### \ud83d\udca1 Pro Tips for Quick Success\n\n```bash\n# Save typing with an alias\nalias bp=\"browser-pilot\" # For PyPI installation\n# or\nalias bp=\"uv run browser-pilot\" # For source installation\n\n# Run any test headless\nbp your-test.md --headless\n\n# Get beautiful HTML reports\nbp your-test.md --output-format html --output-file report.html\n\n# Save money with token optimization\nbp your-test.md --compression-level high # 30% less tokens!\n\n# Debug failing tests\nbp failing-test.md --verbose --save-trace\n```\n\n\n\ud83d\udc49 **[See More Examples](docs/COMMON_USE_CASES.md)** | \ud83d\udcd8 **[Full Quick Start Guide](docs/QUICK_START.md)**\n\n## \ud83d\udcdd Writing Tests\n\nTests are written in simple markdown format with numbered steps:\n\n```markdown\n# Login Test\n\n1. Navigate to https://example.com/login\n2. Click on the email input field\n3. Type \"user@example.com\"\n4. Click on the password field \n5. Type \"securepassword123\"\n6. Click the \"Login\" button\n7. Verify that the dashboard page is displayed\n8. Take a screenshot of the dashboard\n```\n\n## \ud83d\udcca Example Output\n\n```\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n\u2551 Browser Pilot v2.0 \u2551\n\u2551 Simple \u2022 Reliable \u2022 Token Efficient \u2551\n\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255d\n\n\ud83d\udcc4 Test Suite: login_test.md\n Size: 245 chars\n\n\ud83e\udd16 Provider: github_copilot\n Model: gpt-4o\n\n\ud83d\ude80 Executing test...\n Browser: chromium\n Mode: Headed\n\n--------------------------------------------------\nStatus: \u2705 PASSED\nDuration: 28.3s\nSteps: 15\n\n\ud83d\udcca Token Usage:\n Total: 12,847\n Prompt: 12,214\n Completion: 633\n Cost: $0.0421\n\n\ud83d\udca1 Token Optimization:\n Reduction: 23.5%\n Tokens Saved: 3,200\n Cost Savings: $0.0096\n Strategies: whitespace, phrases, redundancy\n\n\ud83d\udcdd Results saved:\n - report: report_20250726_173422.md\n - results: results_20250726_173422.json\n```\n\n## \ud83c\udd95 New Features in v2.0\n\n### \ud83d\udd0d Enhanced Verbose Mode\n```bash\n# Enable detailed step-by-step logging\nbrowser-pilot test.md --verbose\n\n# Logs are saved to ~/.browser_pilot/logs/\n# Both console and file output for debugging\n```\n\n### \ud83d\udcb0 Token Optimization\n```bash\n# Control optimization level\nbrowser-pilot test.md --compression-level high # 30% reduction\nbrowser-pilot test.md --compression-level medium # 20% reduction (default)\nbrowser-pilot test.md --compression-level low # 10% reduction\nbrowser-pilot test.md --no-token-optimization # Disable\n```\n\n### \ud83d\udce4 Flexible Output Options\n```bash\n# Different output formats\nbrowser-pilot test.md --output-format json\nbrowser-pilot test.md --output-format yaml\nbrowser-pilot test.md --output-format xml\nbrowser-pilot test.md --output-format junit\nbrowser-pilot test.md --output-format html\nbrowser-pilot test.md --output-format markdown\n\n# Output to file instead of console\nbrowser-pilot test.md --output-file results.json\n```\n\n### \ud83c\udf9b\ufe0f Custom System Prompts\n```bash\n# Use custom instructions\nbrowser-pilot test.md --system-prompt custom-prompt.txt\n\n# Example prompt file:\ncat > prompt.txt << EOF\nYou are a meticulous QA engineer. \nAlways take screenshots before and after actions.\nWait 2 seconds after each navigation.\nEOF\n```\n\n### \ud83d\udd27 Configuration Management\n```bash\n# Save current settings as defaults\nbrowser-pilot test.md --provider openai --model gpt-4 --save-config\n\n# Use custom config file\nbrowser-pilot test.md --config my-config.json\n\n# Environment variables (override config file)\nexport BROWSER_PILOT_PROVIDER=anthropic\nexport BROWSER_PILOT_MODEL=claude-3-opus\nexport BROWSER_PILOT_BROWSER=firefox\n```\n\n## \ud83d\udd27 Configuration\n\n### Prerequisites\n\n1. **Python 3.11+** (required by ModelForge)\n2. **Node.js** (for Playwright MCP server)\n3. **uv** - Fast Python package installer and resolver\n4. **ModelForge** configured with at least one LLM provider\n\n### Command Line Options\n\n```\npositional arguments:\n test_scenario Test scenario file path or '-' for stdin\n\noptions:\n -h, --help Show help message\n --provider PROVIDER LLM provider (uses ModelForge discovery if not specified)\n --model MODEL Model name (uses provider default if not specified)\n --browser BROWSER Browser: chromium, chrome, firefox, safari, edge\n --headless Run browser in headless mode\n --viewport-width W Browser viewport width (default: 1920)\n --viewport-height H Browser viewport height (default: 1080)\n -v, --verbose Enable verbose output with step-by-step debugging\n -q, --quiet Suppress all output except errors\n --output-format FMT Output format: json, yaml, xml, junit, html, markdown\n --output-file FILE Save results to file (stdout if not specified)\n --system-prompt FILE Custom system prompt file\n --timeout SECONDS Test execution timeout\n --retry COUNT Number of retries on failure\n --no-screenshots Disable screenshot capture\n --no-token-optimization Disable token optimization\n --config FILE Path to configuration file\n --save-config Save current settings as defaults\n```\n\n### Setting up ModelForge\n\n```bash\n# ModelForge is already installed with Browser Pilot (via model-forge-llm package)\n# Just configure a provider:\n\n# Configure a provider (e.g., GitHub Copilot)\nmodelforge config add --provider github_copilot --model gpt-4o\n\n# Check configuration\nmodelforge config show\n```\n\n## \ud83d\udcc1 Project Structure\n\n```\nbrowser-pilot/\n\u251c\u2500\u2500 browser_pilot/ # Main package\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 __main__.py # CLI entry point\n\u2502 \u251c\u2500\u2500 core.py # Core automation engine\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u251c\u2500\u2500 reporter.py # Report generation\n\u2502 \u251c\u2500\u2500 config_manager.py # Configuration management\n\u2502 \u251c\u2500\u2500 storage_manager.py # Local storage handling\n\u2502 \u251c\u2500\u2500 io_handlers.py # Input/output formatting\n\u2502 \u251c\u2500\u2500 verbose_logger.py # Enhanced logging\n\u2502 \u251c\u2500\u2500 token_optimizer.py # Token optimization\n\u2502 \u2514\u2500\u2500 test_enhancer.py # Test suite enhancement\n\u251c\u2500\u2500 examples/ # Example test suites\n\u2502 \u251c\u2500\u2500 google-ai-search.md # Google AI search test\n\u2502 \u2514\u2500\u2500 saucedemo-shopping.md # E-commerce shopping cart test\n\u251c\u2500\u2500 docs/ # Documentation\n\u2502 \u2514\u2500\u2500 specs/ # Technical specifications\n\u2514\u2500\u2500 tests/ # Unit tests\n```\n\n## \ud83d\udcc2 Local Storage\n\nBrowser Pilot stores data in platform-specific locations:\n\n- **macOS**: `~/Library/Application Support/browser_pilot/`\n- **Windows**: `%LOCALAPPDATA%\\browser_pilot\\`\n- **Linux**: `~/.browser_pilot/`\n\nStorage structure:\n```\n~/.browser_pilot/\n\u251c\u2500\u2500 logs/ # Verbose execution logs\n\u251c\u2500\u2500 settings/ # Configuration files\n\u251c\u2500\u2500 reports/ # Test reports\n\u251c\u2500\u2500 screenshots/ # Captured screenshots\n\u251c\u2500\u2500 cache/ # Temporary files\n\u2514\u2500\u2500 memory/ # Future: persistent memory\n\n## \ud83c\udf93 Learn More\n\n- \ud83d\udcd8 **[Quick Start Guide](docs/QUICK_START.md)** - Get running in 5 minutes\n- \ud83e\uddd9 **[Configuration Wizard Guide](docs/WIZARD_GUIDE.md)** - Interactive setup walkthrough\n- \ud83c\udfaf **[Common Use Cases](docs/COMMON_USE_CASES.md)** - Real-world testing examples\n- \ud83d\udd0d **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Solve common issues\n- \ud83d\udee0\ufe0f **[Configuration Guide](docs/CONFIGURATION.md)** - Advanced configuration\n- \ud83d\udcca **[Performance Guide](docs/PERFORMANCE.md)** - Optimization tips\n\n## \ud83c\udf1f Example Test Suites\n\nLearn from our comprehensive examples in the `examples/` directory:\n\n### \ud83d\uded2 `saucedemo-shopping.md`\nComplete e-commerce workflow including:\n- User authentication\n- Product browsing and selection\n- Shopping cart management\n- Multi-step checkout process\n- Order confirmation\n\n### \ud83d\udd0d `google-ai-search.md`\nAI-powered search testing:\n- Google AI mode activation\n- Search query execution\n- AI response validation\n- Screenshot capture\n- Different search scenarios\n\nRun any example:\n```bash\n# With PyPI installation (after downloading examples):\nbrowser-pilot saucedemo-shopping.md\nbrowser-pilot google-ai-search.md --headless\n\n# With source installation:\nuv run browser-pilot examples/saucedemo-shopping.md\nuv run browser-pilot examples/google-ai-search.md --headless\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n```bash\n# Install with dev dependencies\nuv sync --extra dev\n\n# Run tests\nuv run pytest\n\n# Run linting\nuv run ruff check .\n```\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Built with [LangChain](https://github.com/langchain-ai/langchain) and [LangGraph](https://github.com/langchain-ai/langgraph)\n- Browser automation powered by [Playwright](https://playwright.dev/) via [MCP](https://github.com/modelcontextprotocol)\n- LLM management by [ModelForge](https://github.com/smiao-icims/model-forge)\n\n---\n\n<p align=\"center\">\n <strong>Browser Pilot</strong> - Making browser testing as easy as writing a todo list \ud83d\udcdd\n <br>\n Made with \u2764\ufe0f by the Browser Pilot Team\n</p>",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI-powered browser test automation framework",
"version": "1.0.1",
"project_urls": {
"Bug Reports": "https://github.com/smiao-icims/browser-pilot/issues",
"Documentation": "https://github.com/smiao-icims/browser-pilot#readme",
"Homepage": "https://github.com/smiao-icims/browser-pilot",
"Source": "https://github.com/smiao-icims/browser-pilot"
},
"split_keywords": [
"ai",
" automation",
" browser",
" llm",
" playwright",
" testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f0854038591101726215a8f09044c38d82efe61ff1385a8bb2a720c5b13309e3",
"md5": "2d4949529c180b98dcb4626b5891e56c",
"sha256": "29b597efc19d2892964e1f3d0453c44c30a0a1ec0e547da4503b6094fc5d767e"
},
"downloads": -1,
"filename": "browser_pilot_llm-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d4949529c180b98dcb4626b5891e56c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 70883,
"upload_time": "2025-07-28T18:43:22",
"upload_time_iso_8601": "2025-07-28T18:43:22.350585Z",
"url": "https://files.pythonhosted.org/packages/f0/85/4038591101726215a8f09044c38d82efe61ff1385a8bb2a720c5b13309e3/browser_pilot_llm-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e5648b1d2b965a97a57aaa982799f20eeb0a6bca0dd6b9dbd364f9b38ef370c9",
"md5": "d50f466b9b47253c14bd24f7c9411c67",
"sha256": "b7aca8bbb16368792f65738245a1f29da6cc569581c42db649d9c254d7e09435"
},
"downloads": -1,
"filename": "browser_pilot_llm-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d50f466b9b47253c14bd24f7c9411c67",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 300126,
"upload_time": "2025-07-28T18:43:24",
"upload_time_iso_8601": "2025-07-28T18:43:24.088450Z",
"url": "https://files.pythonhosted.org/packages/e5/64/8b1d2b965a97a57aaa982799f20eeb0a6bca0dd6b9dbd364f9b38ef370c9/browser_pilot_llm-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 18:43:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "smiao-icims",
"github_project": "browser-pilot",
"github_not_found": true,
"lcname": "browser-pilot-llm"
}
JSON
