testdriver:mcp-workflow

# TestDriver MCP Workflow

Build automated tests by directly controlling a sandbox through MCP tools. Every action returns a screenshot AND the generated code to add to your test file.

## When to Use This Skill

Use this skill when:
- You have access to TestDriver MCP tools (`session_start`, `find`, `click`, etc.)
- User asks to "write a test", "automate this workflow", "check if X works"
- You need to build tests iteratively with visual feedback

## Overview

Use MCP tools to:

1. **Control the sandbox directly** - Click, type, scroll in real-time
2. **See visual feedback** - Every action shows a screenshot with overlays
3. **Get generated code** - Each successful action returns the code to add to your test file
4. **Build tests incrementally** - Append code to test files as you go

## Quick Start

### 1. Start a Session

```
session_start({ type: "chrome", url: "https://your-app.com" })
```

This provisions a sandbox with Chrome and navigates to your URL. You'll see a screenshot and the provision code:

```
Add to test file:
await testdriver.provision.chrome({ url: "https://your-app.com" });
```

**For local development** (pointing to a custom API endpoint):

```
session_start({ 
  type: "chrome", 
  url: "https://your-app.com",
  apiRoot: "https://your-ngrok-url.ngrok.io"
})
```

**For self-hosted AWS instances** (your own Windows EC2):

```
session_start({ 
  type: "chrome", 
  url: "https://your-app.com",
  os: "windows",
  ip: "1.2.3.4"  // IP from your AWS instance
})
```

See [AWS Setup Guide](https://docs.testdriver.ai/v7/aws-setup) to deploy your own infrastructure.

### 2. Interact with the App

Find elements and interact with them. Each action returns a screenshot AND generated code:

```
find_and_click({ description: "Sign In button" })
→ Returns: screenshot with element highlighted
→ Add to test file: await testdriver.find("Sign In button").click();

type({ text: "user@example.com" })
→ Returns: screenshot showing typed text
→ Add to test file: await testdriver.type("user@example.com");
```

### 3. Check If Actions Succeeded

After performing actions, use `check` to verify they worked:

```
check({ task: "Was the text entered into the field?" })
→ Returns: AI analysis of whether the task completed, with screenshot

check({ task: "Did the button click navigate to a new page?" })
→ Returns: AI compares previous screenshot to current state
```

### 4. Make Assertions (for Test Files)

Use `assert` for boolean pass/fail conditions that get recorded in test files:

```
assert({ assertion: "the login form is visible" })
→ Returns: pass/fail with screenshot
→ Add to test file:
   const assertResult = await testdriver.assert("the login form is visible");
   expect(assertResult).toBeTruthy();
```

### 5. Write the Test File

As you perform actions, append the generated code to your test file:

```javascript
/**
 * Login Flow test
 */
import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";

describe("Login Flow", () => {
  it("should complete login", async (context) => {
    const testdriver = TestDriver(context);

    // Append generated code here as you go:
    await testdriver.provision.chrome({ url: "https://app.example.com" });
    await testdriver.find("email input field").click();
    await testdriver.type("user@example.com");
    // ... more code as you perform actions
  });
});
```

### 6. Verify the Test

Run the test from scratch to validate it works:

```
verify({ testFile: "tests/login.test.mjs" })
```

## Tools Reference

### Session Management

| Tool | Description |
|------|-------------|
| `session_start` | Start sandbox with browser/app, returns screenshot + provision code |
| `session_status` | Check session health and time remaining |
| `session_extend` | Add more time before session expires |

### Element Interaction

Each tool returns a screenshot AND the generated code to add to your test file.

| Tool | Description |
|------|-------------|
| `find` | Locate element by description, returns ref for later use |
| `click` | Click on element ref |
| `find_and_click` | Find and click in one action |
| `type` | Type text into focused field |
| `press_keys` | Press keyboard shortcuts (e.g., `["ctrl", "a"]`) |
| `scroll` | Scroll page (up/down/left/right) |

### Verification & Display

| Tool | Description |
|------|-------------|
| `check` | **For AI to understand screen state.** Analyzes current screen and tells you (the AI) whether a task/condition is met. Use this after actions to verify they worked. |
| `assert` | AI-powered boolean assertion for test files (pass/fail for CI). Returns generated code. |
| `screenshot` | **For showing the user the screen.** Captures and displays a screenshot. Does NOT return analysis to you (the AI). |
| `exec` | Execute JavaScript, shell, or PowerShell in sandbox. Returns generated code. |

### Test Validation

| Tool | Description |
|------|-------------|
| `verify` | Run test file from scratch to validate it works |

## Visual Feedback

Every tool returns a screenshot showing:

- **Element highlights** - Blue box around found elements
- **Click markers** - Red dot with ripple effect at click location
- **Scroll indicators** - Arrow showing scroll direction
- **Action status** - Success/failure with duration
- **Session info** - Time remaining before expiry

## Workflow Best Practices

### 1. Work Incrementally

Don't try to build the entire test at once:

```
# Step 1: Get to login page
session_start({ url: "https://app.com" })
→ Add to test: await testdriver.provision.chrome({ url: "https://app.com" });

# Step 2: Verify you're on the right page
check({ task: "Is this the login page?" })

# Step 3: Fill in email
find_and_click({ description: "email input field" })
→ Add to test: await testdriver.find("email input field").click();

type({ text: "user@example.com" })
→ Add to test: await testdriver.type("user@example.com");

# Step 4: Check if email was entered
check({ task: