@testdriverai/mcp 7.10.0-canary.0 → 7.10.1-test

package/docs/v7/_drafts/prompt-cache.mdx

@@ -1,200 +0,0 @@
-# Prompt Cache System
-
-## Overview
-
-The TestDriver SDK includes automatic caching of `.ai()` responses. When you use the SDK to execute natural language prompts, the YAML commands generated by the AI are cached locally to improve performance and reduce API calls.
-
-**Caching is enabled by default** and can be controlled per-call using the `cache` parameter.
-
-## How It Works
-
-1. **First Call**: When you call `.ai('click the submit button')` for the first time:
-
-   - The SDK sends the prompt and screenshot to the API
-   - The API returns YAML commands in markdown format
-   - The response is cached to `.testdriver/.cache/{prompt-hash}.yaml`
-
-2. **Subsequent Calls**: When you call `.ai('click the submit button')` again:
-
-   - The SDK checks the cache first
-   - If found, it uses the cached YAML instead of calling the API
-   - You'll see `(using cached response)` in the output
-
-3. **Disable Caching**: Pass `false` as the second parameter:
-   - `.ai('click the submit button', false)` bypasses the cache
-   - Forces a fresh API call and updates the cache
-
-## Cache Location
-
-Cached responses are stored in:
-
-```
-.testdriver/.cache/
-```
-
-Files are named using a combination of:
-
-- Sanitized prompt (first 50 chars, alphanumeric only)
-- MD5 hash of the full prompt for uniqueness
-
-Example:
-
-```
-.testdriver/.cache/click-the-submit-button-a1b2c3d4e5f6.yaml
-```
-
-## Benefits
-
-- **Faster execution**: No API call needed for repeated prompts
-- **Cost savings**: Reduces API usage for repeated operations
-- **Offline testing**: Can rerun tests without network access
-- **Deterministic tests**: Same prompt always produces same commands
-
-## Disabling Cache
-
-To disable caching for a specific `.ai()` call, pass `false` as the second parameter:
-
-```javascript
-// Force fresh API call, bypass cache
-await client.ai("click the submit button", false);
-```
-
-Caching is **enabled by default** (equivalent to passing `true`):
-
-```javascript
-// These are equivalent
-await client.ai("click the submit button");
-await client.ai("click the submit button", true);
-```
-
-## Clearing Cache
-
-To clear all cached prompts:
-
-```bash
-rm -rf .testdriver/.cache/*.yaml
-```
-
-Or programmatically:
-
-```javascript
-const promptCache = require("testdriverai/agent/lib/cache.js");
-promptCache.clearCache();
-```
-
-## Usage Examples
-
-### Basic Usage (Automatic Caching)
-
-```javascript
-const TestDriver = require("testdriverai");
-
-const client = new TestDriver(process.env.TD_API_KEY);
-await client.connect();
-
-// First call - makes API request and caches
-await client.ai("click the login button");
-
-// Second call - uses cache (instant)
-await client.ai("click the login button");
-
-// Force fresh API call, bypass cache
-await client.ai("click the login button", false);
-```
-
-### Check Cache Status
-
-```javascript
-const promptCache = require("testdriverai/agent/lib/cache.js");
-
-// Check if a prompt is cached
-if (promptCache.hasCache("click the login button")) {
-  console.log("This prompt is cached");
-}
-
-// Get cache statistics
-const stats = promptCache.getCacheStats();
-console.log(`Cached prompts: ${stats.count}`);
-console.log(`Files: ${stats.files}`);
-```
-
-### Read Cached YAML
-
-```javascript
-const promptCache = require("testdriverai/agent/lib/cache.js");
-
-const yaml = promptCache.readCache("click the login button");
-if (yaml) {
-  console.log("Cached YAML:", yaml);
-}
-```
-
-### Manual Cache Control
-
-```javascript
-const promptCache = require("testdriverai/agent/lib/cache.js");
-
-// Write to cache manually
-promptCache.writeCache("custom prompt", yamlContent);
-
-// Clear entire cache
-promptCache.clearCache();
-
-// Get cache path for a prompt
-const path = promptCache.getCachePath("my prompt");
-console.log(`Cache file: ${path}`);
-```
-
-## Important Notes
-
-1. **Prompt Matching**: Cache keys are based on the exact prompt text (case-insensitive, trimmed)
-
-   - `'Click the button'` and `'click the button'` will match
-   - `'Click the button'` and `'Click the button '` will match (trailing space trimmed)
-   - `'Click button'` and `'Click the button'` will NOT match
-
-2. **No Screenshot Comparison**: The cache does NOT compare screenshots
-
-   - Cached responses assume the UI state is similar
-   - Use different prompts if the UI state has changed significantly
-
-3. **Manual Cache Management**: The cache never expires automatically
-
-   - Clear it periodically if needed
-   - Delete specific files if a prompt's behavior should change
-
-4. **Version Compatibility**: Cache files are plain YAML
-   - Compatible across TestDriver versions
-   - Safe to commit to version control (though not recommended)
-
-## Testing
-
-Run the test suite to verify caching:
-
-```bash
-node test-prompt-cache.js
-```
-
-This will:
-
-- Make an initial `.ai()` call that caches the response
-- Make a second `.ai()` call that uses the cache
-- Show cache statistics and file locations
-
-## Troubleshooting
-
-### Cache not being used
-
-- Check that prompts match exactly (case-insensitive)
-- Verify `TD_NO_PROMPT_CACHE` is not set
-- Check `.testdriver/.cache/` directory exists and is writable
-
-### Stale cache data
-
-- Clear the cache directory
-- Or delete specific cached prompt files
-
-### Permission errors
-
-- Ensure `.testdriver/.cache/` is writable
-- Check file system permissions

