/testdriver-mcp-workflow

name: testdriver:mcp-workflow
description: Build TestDriver tests iteratively using MCP tools with visual feedback

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:

/**
 * 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@ex