vibeq 1.0.1
Universal AI-native test automation that works on ANY website - no hardcoded selectors, self-healing, production-ready
Requires Python: >=3.8
Keywords: testing, automation, selenium, playwright, webdriver, bidi, ai, self-healing

# VibeQ - Universal AI Test Automation 🚀

[![PyPI version](https://badge.fury.io/py/vibeq.svg)](https://badge.fury.io/py/vibeq)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**The first truly universal test automation framework that works on ANY website without hardcoded selectors.**

## 🌟 What Makes VibeQ Different

- **🌐 Universal**: Works on diverse websites without modification
- **🧠 AI-Native**: No hardcoded selectors, adapts to any website architecture  
- **🎯 Plain English**: Write tests like `vq.do("click login")` and `vq.do("type john@example.com in email")`
- **🔒 Self-Healing**: Automatically adapts when websites change
- **⚡ Production-Ready**: Built with enterprise reliability patterns
- **🚫 Zero Maintenance**: No brittle XPath or CSS selectors to maintain

## 🎯 Why VibeQ?

```python
# Instead of this (Selenium/Playwright)
driver.find_element(By.XPATH, "//button[@class='btn btn-primary login-submit']").click()
driver.find_element(By.CSS_SELECTOR, "#username").send_keys("admin")

# Write this (VibeQ)
vq.do("click login button")
vq.do("type admin in username field")
```

**VibeQ learns from AI and becomes faster over time.** First run uses AI, subsequent runs use cached patterns.

## ⚡ 30-Second Quick Start

```bash
# Install and run demo in 30 seconds
pip install vibeq
vibeq setup    # Follow the wizard
vibeq demo     # Watch VibeQ in action
```

That's it! VibeQ will guide you through everything else.

## ⚡ Quick Start

### Installation
```bash
pip install vibeq
```

### Verify Installation
```bash
# Quick test - should show version
vibeq --version

# Interactive setup wizard  
vibeq setup

# Run the built-in demo
vibeq demo
```

### Browser Setup (Automatic)
```bash
# VibeQ automatically installs browser drivers on first run
# No manual setup needed - just run your first script!

# Optional: Install Playwright browsers manually
pip install playwright
playwright install chromium
```

### First Time Setup
```bash
# Choose your AI provider (one of these):

# Option 1: OpenAI (Recommended)
export OPENAI_API_KEY="your-openai-key-here"

# Option 2: Anthropic Claude  
export ANTHROPIC_API_KEY="your-anthropic-key-here"

# Option 3: Grok (X.AI)
export GROK_API_KEY="your-grok-key-here"

# Option 4: Local Models (Free) - Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
ollama run llama3.2

# Or create a .env file with your chosen provider:
echo "OPENAI_API_KEY=your-key-here" > .env
```

### Your First VibeQ Script
```python
from vibeq import VibeQ

# Initialize VibeQ (auto-detects your AI provider)
vq = VibeQ(headless=False)  # headless=False to see the browser
vq.launch_browser()

try:
    # Navigate to any website
    vq.go_to("https://www.saucedemo.com/")
    
    # Use natural language commands
    vq.do("type standard_user in username")
    vq.do("type secret_sauce in password") 
    vq.do("click login")
    
    # Verify results
    if vq.check("inventory page is visible"):
        print("✅ Login successful!")
    
finally:
    vq.close()
```

### Advanced AI Provider Options
```python
# Auto-detect (uses first available: OpenAI → Claude → Grok → Local)
vq = VibeQ()  # or VibeQ(ai_provider="auto")

# Specific providers
vq = VibeQ(ai_provider="openai")     # OpenAI GPT-4
vq = VibeQ(ai_provider="anthropic")  # Anthropic Claude  
vq = VibeQ(ai_provider="grok")       # Grok (X.AI)
vq = VibeQ(ai_provider="local")      # Local models (Ollama)

# Custom configurations
vq = VibeQ(ai_provider="openai", model="gpt-4")
vq = VibeQ(ai_provider="local", model="llama3.2:latest")
vq = VibeQ(ai_provider="custom", ai_endpoint="http://localhost:1234/v1")
```

### Run the Complete Demo
VibeQ includes a full working example. Try it out:
```bash
# Download the demo (automatically included with VibeQ)
python -m vibeq.demo

# Or run your own copy
python your_script.py
```
vq.do("Type 'mypassword' in the password field")
vq.do("Click submit")

# Verify results
vq.check("User is logged in successfully")
vq.check("Dashboard is visible")

# Clean up
vq.close()
```

### Enterprise Features
```python
# Enterprise mode with governance
vq = VibeQ(
    enterprise_mode=True,
    ai_provider="auto",  # OpenAI, Claude, or Grok
    screenshot_on_failure=True
)

# Configure policies
vq.configure_enterprise(
    max_ai_calls_per_day=500,
    require_pattern_approval=False,
    ai_mode="training"
)

# Get analytics
health = vq.get_suite_health_report()
print(health['recommendations'])
# "Login flow healed 3 times this week - investigate app changes"
```

## 🤖 AI Provider Setup

VibeQ supports multiple AI providers with automatic detection and flexible configuration:

### 🔥 Auto-Detection (Recommended)
```python
vq = VibeQ()  # Automatically detects and uses best available provider
# Detection order: OpenAI → Claude → Grok → Local Models
```

### ☁️ Cloud AI Providers

**OpenAI GPT-4 (Most Popular)**
```bash
export OPENAI_API_KEY="your-openai-key"
# Get key: https://platform.openai.com/api-keys
```

**Anthropic Claude (High Quality)**
```bash
export ANTHROPIC_API_KEY="your-anthropic-key" 
# Get key: https://console.anthropic.com/
```

**Grok/X.AI (Fast & Creative)**
```bash
export GROK_API_KEY="your-grok-key"
# Get key: https://console.x.ai/
```

### 🏠 Local Models (Free & Private)

**Ollama (Recommended for Local)**
```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Download and run a model
ollama run llama3.2

# Use with VibeQ
vq = VibeQ(ai_provider="local")
```

**LM Studio**
```bash
# Download from https://lmstudio.ai/
# Start local server, then:
vq = VibeQ(ai_provider="custom", ai_endpoint="http://localhost:1234/v1")
```

### 🛠️ Custom Configurations
```python
# Specific provider with custom model
vq = VibeQ(ai_provider="openai", model="gpt-4")
vq = VibeQ(ai_provider="anthropic", model="claude-3-opus-20240229")
vq = VibeQ(ai_provider="local", model="llama3.2:latest")

# Custom OpenAI-compatible endpoint
vq = VibeQ(ai_provider="custom", ai_endpoint="http://your-ai-server.com/v1")

# Override with specific API key
vq = VibeQ(ai_provider="openai", api_key="your-specific-key")
```

### Auto-Detection
```python
# Automatically detects available provider
vq = VibeQ(ai_provider="auto")
```

## 🔧 Advanced Features

### CSV Data Automation
```python
# Load test data from CSV
data = vq.read_csv("test_users.csv")
for user in data:
    vq.do(f"Login as {user['email']}")
    vq.do(user['action'])  # Execute action from CSV
    vq.check(user['expected_result'])
```

### API Mocking for Testing
```python
# Mock API responses 
vq.mock_api("/api/users", {"users": [{"id": 1, "name": "Test"}]})
vq.do("Click load users button")  # Uses mocked response
```

### Performance Monitoring
```python
metrics = vq.get_performance_metrics()
print(f"Page load time: {metrics.get('load_time', 'N/A')}")
```

### Self-Healing Insights
```python
# See how your tests are healing
healing = vq.get_healing_analysis()
print(f"Healing success rate: {healing['healing_success_rate']}")

# Get pattern cache performance
stats = vq.get_intelligence_stats()
print(f"Cache hit rate: {stats['hit_rate']}")  # Goal: >80%
```

## 📚 Learning VibeQ

### Method Discovery
```python
# Get all available methods
help(VibeQ)

# Key methods you'll use:
vq.do("command")           # Execute any action in plain English
vq.check("condition")      # Verify conditions in plain English  
vq.read_csv("file.csv")    # Load and process CSV data
vq.start()                 # Start browser session
vq.close()                 # End browser session

# Enterprise methods:
vq.get_suite_health_report()    # Test suite analytics
vq.get_healing_analysis()       # Self-healing insights
vq.configure_enterprise(**opts) # Configure policies
```

### Common Patterns
```python
# Navigation
vq.do("Go to https://myapp.com")
vq.do("Navigate to the dashboard")

# Interactions  
vq.do("Click the save button")
vq.do("Type 'hello world' in the message field")
vq.do("Select 'Premium' from the plan dropdown")

# Verification
vq.check("Success message is displayed")
vq.check("Page title contains 'Dashboard'") 
vq.check("User email shows 'admin@example.com'")
```

## 📊 VibeQ vs Alternatives

| Feature | VibeQ | Selenium | Playwright |
|---------|-------|----------|------------|
| **Plain English Commands** | ✅ | ❌ | ❌ |
| **Self-Healing Selectors** | ✅ | ❌ | ❌ |
| **AI-Powered Element Finding** | ✅ | ❌ | ❌ |
| **Multi-Provider AI Support** | ✅ | ❌ | ❌ |
| **Built-in CSV Automation** | ✅ | ❌ | ❌ |
| **Pattern Learning & Caching** | ✅ | ❌ | ❌ |
| **Enterprise Governance** | ✅ | ❌ | ❌ |
| **Test Suite Health Analytics** | ✅ | ❌ | ❌ |
| **Modern Browser APIs** | ✅ | ⚠️ | ✅ |
| **Cross-platform** | ✅ | ✅ | ✅ |

## 🏢 Enterprise Ready

### Governance & Compliance
- **AI Usage Policies**: Control AI provider usage and data sharing
- **Pattern Approval Workflows**: Require approval for new selectors in production
- **Audit Trails**: Complete logging of all test actions and decisions
- **Resource Limits**: Prevent runaway AI costs with smart limits

### Analytics & Monitoring
- **Test Health Reports**: Identify problematic test patterns and app changes
- **Healing Analytics**: Monitor self-healing effectiveness and patterns
- **Performance Trends**: Track test execution performance over time
- **Governance Reports**: Policy compliance and resource usage

## 🚀 Getting Started

1. **Install**: `pip install vibeq`
2. **Verify**: `vibeq --version` 
3. **Setup**: `vibeq setup` (interactive wizard)
4. **Try Demo**: `vibeq demo` (see it in action)
5. **Write Tests**: Use plain English commands
6. **Run & Learn**: VibeQ gets smarter with each run

### Quick Commands
```bash
vibeq setup     # Interactive setup wizard
vibeq demo      # Run built-in demo
vibeq examples  # Show example scripts
vibeq run "click login button"  # Test single commands
```

## 🔧 Common Issues & Solutions

### "No API key found"
```bash
# Set your AI provider key:
export OPENAI_API_KEY="your-key-here"

# Or use the setup wizard:
vibeq setup
```

### "Browser not found" 
```bash
# VibeQ will auto-install on first run, or install manually:
playwright install chromium
```

### "Command not understood"
```python
# Be specific and natural:
vq.do("click the blue submit button")  # Good
vq.do("click button")                  # Too vague

# Use vibeq run for testing commands:
vibeq run "click login button"
```

### Import Issues
```bash
# Verify installation:
pip install vibeq --upgrade
python -c "from vibeq import VibeQ; print('✅ VibeQ installed correctly')"
```

## 🤝 Community & Support

- **GitHub**: [github.com/Ronaldozero7/vibeq](https://github.com/Ronaldozero7/vibeq)
- **Documentation**: [README & Examples](https://github.com/Ronaldozero7/vibeq#readme)
- **Issues**: [Report bugs and request features](https://github.com/Ronaldozero7/vibeq/issues)
- **Discussions**: [Community support](https://github.com/Ronaldozero7/vibeq/discussions)

## 📄 License

MIT License - see LICENSE file for details.

---

**VibeQ: Where plain English meets intelligent automation.** 🚀