package/docs/v7/copilot/creating-tests.mdx

@@ -1,156 +0,0 @@
----
-title: "Creating Tests"
-sidebarTitle: "Creating Tests"
-description: "Use the TestDriver agent and MCP to create tests through natural language"
-icon: "wand-magic-sparkles"
----
-
-With GitHub Copilot and TestDriver's MCP server, you can create tests by chatting with an AI agent. The agent spawns a virtual machine, executes actions, and writes test code for you.
-
-## Start a Conversation
-
-Open GitHub Copilot Chat in VS Code. If your project has no other agents configured, the TestDriver agent is used by default. Otherwise, select **testdriver** from the agent dropdown in the chat panel.
-
-Describe what you want to test:
-
-```
-Create a test that logs into my app at https://myapp.com
-```
-
-The agent will:
-1. Start a new session and spawn a Linux virtual machine
-2. Launch Chrome and navigate to your URL
-3. Execute actions based on your instructions
-4. Write the test code to a `.test.mjs` file
-
-<Note>
-  The TestDriver agent appears in the agent selection dropdown if you have other agents configured (like `copilot-instructions.md` or other `.agent.md` files). Make sure to select **testdriver** to use TestDriver's MCP tools.
-</Note>
-
-## Live Preview Panel
-
-When the agent starts a session, a **live preview panel** opens in VS Code. This lets you:
-
-- **Watch tests execute** in real-time
-- **Interact with the VM** — click, type, and navigate manually
-- **Debug issues** — see exactly what the AI sees
-
-<Note>
-  The live preview panel requires the TestDriver VS Code extension. Set `TD_PREVIEW=ide` in your MCP configuration to enable it. See the [device configuration docs](/v7/device-config) for all preview options.
-</Note>
-
-## Interactive Workflow
-
-The recommended workflow for creating tests:
-
-<Steps>
-  <Step title="Describe Your Test">
-    Tell the agent what you want to test:
-
-    ```
-    Test the checkout flow on https://shop.example.com
-    ```
-  </Step>
-
-  <Step title="Watch and Guide">
-    The agent will start executing. Watch the preview panel and provide guidance if needed:
-
-    ```
-    The login modal appeared. Use test@example.com and password123
-    ```
-  </Step>
-
-  <Step title="Add Assertions">
-    Ask the agent to verify specific conditions:
-
-    ```
-    Assert that the order confirmation page is shown with the order number
-    ```
-  </Step>
-
-  <Step title="Review the Code">
-    The agent writes test code as it works. Review the generated `.test.mjs` file and make any adjustments.
-  </Step>
-</Steps>
-
-## Example Conversation
-
-Here's a complete example of creating a login test:
-
-```
-You: Create a test for the login flow at https://console.testdriver.ai
-
-Agent: I'll create a test for the login flow. Starting a session...
-       [Screenshot: Login page loaded]
-
-       I can see the login page. Let me find the email input.
-       [Screenshot: Email input highlighted]
-
-       Now I'll type the email and find the password field...
-
-You: Use test@example.com for the email
-
-Agent: Got it. Typing test@example.com...
-       [Screenshot: Email entered]
-
-       Now entering the password and clicking Sign In...
-       [Screenshot: Dashboard loaded]
-
-       ✅ Login successful! I've written the test to tests/login.test.mjs
-```
-
-## Generated Test Code
-
-The agent generates standard Vitest test files:
-
-```javascript tests/login.test.mjs
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
-
-describe("Login Flow", () => {
-  it("should log in successfully", async (context) => {
-    const testdriver = TestDriver(context);
-
-    await testdriver.provision.chrome({
-      url: "https://console.testdriver.ai"
-    });
-
-    const emailInput = await testdriver.find("email input field");
-    await emailInput.click();
-    await testdriver.type("test@example.com");
-
-    const passwordInput = await testdriver.find("password input field");
-    await passwordInput.click();
-    await testdriver.type("password123");
-
-    const signInButton = await testdriver.find("Sign In button");
-    await signInButton.click();
-
-    const result = await testdriver.assert("dashboard is visible");
-    expect(result).toBeTruthy();
-  });
-});
-```
-
-## Tips for Better Tests
-
-<AccordionGroup>
-  <Accordion title="Be specific with element descriptions">
-    Instead of "click the button", say "click the blue Sign In button in the header". More context helps the AI find the right element.
-  </Accordion>
-  <Accordion title="Add waits for dynamic content">
-    If your app has animations or loading states, tell the agent to wait:
-    ```
-    Wait for the loading spinner to disappear before continuing
-    ```
-  </Accordion>
-  <Accordion title="Use assertions liberally">
-    Add assertions after each major action to catch regressions early:
-    ```
-    Assert that the product was added to the cart
-    ```
-  </Accordion>
-  <Accordion title="Break complex flows into steps">
-    For long workflows, create the test incrementally and verify each step works before moving on.
-  </Accordion>
-</AccordionGroup>

