vibe-testing / rules

---
description: How to use the vibe-test MCP server for browser testing
globs: 
alwaysApply: true
---

# Vibe Testing — MCP Server for Browser Testing

You have access to the `vibe-test` MCP server which provides code-aware browser testing tools. Use these tools to test web applications by understanding their codebase, exploring pages, and executing test scenarios.

## Quick Start Workflow

1. **Scan the codebase** → understand routes, forms, coverage gaps
2. **Login** (if app requires auth) → establish an authenticated browser session
3. **Explore pages** → discover elements, click everything, observe what works/breaks
4. **Execute scenarios** → run specific test flows (generated or custom)
5. **Generate report** → HTML report with screenshots and coverage analysis
6. **Cleanup** → close browsers when done

## Available MCP Tools

### `scan_codebase`
**Call first.** Analyzes the project source code to build a ProductModel:
- Detects framework (Next.js, React SPA, etc.)
- Parses all routes (pages + API endpoints)
- Extracts forms, buttons, dialogs, features per route
- Reads existing test files for coverage mapping
- Identifies gaps and generates test scenarios

```json
{ "codebase_path": "/path/to/project", "url": "https://staging.myapp.com" }
```

### `login`
Establish an authenticated browser session. Uses saved credentials from previous runs or accepts new ones.

```json
{ "email": "user@example.com", "password": "pass123", "login_url": "/login" }
```

Returns: post-login screenshot, token state, API calls observed.

### `scan_page_elements`
Navigate to a page and discover all interactive elements without interacting with them. Returns element types, selectors, text, and a page screenshot.

```json
{ "route": "/dashboard", "authenticated": true }
```

### `explore_page`
Full "senior tester" exploration — clicks every button, fills every input, tests every tab, observes API calls. Returns detailed interaction outcomes.

```json
{ "route": "/dashboard", "authenticated": true }
```

### `execute_scenario`
Run a specific test scenario (sequence of steps). You can use scenarios from `scan_codebase` output or construct custom ones.

```json
{
  "scenario": {
    "id": "test-login",
    "name": "Login with valid credentials",
    "route": "/login",
    "steps": [
      { "action": "navigate", "url": "/login", "description": "Go to login page" },
      { "action": "fill", "selector": "[type='email']", "value": "user@test.com", "description": "Fill email" },
      { "action": "fill", "selector": "[type='password']", "value": "pass123", "description": "Fill password" },
      { "action": "click", "selector": "button[type='submit']", "description": "Click submit" }
    ],
    "expected_outcome": "Redirect to dashboard"
  }
}
```

### `take_screenshot`
Quick visual check — navigate to a URL and return a screenshot.

```json
{ "url": "/settings", "authenticated": true }
```

### `get_coverage`
Returns coverage map, gaps, and suggested scenarios from the last `scan_codebase` call.

### `suggest_tests`
Analyze codebase features vs test coverage and previous run history. Returns **prioritized, executable scenario objects** you can pass directly to `execute_scenario`. Identifies:
- Untested CRUD operations (critical)
- Missing form validation tests (high)
- Broken elements found during exploration (high)
- Previously failing routes that need retests (high)
- API errors observed during exploration (critical/high)
- Untested navigation flows (low)

```json
{ "route": "/dashboard" }
```

Use this after `scan_codebase` and `explore_page` to understand what tests should be written. Each suggestion includes a ready-to-run scenario with steps.

### `generate_report`
Generate an HTML report from all collected test results and explorations.

### `run_full_test`
All-in-one: scan → generate → execute → explore → report. Use for complete test runs.

```json
{ "url": "https://staging.myapp.com", "codebase_path": "/path/to/project" }
```

### `run_converge`
**Iterative coverage expansion:** runs the full baseline suite, then automatically runs follow-up rounds built from **coverage gaps** and **failed scenarios** until pass rate and gap-count thresholds are met (or `max_followup_rounds` is reached). Use when you want the tool to keep testing deeper without manual scenario writing.

```json
{
  "url": "https://staging.myapp.com",
  "codebase_path": "/path/to/project",
  "max_followup_rounds": 4,
  "target_pass_rate": 0.92,
  "max_high_severity_gaps": 2
}
```

### `cleanup`
Close all browsers and reset session state.

## Best Practices

- Always call `scan_codebase` first — it initializes the session
- Use `scan_page_elements` to understand a page before writing custom scenarios
- Use `explore_page` for broad "does everything work?" testing
- Use `suggest_tests` to find gaps and get ready-to-run scenarios
- Use `execute_scenario` for targeted, specific test flows
- Screenshots are returned as images — use them to visually verify results
- After making code changes, re-run relevant scenarios to verify fixes
- Call `cleanup` when done to free browser resources
- Vibe Test learns from every run — selectors, timings, and failure patterns are persisted

## VIBE.md Project Guidance

Projects can include a `VIBE.md` file in their root to guide testing:
- Login URLs, test accounts
- Elements to never interact with (delete buttons, billing, etc.)
- Known flaky flows to skip
- Special environment setup notes