testdriverai 7.3.2 → 7.3.3

package/manual/test-init-command.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+/**
+ * Test Init Command
+ * 
+ * This script tests the `testdriverai init` command by:
+ * 1. Creating a temporary test project
+ * 2. Running the init command
+ * 3. Verifying all files were created correctly
+ * 4. Running the generated test
+ * 5. Cleaning up
+ * 
+ * Usage:
+ *   node manual/test-init-command.js
+ * 
+ * Requirements:
+ *   - TD_API_KEY environment variable must be set
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const os = require('os');
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  yellow: '\x1b[33m',
+  gray: '\x1b[90m',
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function success(message) {
+  log(`✓ ${message}`, 'green');
+}
+
+function error(message) {
+  log(`✗ ${message}`, 'red');
+}
+
+function info(message) {
+  log(message, 'cyan');
+}
+
+function step(message) {
+  log(`\n${message}`, 'cyan');
+}
+
+// Main test function
+async function testInitCommand() {
+  // Check for API key
+  if (!process.env.TD_API_KEY) {
+    error('TD_API_KEY environment variable is required');
+    process.exit(1);
+  }
+
+  const testDir = path.join(os.tmpdir(), `test-init-${Date.now()}`);
+  const cliPath = path.join(__dirname, '..');
+  
+  try {
+    step('📦 Creating test directory...');
+    fs.mkdirSync(testDir, { recursive: true });
+    success(`Created: ${testDir}`);
+
+    step('🔧 Setting up .env file...');
+    const envContent = `TD_API_KEY=${process.env.TD_API_KEY}\n`;
+    fs.writeFileSync(path.join(testDir, '.env'), envContent);
+    success('Created .env with API key');
+
+    step('🚀 Running init command...');
+    try {
+      execSync(`node ${path.join(cliPath, 'bin/testdriverai.js')} init`, {
+        cwd: testDir,
+        stdio: 'inherit',
+        env: { ...process.env, TD_API_KEY: process.env.TD_API_KEY }
+      });
+      success('Init command completed');
+    } catch (err) {
+      error('Init command failed');
+      throw err;
+    }
+
+    step('🔍 Verifying project structure...');
+    
+    const expectedFiles = [
+      'package.json',
+      'vitest.config.js',
+      'tests/example.test.js',
+      'tests/login.js',
+      '.env',
+      '.gitignore',
+      '.github/workflows/testdriver.yml'
+    ];
+
+    for (const file of expectedFiles) {
+      const filePath = path.join(testDir, file);
+      if (!fs.existsSync(filePath)) {
+        error(`Missing file: ${file}`);
+        throw new Error(`Expected file not found: ${file}`);
+      }
+      success(`Found: ${file}`);
+    }
+
+    step('📝 Verifying vitest.config.js contents...');
+    const vitestConfig = fs.readFileSync(path.join(testDir, 'vitest.config.js'), 'utf8');
+    
+    if (!vitestConfig.includes('TestDriver()')) {
+      error('TestDriver reporter not found in vitest.config.js');
+      console.log(vitestConfig);
+      throw new Error('TestDriver reporter not configured');
+    }
+    success('TestDriver reporter is configured');
+
+    if (!vitestConfig.includes('setupFiles') || !vitestConfig.includes('testdriverai/vitest/setup')) {
+      error('setupFiles not configured correctly');
+      console.log(vitestConfig);
+      throw new Error('setupFiles not configured');
+    }
+    success('setupFiles is configured correctly');
+
+    if (!vitestConfig.includes('reporters')) {
+      error('reporters array not found');
+      console.log(vitestConfig);
+      throw new Error('reporters not configured');
+    }
+    success('reporters array includes TestDriver');
+
+    step('📝 Verifying example test contents...');
+    const testFile = fs.readFileSync(path.join(testDir, 'tests/example.test.js'), 'utf8');
+    
+    if (!testFile.includes('.provision.chrome')) {
+      error('Test does not use .provision.chrome');
+      console.log(testFile);
+      throw new Error('Test does not use .provision pattern');
+    }
+    success('Test uses .provision.chrome');
+
+    if (!testFile.includes("from 'testdriverai/vitest/hooks'")) {
+      error('Test does not import from testdriverai/vitest/hooks');
+      console.log(testFile);
+      throw new Error('Test does not import TestDriver from vitest/hooks');
+    }
+    success('Test imports TestDriver from vitest/hooks');
+
+    if (!testFile.includes("from './login.js'")) {
+      error('Test does not import login from ./login.js');
+      console.log(testFile);
+      throw new Error('Test does not import login snippet');
+    }
+    success('Test imports login snippet');
+
+    step('📝 Verifying login snippet contents...');
+    const loginFile = fs.readFileSync(path.join(testDir, 'tests/login.js'), 'utf8');
+
+    if (!loginFile.includes('.extract(')) {
+      error('Login snippet does not use .extract()');
+      console.log(loginFile);
+      throw new Error('Login snippet does not demonstrate .extract()');
+    }
+    success('Login snippet demonstrates .extract()');
+
+    if (!loginFile.includes('secret: true')) {
+      error('Login snippet does not use secret option');
+      console.log(loginFile);
+      throw new Error('Login snippet does not demonstrate secret typing');
+    }
+    success('Login snippet demonstrates secret typing');
+
+    step('🧪 Running generated test...');
+    try {
+      execSync('npm test', {
+        cwd: testDir,
+        stdio: 'inherit',
+        env: { ...process.env, TD_API_KEY: process.env.TD_API_KEY }
+      });
+      success('Test execution completed successfully');
+    } catch (err) {
+      error('Test execution failed');
+      throw err;
+    }
+
+    step('✅ All checks passed!');
+    log('\nTest summary:', 'green');
+    log('  • Init command executed successfully', 'green');
+    log('  • All expected files created', 'green');
+    log('  • Configuration files are correct', 'green');
+    log('  • Example test has proper patterns', 'green');
+    log('  • Generated test runs successfully', 'green');
+
+  } catch (err) {
+    step('❌ Test failed!');
+    error(err.message);
+    if (err.stack) {
+      log(err.stack, 'gray');
+    }
+    process.exit(1);
+  } finally {
+    // Optional: Clean up test directory
+    // Commented out so you can inspect the generated files
+    // step('🧹 Cleaning up...');
+    // if (fs.existsSync(testDir)) {
+    //   fs.rmSync(testDir, { recursive: true, force: true });
+    //   success('Cleaned up test directory');
+    // }
+    
+    info(`\nTest project preserved at: ${testDir}`);
+    info('To clean up manually, run:');
+    log(`  rm -rf ${testDir}`, 'gray');
+  }
+}
+
+// Run the test
+testInitCommand().catch(err => {
+  error('Unexpected error:');
+  console.error(err);
+  process.exit(1);
+});

package/mcp-server/README.md

@@ -0,0 +1,312 @@
+# TestDriver MCP Server
+
+MCP server that enables AI agents to iteratively build TestDriver tests with visual feedback.
+
+## Features
+
+- **Live Session Control**: Direct sandbox control via MCP tools
+- **Visual Feedback**: Every action returns a screenshot with overlays (MCP Apps)
+- **Inline Code Generation**: Each action returns the code to append to your test file
+- **Assertions**: AI-powered assertions about screen state
+
+## Installation
+
+### Via npx (Recommended)
+
+No installation needed! Just configure your MCP client to use npx:
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "testdriver-api-key",
+      "description": "TestDriver API Key From https://console.testdriver.ai/team",
+      "password": true
+    }
+  ],
+  "servers": {
+    "testdriver": {
+      "command": "npx",
+      "args": ["-p", "testdriverai", "testdriverai-mcp"],
+      "env": {
+        "TD_API_KEY": "${input:testdriver-api-key}"
+      }
+    }
+  }
+}
+```
+
+### From Source
+
+```bash
+cd mcp-server
+npm install
+npm run build
+```
+
+## Usage
+
+### With GitHub Copilot Coding Agent
+
+To use the TestDriver MCP server with GitHub Copilot coding agent:
+
+1. **Create a Copilot environment secret:**
+   - Go to your repository **Settings** → **Environments**
+   - Create or select the `copilot` environment
+   - Add an environment secret named `COPILOT_MCP_TD_API_KEY`
+   - Set the value to your TestDriver API key from https://console.testdriver.ai/team
+
+2. **Add the MCP configuration** to your repository's **Settings** → **Copilot** → **Coding agent** → **MCP configuration**:
+
+```json
+{
+  "mcpServers": {
+    "testdriver": {
+      "type": "local",
+      "command": "npx",
+      "args": ["-p", "testdriverai", "testdriverai-mcp"],
+      "tools": ["*"],
+      "env": {
+        "TD_API_KEY": "COPILOT_MCP_TD_API_KEY"
+      }
+    }
+  }
+}
+```
+
+**Note:** The MCP server supports both `TD_API_KEY` and `COPILOT_MCP_TD_API_KEY` environment variables for maximum compatibility with GitHub Copilot coding agent.
+
+For more information, see [Extending GitHub Copilot coding agent with Model Context Protocol](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-coding-agent-with-mcp).
+
+### With Claude Desktop / Cursor
+
+Add to your MCP config (`~/.cursor/mcp.json` or `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+**Using npx (recommended):**
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "testdriver-api-key",
+      "description": "TestDriver API Key From https://console.testdriver.ai/team",
+      "password": true
+    }
+  ],
+  "servers": {
+    "testdriver": {
+      "command": "npx",
+      "args": ["-p", "testdriverai", "testdriverai-mcp"],
+      "env": {
+        "TD_API_KEY": "${input:testdriver-api-key}"
+      }
+    }
+  }
+}
+```
+
+**Using local build:**
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "testdriver-api-key",
+      "description": "TestDriver API Key From https://console.testdriver.ai/team",
+      "password": true
+    }
+  ],
+  "servers": {
+    "testdriver": {
+      "command": "node",
+      "args": ["/path/to/testdriverai/mcp-server/dist/server.js"],
+      "env": {
+        "TD_API_KEY": "${input:testdriver-api-key}"
+      }
+    }
+  }
+}
+```
+
+### API Endpoint Configuration
+
+The API endpoint can be configured in three ways (in order of precedence):
+
+1. **Per-session**: Pass `apiRoot` to `session_start` tool
+2. **Environment variable**: Set `TD_API_ROOT` in your MCP config
+3. **Default**: `https://testdriver-api.onrender.com`
+
+Common values:
+- **Production**: `https://testdriver-api.onrender.com`
+- **Local dev**: Your ngrok URL (e.g., `https://abc123.ngrok.io`)
+
+### Self-Hosted AWS Instances
+
+Connect to your own AWS-hosted Windows instances instead of using TestDriver cloud:
+
+1. **Deploy AWS Infrastructure**: Use the [CloudFormation template](https://docs.testdriver.ai/v7/aws-setup) to set up VPC, security groups, and launch templates
+
+2. **Spawn an instance**: Use `spawn-runner.sh` to launch an EC2 instance:
+   ```bash
+   AWS_REGION=us-east-2 \
+   AMI_ID=ami-0504bf50fad62f312 \
+   AWS_LAUNCH_TEMPLATE_ID=lt-xxx \
+   bash setup/aws/spawn-runner.sh
+   ```
+   
+3. **Connect via MCP**: Pass the IP to `session_start`:
+   ```json
+   {
+     "type": "chrome",
+     "url": "https://example.com",
+     "os": "windows",
+     "ip": "1.2.3.4"
+   }
+   ```
+
+Or set `TD_IP` environment variable:
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "testdriver-api-key",
+      "description": "TestDriver API Key From https://console.testdriver.ai/team",
+      "password": true
+    }
+  ],
+  "servers": {
+    "testdriver": {
+      "command": "node",
+      "args": ["/path/to/mcp-server/dist/server.js"],
+      "env": {
+        "TD_API_KEY": "${input:testdriver-api-key}",
+        "TD_IP": "1.2.3.4"
+      }
+    }
+  }
+}
+```
+
+**Benefits of self-hosted:**
+- Flat license fee (no device-second metering)
+- Use your own AI API keys
+- Custom hardware and software configurations
+- Full RDP access for debugging
+
+### Development
+
+```bash
+# Run in development mode with auto-reload
+npm run dev
+
+# Build for production
+npm run build
+
+# Start production server
+npm start
+```
+
+## Tools
+
+### Session Management
+
+| Tool | Description |
+|------|-------------|
+| `session_start` | Start a new session and provision sandbox |
+| `session_status` | Check session health and time remaining |
+| `session_extend` | Extend session keepAlive time |
+
+### Element Interaction
+
+| Tool | Description |
+|------|-------------|
+| `find` | Find element by natural language description |
+| `click` | Click on element or coordinates |
+| `find_and_click` | Find and click in one action |
+| `type` | Type text into focused field |
+| `press_keys` | Press keyboard shortcuts |
+| `scroll` | Scroll the page |
+
+### Verification
+
+| Tool | Description |
+|------|-------------|
+| `assert` | AI-powered assertion about screen state |
+| `check` | AI analyzes screen state (for agent understanding, no code generated) |
+| `exec` | Execute code in sandbox |
+| `screenshot` | Capture screenshot (displays to user only) |
+
+### Local Screenshots
+
+| Tool | Description |
+|------|-------------|
+| `list_local_screenshots` | List screenshots saved in `.testdriver` directory |
+| `view_local_screenshot` | View a local screenshot (returns image to AI + displays to user) |
+
+The local screenshot tools allow AI agents to review screenshots from previous test runs:
+
+```
+1. Call list_local_screenshots to see available screenshots
+2. Call view_local_screenshot with a path to view and analyze it
+3. The image is returned to the AI (if the client supports images) AND displayed to the user
+```
+
+This is useful for:
+- Debugging test failures by examining saved screenshots
+- Reviewing test execution history
+- Comparing current screen state to previous runs
+
+## Workflow
+
+1. **Start Session**: `session_start` provisions a sandbox with browser/app
+2. **Interact**: Use `find`, `click`, `type` etc. - each action returns generated code
+3. **Build Test**: Append the generated code from each action to your test file
+4. **Assert**: Use `assert` to verify expected state
+5. **Run Test**: Use the CLI (`vitest run <testFile>`) to run the test from scratch
+
+Each tool returns a screenshot showing the result AND the code to add to your test file.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                 MCP Server                          │
+├─────────────────────────────────────────────────────┤
+│                                                     │
+│  ┌─────────────┐  ┌─────────────┐  ┌────────────┐  │
+│  │   Tools     │  │   Session   │  │  CodeGen   │  │
+│  │  (find,     │  │  Manager    │  │  (inline   │  │
+│  │   click,    │  │  (state,    │  │   code     │  │
+│  │   type...)  │  │   expiry)   │  │   output)  │  │
+│  └──────┬──────┘  └──────┬──────┘  └─────┬──────┘  │
+│         │                │               │         │
+│         └────────────────┼───────────────┘         │
+│                          │                         │
+│  ┌───────────────────────┴───────────────────────┐ │
+│  │              TestDriver SDK                   │ │
+│  │         (sandbox control, AI vision)          │ │
+│  └───────────────────────────────────────────────┘ │
+│                          │                         │
+└──────────────────────────┼─────────────────────────┘
+                           │
+                           ▼
+                    ┌──────────────┐
+                    │   Sandbox    │
+                    │  (VM + app)  │
+                    └──────────────┘
+```
+
+## MCP Apps Integration
+
+Every action tool returns a rich UI via MCP Apps showing:
+
+- Screenshot of current screen
+- Element highlights (for `find`)
+- Click markers (for `click`)
+- Scroll indicators (for `scroll`)
+- Action status and duration
+- Session info and time remaining

package/mcp-server/mcp-app.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="color-scheme" content="light dark">
+  <title>TestDriver Screenshot</title>
+</head>
+<body>
+  <main class="main">
+    <div class="screenshot-wrapper">
+      <div class="loading-overlay" id="loading-overlay">
+        <div class="loading-spinner"></div>
+        <span class="loading-text">Waiting for screenshot...</span>
+      </div>
+      <div class="screenshot-container" id="screenshot-container" style="display: none;">
+        <img id="screenshot" alt="Screenshot" />
+        <div id="overlays"></div>
+      </div>
+    </div>
+    <div class="status-bar">
+      <span id="action-status"></span>
+      <span id="session-info"></span>
+    </div>
+  </main>
+  <script type="module" src="/src/mcp-app.ts"></script>
+</body>
+</html>

package/mcp-server/mcp-config.example.json

@@ -0,0 +1,19 @@
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "testdriver-api-key",
+      "description": "TestDriver API Key From https://console.testdriver.ai/team",
+      "password": true
+    }
+  ],
+  "servers": {
+    "testdriver": {
+      "command": "npx",
+      "args": ["-p", "testdriverai", "testdriverai-mcp"],
+      "env": {
+        "TD_API_KEY": "${input:testdriver-api-key}"
+      }
+    }
+  }
+}