package/docs/v7/copilot/github.mdx

@@ -1,143 +0,0 @@
----
-title: "GitHub Integration"
-sidebarTitle: "GitHub"
-description: "Use TestDriver from GitHub's web interface and mobile app"
-icon: "github"
----
-
-TestDriver works directly in GitHub's web interface and mobile app. The same MCP server that powers VS Code integration also works in GitHub, letting you create and manage tests from anywhere.
-
-## How It Works
-
-When you add a TestDriver agent file to your repository at `.github/agents/testdriver.agent.md`, GitHub Copilot can use TestDriver's MCP tools directly in:
-
-- GitHub.com (web browser)
-- GitHub Mobile app (iOS/Android)
-- Pull request conversations
-- Issue comments
-
-## Using TestDriver in GitHub Web
-
-<Steps>
-  <Step title="Navigate to Your Repository">
-    Open your repository on GitHub.com. Make sure you have the TestDriver agent file at `.github/agents/testdriver.agent.md`.
-  </Step>
-
-  <Step title="Start a Copilot Chat">
-    Click the **Copilot icon** in the GitHub interface to open a chat. You can find this in:
-    - The repository's Code tab
-    - Pull request pages
-    - Issue pages
-  </Step>
-
-  <Step title="Invoke the TestDriver Agent">
-    Start your message with `@testdriver`:
-
-    ```
-    @testdriver Create a test that verifies the homepage loads correctly at https://myapp.com
-    ```
-
-    The agent will spawn a sandbox environment and begin executing, just like in VS Code.
-  </Step>
-
-  <Step title="View Screenshots in Chat">
-    As the test runs, screenshots appear directly in the chat. You can see what the AI sees and provide guidance if needed.
-  </Step>
-</Steps>
-
-## Creating Tests from PR Comments
-
-You can create tests directly from pull request reviews. Comment on a PR and mention Copilot:
-
-```
-@copilot create a TestDriver test that verifies this new feature works.
-Test the checkout flow with a guest user.
-```
-
-Copilot will:
-1. Use the TestDriver MCP server
-2. Create a test based on your description
-3. Commit the test file to the PR branch
-
-This is useful for:
-- Adding test coverage during code review
-- Verifying bug fixes before merging
-- Creating regression tests for new features
-
-## Creating Tests from Issues
-
-You can also create tests from issue comments:
-
-```
-@copilot Use TestDriver to create a test that reproduces this bug.
-Navigate to /settings, change the theme, and verify it persists after refresh.
-```
-
-The test will be created in a new branch and linked to the issue.
-
-## Mobile App Support
-
-The GitHub Mobile app supports Copilot chat, which means you can use TestDriver from your phone:
-
-1. Open the GitHub app
-2. Navigate to your repository
-3. Tap the Copilot icon
-4. Type `@testdriver` followed by your request
-
-Screenshots and test progress appear in the chat, letting you create and debug tests on the go.
-
-## Example: PR Review Workflow
-
-Here's a complete workflow for adding tests during code review:
-
-<Steps>
-  <Step title="Developer Opens PR">
-    A developer opens a pull request with a new feature.
-  </Step>
-
-  <Step title="Reviewer Requests Tests">
-    The reviewer comments:
-    ```
-    @copilot Create a TestDriver test for this user registration flow.
-    Test both successful registration and validation errors.
-    ```
-  </Step>
-
-  <Step title="Copilot Creates Tests">
-    Copilot spawns TestDriver, creates the tests, and commits them to the PR branch.
-  </Step>
-
-  <Step title="Tests Run in CI">
-    The new tests run automatically in CI, validating the feature works as expected.
-  </Step>
-</Steps>
-
-## Agent File Reference
-
-The agent file at `.github/agents/testdriver.agent.md` contains the configuration for GitHub Copilot to use TestDriver. Here's the structure:
-
-```yaml
----
-name: testdriver
-description: An expert at creating and refining automated tests using TestDriver.ai
-mcp-servers:
-  testdriver:
-    command: npx
-    args:
-      - -p
-      - testdriverai
-      - testdriverai-mcp
-    env:
-      TD_API_KEY: ${TD_API_KEY}
----
-
-# TestDriver Expert
-
-You are an expert at writing automated tests using TestDriver...
-```
-
-The `TD_API_KEY` is pulled from your repository secrets when running in GitHub Actions or from your environment when using the web interface.
-
-<Warning>
-  Make sure `TD_API_KEY` is set in your repository secrets for CI workflows. Go to **Settings → Secrets and variables → Actions** to add it.
-</Warning>

