vibetest 0.3.1
Browser-agent QA swarm with MCP interface for testing AI-generated websites
Requires Python: >=3.9
Keywords: testing, browser, automation, qa, mcp

<div align="center">

# 🚀 Vibetest

<div align="center">
  <a href="README.md">🇺🇸 English</a> |
  <a href="README_zh.md">🇨🇳 中文</a>
</div>

<br>

[![PyPI version](https://badge.fury.io/py/vibetest.svg)](https://badge.fury.io/py/vibetest)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub Actions](https://github.com/im47cn/vibetest/workflows/Tests/badge.svg)](https://github.com/im47cn/vibetest/actions)

**🤖 Intelligent MCP-Powered Website Testing Platform**

*Advanced MCP tools that enable intelligent browser testing without requiring LLM API keys - let your MCP client be the brain!*

[📦 Installation](#-installation) • [🚀 Quick Start](#-quick-start) • [📖 Usage](#-usage) • [🎯 Examples](#-examples) • [🔧 Configuration](#-configuration)

</div>

---

## ✨ What is Vibetest Use?

**Vibetest** is a revolutionary **Model Control Protocol (MCP)** server that provides intelligent browser testing tools without requiring LLM API keys. Instead of running its own AI models, it empowers your MCP client to be the intelligent decision-maker, using a suite of powerful testing tools.

### 🎯 Key Features

- 🧠 **MCP Client Intelligence**: Your MCP client acts as the testing expert using our tools
- 🔧 **No LLM Dependencies**: No API keys required - works entirely through MCP tools
- 🌐 **Universal Compatibility**: Test any website - production, staging, or localhost
- 🔍 **Smart Page Analysis**: Automatically discover and analyze page elements
- 🎯 **Intelligent Test Generation**: Generate targeted test cases based on page structure
- 🤖 **Automated Browser Actions**: Execute clicks, inputs, and navigation seamlessly
- ♿ **Accessibility Testing**: Built-in WCAG compliance checking
- 📊 **Comprehensive Analysis**: Detailed test result analysis and reporting
- 📸 **Visual Documentation**: Screenshot capture for test documentation
- ⚡ **High Performance**: Fast, efficient testing without external API calls

https://github.com/user-attachments/assets/9558d051-78bc-45fd-8694-9ac80eaf9494

---

## 📦 Installation

### Recommended: Using uvx (fastest)

[uvx](https://github.com/astral-sh/uv) is the fastest way to run Python tools without installation conflicts:

```bash
# Run vibetest directly (no installation needed)
uvx vibetest

# Or install globally for repeated use
uvx --global vibetest
```

**Why uvx?**
- ⚡ **Instant execution** - No virtual environment setup
- 🔒 **Isolated dependencies** - No conflicts with your system
- 🚀 **Always latest version** - Automatically uses the newest release

### Alternative: Using pip

```bash
pip install vibetest
```

### Prerequisites

- **Python 3.11+** - Modern Python version required
- **MCP-Compatible Client** - Claude Desktop, Cursor, or any MCP-enabled environment
- **Browser Dependencies** - Automatically installed with the package

**🎉 No API Keys Required!** - The new MCP architecture works entirely through your MCP client's intelligence.

---

## 🚀 Quick Start

### Step 1: Install Vibetest

```bash
# Recommended: Using uvx (fastest)
uvx vibetest

# Alternative: Using pip
pip install vibetest
```

### Step 2: Configure Your MCP Client

Choose your preferred MCP client and follow the configuration:

#### 🤖 Claude Desktop (Recommended)

**Automatic Configuration:**
```bash
# Add MCP server automatically
claude mcp add vibetest vibetest

# Verify connection
claude
> /mcp
  ⎿  MCP Server Status
     • vibetest: ✅ connected (6 tools available)
```

**Manual Configuration:**
1. Open Claude Desktop config file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. Add vibetest configuration:
```json
{
  "mcpServers": {
    "vibetest": {
      "command": "uvx",
      "args": ["vibetest"]
    }
  }
}
```

3. Restart Claude Desktop

#### 🎯 Cursor IDE

1. **Open Cursor Settings** → **Extensions** → **MCP**
2. **Add server configuration:**

```json
{
  "mcpServers": {
    "vibetest": {
      "command": "uvx",
      "args": ["vibetest"],
      "env": {
        "BROWSER_USE_LOGGING_LEVEL": "INFO"
      }
    }
  }
}
```

3. **Restart Cursor** and start testing!

#### 🔌 Cline (VSCode Extension)

1. **Install Cline** from VSCode marketplace
2. **Configure MCP server** in Cline settings:

```json
{
  "mcpServers": {
    "vibetest": {
      "command": "uvx",
      "args": ["vibetest"]
    }
  }
}
```

3. **Use in VSCode**: `@vibetest test my website`

### Step 3: Verify Installation

In your MCP client:
```text
> /mcp

Expected output:
✅ vibetest: connected
   • browser_scout - Analyze website structure
   • generate_test_tasks - Create test plans
   • execute_browser_action - Run browser actions
   • analyze_test_results - Analyze test results
   • get_page_screenshot - Capture screenshots
   • run_mcp_test_session - Complete testing session
```

---

## 📖 Usage

### 🎯 New MCP Tools Architecture

Vibetest Use now provides intelligent MCP tools that work with your MCP client's intelligence:

#### Available MCP Tools

| Tool | Purpose | Usage |
|------|---------|-------|
| `browser_scout` | Analyze page structure | Scout any website to identify interactive elements |
| `generate_test_tasks` | Create test plans | Generate targeted test cases based on page analysis |
| `execute_browser_action` | Run browser actions | Execute clicks, inputs, and navigation |
| `analyze_test_results` | Analyze results | Generate comprehensive test reports |
| `get_page_screenshot` | Capture screenshots | Document testing with visual evidence |
| `run_mcp_test_session` | Complete testing | One-click comprehensive testing |

#### Basic Usage Commands

```text
🌐 Complete Website Testing
> Use run_mcp_test_session to test https://example.com with 10 tests

🔍 Detailed Analysis
> First use browser_scout on localhost:3000, then generate_test_tasks, and execute each test

🎯 Focused Testing
> Test the navigation and forms on my staging site using the MCP tools

📊 Custom Analysis
> Scout my website, generate accessibility-focused tests, and provide a detailed report
```

#### Advanced MCP Workflow

```text
1. Scout the website structure
2. Generate targeted test tasks
3. Execute browser actions systematically
4. Analyze results comprehensively
5. Generate actionable reports
```

---

## 🎯 Examples

### E-commerce Site Testing

```text
> Use run_mcp_test_session to test my e-commerce site https://mystore.com
  with focus on navigation and forms, using 8 tests in non-headless mode
```

### Mobile App Testing

```text
> Scout my mobile app at https://app.example.com, then generate responsive
  tests and execute them with detailed accessibility analysis
```

### Accessibility Audit

```text
> Perform comprehensive accessibility testing on localhost:3000:
  1. Use browser_scout to analyze the page
  2. Generate accessibility-focused test tasks
  3. Execute each test and analyze results
  4. Provide detailed WCAG compliance report
```

### Performance Testing

```text
> Test my website performance:
  1. Take screenshots before and after interactions
  2. Measure response times for key actions
  3. Analyze loading behavior and user experience
```

---

## 🔧 Configuration

### MCP Client Configuration

Vibetest works as an MCP server that provides intelligent testing tools to your MCP client. No API keys required!

#### 📋 Complete Configuration Guide

For detailed setup instructions for all MCP clients, see our **[MCP Client Configuration Guide](docs/mcp-client-configuration.md)**.

#### 🚀 Quick Configuration Reference

| MCP Client | Configuration File | Command |
|------------|-------------------|---------|
| **Claude Desktop** | `claude_desktop_config.json` | `uvx vibetest` |
| **Cursor IDE** | Cursor MCP Settings | `uvx vibetest` |
| **Cline (VSCode)** | Cline Extension Settings | `uvx vibetest` |
| **Custom Clients** | Client-specific config | `python -m vibetest.mcp_server` |

#### 🔧 Standard MCP Configuration

```json
{
  "mcpServers": {
    "vibetest": {
      "command": "uvx",
      "args": ["vibetest"],
      "env": {
        "BROWSER_USE_LOGGING_LEVEL": "INFO",
        "ANONYMIZED_TELEMETRY": "false"
      }
    }
  }
}
```

#### 🛠️ Alternative Configuration (pip installation)

```json
{
  "mcpServers": {
    "vibetest": {
      "command": "python",
      "args": ["-m", "vibetest.mcp_server"],
      "env": {
        "BROWSER_USE_LOGGING_LEVEL": "INFO"
      }
    }
  }
}
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `BROWSER_USE_LOGGING_LEVEL` | `INFO` | Browser automation logging level |
| `ANONYMIZED_TELEMETRY` | `true` | Enable/disable anonymous telemetry |

### MCP Tools Parameters

Each tool accepts specific parameters for customization:

#### `browser_scout`
```text
- url: Target website URL (required)
- headless: Browser visibility (default: true)
```

#### `generate_test_tasks`
```text
- page_info: Output from browser_scout (required)
- focus_areas: ['navigation', 'forms', 'accessibility', 'interaction']
```

#### `execute_browser_action`
```text
- url: Target website URL (required)
- task: Test task object (required)
- headless: Browser visibility (default: true)
```

#### `run_mcp_test_session`
```text
- url: Target website URL (required)
- num_tests: Number of tests (default: 10)
- headless: Browser visibility (default: false)
- focus_areas: Test focus areas (optional)
```

### Troubleshooting

#### Common Issues

1. **"Command not found: vibetest"**
   ```bash
   pip install vibetest
   # Or use full path in config
   ```

2. **"MCP server connection failed"**
   ```bash
   # Test manually
   python -m vibetest.mcp_server
   ```

3. **"Browser dependencies missing"**
   ```bash
   playwright install chromium
   ```

For detailed troubleshooting, see our [Configuration Guide](docs/mcp-client-configuration.md#-troubleshooting).

---

## 🎬 Full Demo

https://github.com/user-attachments/assets/6450b5b7-10e5-4019-82a4-6d726dbfbe1f

---

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📚 Documentation

For comprehensive documentation, visit our [docs directory](docs/):

### 🚀 Getting Started
- **[MCP Client Configuration](docs/mcp-client-configuration.md)** - Complete setup guide for all MCP clients
- **[MCP Tools Examples](docs/mcp-tools-examples.md)** - Practical examples and usage patterns
- **[MCP Client Prompts](docs/mcp-client-prompts.md)** - Optimized prompts for better testing

### 📖 Reference
- **[API Documentation](docs/api-reference.md)** - Complete MCP tools reference
- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project
- **[Changelog](CHANGELOG.md)** - Version history and release notes
- **[Documentation Index](docs/README.md)** - Complete documentation overview

### 🌐 Languages
All major documentation is available in both English and Chinese.

### Development Setup

```bash
git clone https://github.com/im47cn/vibetest.git
cd vibetest
pip install -e ".[dev]"
pytest
```

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Powered by [Browser Use](https://github.com/browser-use/browser-use) - Advanced browser automation
- Built with [MCP Protocol](https://modelcontextprotocol.io/) - Intelligent analysis through your MCP client
- Supports [Model Control Protocol](https://modelcontextprotocol.io/) - Seamless AI integration

---

<div align="center">

**Made with ❤️ for developers who care about quality**

[⭐ Star us on GitHub](https://github.com/im47cn/vibetest) • [🐛 Report Issues](https://github.com/im47cn/vibetest/issues) • [💬 Join Discussions](https://github.com/im47cn/vibetest/discussions)

</div>