package/docs/v7/copilot/setup.mdx

@@ -1,143 +0,0 @@
----
-title: "GitHub Copilot Setup"
-sidebarTitle: "IDE Setup"
-description: "Install the TestDriver extension and configure MCP for GitHub Copilot"
-icon: "wrench"
----
-
-TestDriver integrates with GitHub Copilot through the VS Code extension and MCP server. This guide walks you through the complete setup.
-
-## Prerequisites
-
-Before you begin, you'll need:
-
-- **GitHub Copilot** — A subscription with MCP access. A [free tier](https://github.com/features/copilot/plans) is available.
-- **TestDriver Account** — Create a free account at [console.testdriver.ai](https://console.testdriver.ai/team) to get your API key. 60 free device minutes, no credit card required.
-- **VS Code** — The TestDriver extension provides the best experience with live preview and integrated test running.
-
-## Setup Steps
-
-<Steps>
-  <Step title="Install the TestDriver Extension">
-    <Card
-      horizontal
-      title="Install TestDriver for VS Code"
-      arrow
-      href="vscode:extension/testdriver.testdriver"
-      icon="/images/content/extension/vscode.svg"
-    ></Card>
-
-    The extension provides:
-    - One-click sign-in and project initialization
-    - Live preview panel for watching tests execute
-    - MCP server configuration
-  </Step>
-
-  <Step title="Sign Into TestDriver">
-    Sign in to connect your account and API key.
-
-    1. Open the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
-    2. Run **TestDriver: Login**
-    3. Your browser will open to the TestDriver sign-in page
-    4. Sign in (or create an account)
-    5. You'll be redirected back to VS Code, now signed in
-
-    <Tip>
-      The extension automatically saves your API key to VS Code's secure storage and your workspace `.env` file.
-    </Tip>
-  </Step>
-
-  <Step title="Initialize Your Project">
-    Set up TestDriver in your project with a single command.
-
-    1. Open the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
-    2. Run **TestDriver: Init Project**
-
-    This command:
-    - Creates a `package.json` with TestDriver and Vitest dependencies
-    - Generates a `vitest.config.mjs` with proper timeout settings
-    - Creates example test files in `tests/`
-    - Sets up `.env` with your API key
-    - Creates the TestDriver agent file at `.github/agents/testdriver.agent.md`
-    - Configures the MCP server
-
-    <Note>
-      If you already have a `package.json`, the command will add the necessary dependencies to it.
-    </Note>
-  </Step>
-
-  <Step title="Start the MCP Server">
-    The MCP server enables GitHub Copilot to control TestDriver sandboxes.
-
-    After initialization, the MCP configuration is created at `.vscode/mcp.json`:
-
-    ```json .vscode/mcp.json
-    {
-      "servers": {
-        "testdriver": {
-          "command": "npx",
-          "args": ["-p", "testdriverai", "testdriverai-mcp"],
-          "env": {
-            "TD_PREVIEW": "ide",
-            "TD_API_KEY": "your-api-key"
-          }
-        }
-      }
-    }
-    ```
-
-    **To start the MCP server:**
-
-    1. Open the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
-    2. Run **MCP: List Servers**
-    3. Click on the **testdriver** server
-    4. Select **Start Server**
-
-    You can also click the MCP icon in the status bar to manage servers.
-
-    <Tip>
-      See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details on managing MCP servers.
-    </Tip>
-
-    <Warning>
-      Make sure your API key is set. The extension uses the key from your sign-in, but you can also set it via the `TD_API_KEY` environment variable.
-    </Warning>
-  </Step>
-
-  <Step title="Install Vitest Extension (Recommended)">
-    For the best experience running tests, install the Vitest extension:
-
-    <Card
-      horizontal
-      title="Vitest Extension"
-      arrow
-      href="vscode:extension/vitest.explorer"
-      icon="flask-vial"
-    >
-      Run tests with GUI mode from the Test Explorer
-    </Card>
-
-    After installation, you'll see a beaker icon in the sidebar for accessing the Test Explorer.
-  </Step>
-</Steps>
-
-## Verify Your Setup
-
-To verify everything is configured correctly:
-
-1. Open the command palette and run **TestDriver: Check Status**
-2. You should see:
-   - ✅ Signed in
-   - ✅ MCP server configured
-   - ✅ Project initialized
-
-## The Agent File
-
-During initialization, TestDriver creates an agent file at `.github/agents/testdriver.agent.md`. This file tells GitHub Copilot how to use TestDriver's MCP tools.
-
-The agent has access to tools like:
-- `session_start` — Launch a sandbox with Chrome or other apps
-- `find` / `click` / `type` — Interact with elements on screen
-- `assert` — Verify conditions using AI vision
-- `screenshot` — Capture the current screen state
-