testdriverai 7.5.25 → 7.6.0-test.0

package/docs/v7/exec.mdx

@@ -1,13 +1,13 @@
 ---
 title: "exec()"
 sidebarTitle: "exec"
-description: "Execute code or shell commands in the sandbox"
+description: "Execute shell or PowerShell commands in the sandbox"
 icon: "terminal"
 ---
 
 ## Overview
 
-Execute JavaScript code in the browser or PowerShell commands in the Windows sandbox environment.
+Execute shell commands (Linux) or PowerShell commands (Windows) in the sandbox environment.
 
 ## Syntax
 
@@ -18,7 +18,7 @@ await testdriver.exec(language, code, timeout, silent)
 ## Parameters
 
 <ParamField path="language" type="string" required>
-  Language to execute: `'js'` (JavaScript) or `'pwsh'` (PowerShell)
+  Language to execute: `'sh'` (Shell/Linux) or `'pwsh'` (PowerShell/Windows)
 </ParamField>
 
 <ParamField path="code" type="string" required>
@@ -37,57 +37,40 @@ await testdriver.exec(language, code, timeout, silent)
 
 `Promise<string>` - Command output
 
-## JavaScript Execution
+## Shell Execution (Linux)
 
-Execute JavaScript in the browser context (Windows sandbox only).
+Execute shell commands in the Linux sandbox.
 
-### DOM Manipulation
+### Basic Commands
 
 ```javascript
-// Click an element via JavaScript
-await testdriver.exec('js', `
-  document.querySelector('#submit-button').click();
-`, 5000);
+// List files
+const files = await testdriver.exec('sh', 'ls -la', 5000);
 
-// Fill a form
-await testdriver.exec('js', `
-  document.querySelector('#username').value = 'testuser';
-  document.querySelector('#password').value = 'password123';
-  document.querySelector('#login-form').submit();
-`, 5000);
+// Check current directory
+const pwd = await testdriver.exec('sh', 'pwd', 5000);
 
-// Scroll to element
-await testdriver.exec('js', `
-  document.querySelector('#footer').scrollIntoView();
-`, 5000);
+// Run a script
+await testdriver.exec('sh', './setup.sh', 60000);
 ```
 
-### Reading Page Data
+### File Operations
 
 ```javascript
-// Get page title
-const title = await testdriver.exec('js', 'document.title', 5000);
-console.log('Page title:', title);
-
-// Get all links
-const links = await testdriver.exec('js', `
-  Array.from(document.querySelectorAll('a'))
-    .map(a => a.href)
-    .join('\\n')
-`, 5000);
+// Create a file
+await testdriver.exec('sh', 'echo "Hello World" > test.txt', 5000);
 
-// Check if element exists
-const exists = await testdriver.exec('js', `
-  document.querySelector('.error-message') !== null
-`, 5000);
+// Read a file
+const content = await testdriver.exec('sh', 'cat test.txt', 5000);
 
-// Get element text
-const text = await testdriver.exec('js', `
-  document.querySelector('.notification').textContent
-`, 5000);
+// Copy files
+await testdriver.exec('sh', 'cp source.txt dest.txt', 5000);
+
+// Delete files
+await testdriver.exec('sh', 'rm test.txt', 5000);
 ```
 
-## PowerShell Execution
+## PowerShell Execution (Windows)
 
 Execute PowerShell commands in the Windows sandbox.
 
@@ -216,7 +199,7 @@ await testdriver.exec('pwsh', '.\\setup.ps1', 60000, true);
   
   ```javascript
   // Quick operations: 5000ms
-  await testdriver.exec('js', 'document.title', 5000);
+  await testdriver.exec('sh', 'ls -la', 5000);
   
   // Installations: 30000-60000ms
   await testdriver.exec('pwsh', 'npm install -g package', 30000);
@@ -289,27 +272,20 @@ describe('Code Execution', () => {
     await testdriver.disconnect();
   });
 
-  it('should execute JavaScript in browser', async () => {
-    await testdriver.focusApplication('Google Chrome');
+  it('should execute shell commands on Linux', async () => {
+    // List directory
+    const files = await testdriver.exec('sh', 'ls -la', 5000);
+    console.log('Files:', files);
     
-    // Get page info via JavaScript
-    const title = await testdriver.exec('js', 'document.title', 5000);
-    console.log('Page title:', title);
+    // Create a file
+    await testdriver.exec('sh', 'echo "Hello World" > test.txt', 5000);
     
-    // Manipulate DOM
-    await testdriver.exec('js', `
-      document.querySelector('#username').value = 'testuser';
-    `, 5000);
-    
-    // Verify
-    const value = await testdriver.exec('js', `
-      document.querySelector('#username').value
-    `, 5000);
-    
-    expect(value).toBe('testuser');
+    // Read the file
+    const content = await testdriver.exec('sh', 'cat test.txt', 5000);
+    expect(content).toContain('Hello World');
   });
 
-  it('should install and use tools', async () => {
+  it('should install and use tools on Windows', async () => {
     // Install tool
     await testdriver.exec('pwsh', 'npm install -g http-server', 30000, true);
     
@@ -331,10 +307,6 @@ describe('Code Execution', () => {
     `, 5000);
     
     await testdriver.focusApplication('Google Chrome');
-    
-    // Verify page loaded
-    const content = await testdriver.exec('js', 'document.body.textContent', 5000);
-    expect(content).toContain('Test Page');
   });
 });
 ```
@@ -342,5 +314,5 @@ describe('Code Execution', () => {
 ## Related Methods
 
 - [`focusApplication()`](/v7/focus-application) - Focus apps before exec
-- [`find()`](/v7/find) - Locate elements (alternative to DOM manipulation)
-- [`type()`](/v7/type) - Type text (alternative to JS form filling)
+- [`find()`](/v7/find) - Locate elements visually
+- [`type()`](/v7/type) - Type text into inputs

package/docs/v7/quickstart.mdx

@@ -23,7 +23,7 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
         npx testdriverai init
         ```
 
-        This will walk you through creating a new project folder, installing dependencies, and setting up your API key.
+        This will walk you through creating a new project folder, installing dependencies, setting up your API key, and configuring MCP for your preferred AI assistant (VS Code, Cursor, Claude Desktop, etc.).
 
       </Step>
       

package/examples/config.mjs

@@ -1,5 +1,5 @@
 export const getDefaults = (context) => ({
   ip: context.ip || process.env.TD_IP,
   redraw: { enabled: false },
-  preview: 'ide',
+  preview: 'web',
 });

package/examples/no-provision.test.mjs

@@ -1,24 +1,31 @@
 /**
- * TestDriver SDK - Assert Test (Vitest)
- * Converted from: testdriver/acceptance/assert.yaml
+ * TestDriver SDK - No-Provision Test with Dashcam (Vitest)
+ * 
+ * Demonstrates manual dashcam control without using provision methods.
+ * When not using provision.chrome(), provision.vscode(), etc., you need
+ * to manually start and stop dashcam recording.
  */
 
-import { describe, expect, it } from "vitest";
+import { describe, it } from "vitest";
 import { TestDriver } from "../lib/vitest/hooks.mjs";
 import { getDefaults } from "./config.mjs";
 
-describe("Assert Test", () => {
-  it("should assert the testdriver login page shows", async (context) => {
+describe("No-Provision with Dashcam", () => {
+  it("should record dashcam while asserting desktop is visible", async (context) => {
     const testdriver = TestDriver(context, { ...getDefaults(context) });
 
-    await testdriver.wait(10000)
+    // Start dashcam recording manually (provision methods do this automatically)
+    await testdriver.dashcam.start();
     
-    // Assert the TestDriver.ai Sandbox login page is displayed
-    const result = await testdriver.assert(
-      "A desktop is visible",
-    );
+    await testdriver.exec('sh', 'gedit >/dev/null 2>&1 &'); // Example command to keep the test running for a bit
 
-    expect(result).toBeTruthy();
+    await testdriver.assert('untitled document is visible');
+
+    // Stop dashcam and get the recording URL
+    const dashcamUrl = await testdriver.dashcam.stop();
+    if (dashcamUrl) {
+      console.log(`🎥 Dashcam recording: ${dashcamUrl}`);
+    }
   });
 });
 

package/interfaces/cli/commands/init.js

@@ -12,7 +12,8 @@ const { execSync } = require("child_process");
 require("dotenv").config();
 
 // API configuration
-const API_BASE_URL = process.env.TD_API_ROOT || "https://api.testdriver.ai";
+const channelConfig = require("../../../../channel.json");
+const API_BASE_URL = process.env.TD_API_ROOT || channelConfig.channels[channelConfig.active];
 const POLL_INTERVAL = 5000; // 5 seconds
 const POLL_TIMEOUT = 900000; // 15 minutes
 

package/interfaces/vitest-plugin.mjs

@@ -9,6 +9,7 @@ import { setTestRunInfo } from "./shared-test-state.mjs";
 
 // Use createRequire to import CommonJS modules without esbuild processing
 const require = createRequire(import.meta.url);
+const channelConfig = require("../channel.json");
 
 // Import Sentry for error reporting
 const Sentry = require("@sentry/node");
@@ -763,7 +764,7 @@ export default function testDriverPlugin(options = {}) {
   pluginState.apiRoot =
     options.apiRoot ||
     process.env.TD_API_ROOT ||
-    "https://api.testdriver.ai";
+    channelConfig.channels[channelConfig.active];
   pluginState.ciProvider = detectCI();
   pluginState.gitInfo = getGitInfo();
 
@@ -822,7 +823,7 @@ class TestDriverReporter {
     pluginState.apiRoot =
       this.options.apiRoot ||
       process.env.TD_API_ROOT ||
-      "https://api.testdriver.ai";
+      channelConfig.channels[channelConfig.active];
     logger.debug("API key from options:", !!this.options.apiKey);
     logger.debug("API key from env (at onInit):", !!process.env.TD_API_KEY);
     logger.debug("API root from options:", this.options.apiRoot);
@@ -1258,6 +1259,26 @@ function getConsoleUrl(apiRoot) {
     return `http://localhost:3001`;
   }
 
+  // Render PR previews: map API service to Web service
+  // canary-api-pr-123.onrender.com -> canary-web-pr-123.onrender.com
+  // testdriver-api-i4m4-pr-123.onrender.com -> web-i4m4-pr-123.onrender.com
+  const renderPrMatch = apiRoot.match(/https:\/\/([\w-]+)-api(-[\w]+)?(-pr-\d+)?\.onrender\.com/);
+  if (renderPrMatch) {
+    const [, prefix, suffix, prSuffix] = renderPrMatch;
+    // Map API naming to Web naming:
+    // canary-api -> canary-web
+    // testdriver-api-i4m4 -> web-i4m4
+    let webPrefix;
+    if (prefix === 'testdriver' && suffix) {
+      // testdriver-api-i4m4 -> web-i4m4
+      webPrefix = 'web' + suffix;
+    } else {
+      // canary-api -> canary-web
+      webPrefix = prefix + '-web';
+    }
+    return `https://${webPrefix}${prSuffix || ''}.onrender.com`;
+  }
+
   // Other tunnels or unknown hosts: return as-is
   return apiRoot;
 }

package/lib/core/Dashcam.js

@@ -80,8 +80,9 @@ class Dashcam {
    * @private
    */
   _getApiRoot() {
+    const channelConfig = require("../../channel.json");
     return (
-      this.client.config?.TD_API_ROOT || "https://api.testdriver.ai"
+      this.client.config?.TD_API_ROOT || channelConfig.channels[channelConfig.active]
     );
   }
 
@@ -91,7 +92,7 @@ class Dashcam {
    * @param {string} apiRoot - The API root URL
    * @returns {string} The corresponding console URL
    */
-  static getConsoleUrl(apiRoot = "https://api.testdriver.ai") {
+  static getConsoleUrl(apiRoot = (() => { const c = require("../../channel.json"); return c.channels[c.active]; })()) {
     // Allow explicit override via env (e.g. VITE_DOMAIN from .env)
     if (process.env.VITE_DOMAIN) return process.env.VITE_DOMAIN;
 
@@ -110,6 +111,26 @@ class Dashcam {
       return "http://localhost:3001";
     }
 
+    // Render PR previews: map API service to Web service
+    // canary-api-pr-123.onrender.com -> canary-web-pr-123.onrender.com
+    // testdriver-api-i4m4-pr-123.onrender.com -> web-i4m4-pr-123.onrender.com
+    const renderPrMatch = apiRoot.match(/https:\/\/([\w-]+)-api(-[\w]+)?(-pr-\d+)?\.onrender\.com/);
+    if (renderPrMatch) {
+      const [, prefix, suffix, prSuffix] = renderPrMatch;
+      // Map API naming to Web naming:
+      // canary-api -> canary-web
+      // testdriver-api-i4m4 -> web-i4m4
+      let webPrefix;
+      if (prefix === 'testdriver' && suffix) {
+        // testdriver-api-i4m4 -> web-i4m4
+        webPrefix = 'web' + suffix;
+      } else {
+        // canary-api -> canary-web
+        webPrefix = prefix + '-web';
+      }
+      return `https://${webPrefix}${prSuffix || ''}.onrender.com`;
+    }
+
     // Cloudflare tunnels, custom domains, etc.: the web console is served
     // from the same origin as the API, so return apiRoot as-is.
     return apiRoot;

package/lib/init-project.js

@@ -337,40 +337,80 @@ jobs:
       progress("⊘ GitHub workflow already exists");
     }
 
-    // 6. Create VSCode MCP config
-    const vscodeDir = path.join(targetDir, ".vscode");
-    if (!fs.existsSync(vscodeDir)) {
-      fs.mkdirSync(vscodeDir, { recursive: true });
-    }
+    // 6. Setup MCP configuration
+    // When triggered from VS Code extension, create .vscode/mcp.json silently
+    // When triggered from CLI, use interactive add-mcp for user to select their MCP client
+    const isVscodeInit = process.env.TD_INIT_SOURCE === "vscode";
+
+    if (isVscodeInit) {
+      // VS Code extension: create .vscode/mcp.json directly
+      const vscodeDir = path.join(targetDir, ".vscode");
+      if (!fs.existsSync(vscodeDir)) {
+        fs.mkdirSync(vscodeDir, { recursive: true });
+      }
 
-    const mcpConfigFile = path.join(vscodeDir, "mcp.json");
-    if (!fs.existsSync(mcpConfigFile)) {
-      const mcpConfig = {
-        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}",
+      const mcpConfigFile = path.join(vscodeDir, "mcp.json");
+      if (!fs.existsSync(mcpConfigFile)) {
+        const mcpConfig = {
+          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}",
+              },
             },
           },
-        },
-      };
-      fs.writeFileSync(mcpConfigFile, JSON.stringify(mcpConfig, null, 2) + "\n");
-      progress("✓ Created MCP config: .vscode/mcp.json");
+        };
+        fs.writeFileSync(mcpConfigFile, JSON.stringify(mcpConfig, null, 2) + "\n");
+        progress("✓ Created MCP config: .vscode/mcp.json");
+      } else {
+        progress("⊘ MCP config already exists");
+      }
     } else {
-      progress("⊘ MCP config already exists");
+      // CLI: use add-mcp for interactive MCP client selection
+      progress("🔧 Setting up MCP integration...");
+      try {
+        const addMcpResult = require("child_process").spawnSync(
+          "npx",
+          [
+            "add-mcp",
+            "testdriver",
+            "--command",
+            "npx -p testdriverai testdriverai-mcp",
+            "--env",
+            "TD_API_KEY",
+          ],
+          {
+            cwd: targetDir,
+            stdio: "inherit", // Pass through stdin/stdout for interactive prompts
+            shell: process.platform === "win32",
+          }
+        );
+
+        if (addMcpResult.status === 0) {
+          progress("✓ MCP configured via add-mcp");
+        } else if (addMcpResult.status !== null) {
+          progress("⚠ MCP setup skipped or failed - you can run 'npx add-mcp testdriver' later");
+        }
+      } catch (err) {
+        progress("⚠ Could not run add-mcp - you can run 'npx add-mcp testdriver' later");
+      }
     }
 
     // 7. Create VSCode extensions recommendations
+    const vscodeDir = path.join(targetDir, ".vscode");
+    if (!fs.existsSync(vscodeDir)) {
+      fs.mkdirSync(vscodeDir, { recursive: true });
+    }
     const extensionsFile = path.join(vscodeDir, "extensions.json");
     if (!fs.existsSync(extensionsFile)) {
       const extensionsConfig = {

package/lib/vitest/hooks.mjs

@@ -22,6 +22,7 @@ import TestDriverSDK from "../../sdk.js";
 
 // Use createRequire to import CommonJS modules
 const require = createRequire(import.meta.url);
+const channelConfig = require("../../channel.json");
 
 /**
  * Minimum required Vitest major version
@@ -255,7 +256,7 @@ async function uploadLogsToReplay(client, dashcamUrl) {
     }
 
     // Use the SDK's configured API root (matches what the SDK uses for all other API calls)
-    const apiRoot = client.config?.TD_API_ROOT || process.env.TD_API_ROOT || "https://api.testdriver.ai";
+    const apiRoot = client.config?.TD_API_ROOT || process.env.TD_API_ROOT || channelConfig.channels[channelConfig.active];
 
     console.log(`[TestDriver] Uploading logs for replay ${replayId} to ${apiRoot}...`);
 

package/mcp-server/README.md

@@ -11,9 +11,19 @@ MCP server that enables AI agents to iteratively build TestDriver tests with vis
 
 ## Installation
 
-### Via npx (Recommended)
+### Quick Install (Recommended)
 
-No installation needed! Just configure your MCP client to use npx:
+Use `add-mcp` to automatically configure TestDriver for your MCP client:
+
+```bash
+npx add-mcp testdriver
+```
+
+This will prompt you to select your MCP client (VS Code, Cursor, Claude Desktop, etc.) and configure it automatically.
+
+### Manual Configuration
+
+If you prefer to configure manually, add the following to your MCP config file:
 
 ```json
 {

package/mcp-server/dist/codegen.js

@@ -141,7 +141,7 @@ export function generateActionCode(action, args, result) {
             return `const assertResult = await testdriver.assert("${escapeString(assertion)}");\nexpect(assertResult).toBeTruthy();`;
         }
         case "exec": {
-            const language = args.language || "js";
+            const language = args.language || "sh";
             const code = args.code;
             const timeout = args.timeout;
             if (code.includes("\n")) {

package/mcp-server/dist/server.mjs

@@ -687,6 +687,7 @@ registerAppTool(server, "find", {
         const duration = Date.now() - startTime;
         // Store cropped image for resource serving (instead of inline data URL)
         let croppedImageResourceUri;
+        let screenshotResourceUri;
         const croppedImage = rawResponse.croppedImage;
         if (croppedImage) {
             const imageData = croppedImage.startsWith('data:')
@@ -696,6 +697,20 @@ registerAppTool(server, "find", {
             // Remove croppedImage from response to avoid context bloat
             delete rawResponse.croppedImage;
         }
+        else if (!found) {
+            // Element not found and no cropped image - capture a fresh screenshot
+            // so the user can see what's currently visible on screen
+            try {
+                const screenshotBase64 = await sdk.agent.system.captureScreenBase64(1, false, true);
+                if (screenshotBase64) {
+                    screenshotResourceUri = storeImage(screenshotBase64, "screenshot");
+                    logger.debug("find: Captured screenshot for not-found state");
+                }
+            }
+            catch (e) {
+                logger.warn("find: Failed to capture screenshot for not-found state", { error: String(e) });
+            }
+        }
         // Remove extractedText and pixelDiffImage from response to reduce context bloat
         delete rawResponse.extractedText;
         delete rawResponse.pixelDiffImage;
@@ -717,6 +732,7 @@ registerAppTool(server, "find", {
             element: elementInfo,
             ref: elementRef,
             croppedImageResourceUri,
+            screenshotResourceUri,
             duration,
         }, generatedCode);
     }
@@ -786,6 +802,7 @@ registerAppTool(server, "findall", {
         const duration = Date.now() - startTime;
         // Store cropped image for resource serving (instead of inline data URL)
         let croppedImageResourceUri;
+        let screenshotResourceUri;
         const croppedImage = rawResponse.croppedImage;
         if (croppedImage) {
             const imageData = croppedImage.startsWith('data:')
@@ -795,6 +812,20 @@ registerAppTool(server, "findall", {
             // Remove croppedImage from response to avoid context bloat
             delete rawResponse.croppedImage;
         }
+        else if (count === 0) {
+            // No elements found and no cropped image - capture a fresh screenshot
+            // so the user can see what's currently visible on screen
+            try {
+                const screenshotBase64 = await sdk.agent.system.captureScreenBase64(1, false, true);
+                if (screenshotBase64) {
+                    screenshotResourceUri = storeImage(screenshotBase64, "screenshot");
+                    logger.debug("findall: Captured screenshot for not-found state");
+                }
+            }
+            catch (e) {
+                logger.warn("findall: Failed to capture screenshot for not-found state", { error: String(e) });
+            }
+        }
         // Remove extractedText and pixelDiffImage from response to reduce context bloat
         delete rawResponse.extractedText;
         delete rawResponse.pixelDiffImage;
@@ -810,6 +841,7 @@ registerAppTool(server, "findall", {
             refs,
             elements: elementInfos,
             croppedImageResourceUri,
+            screenshotResourceUri,
             duration,
         }, generatedCode);
     }
@@ -1029,6 +1061,7 @@ registerAppTool(server, "find_and_click", {
             const duration = Date.now() - startTime;
             // Store cropped image (screenshot) for resource serving
             let croppedImageResourceUri;
+            let screenshotResourceUri;
             const croppedImage = rawResponse.croppedImage;
             if (croppedImage) {
                 const imageData = croppedImage.startsWith('data:')
@@ -1037,6 +1070,20 @@ registerAppTool(server, "find_and_click", {
                 croppedImageResourceUri = storeImage(imageData, "screenshot");
                 delete rawResponse.croppedImage;
             }
+            else {
+                // No cropped image - capture a fresh screenshot so the user can see
+                // what's currently visible on screen when element was not found
+                try {
+                    const screenshotBase64 = await sdk.agent.system.captureScreenBase64(1, false, true);
+                    if (screenshotBase64) {
+                        screenshotResourceUri = storeImage(screenshotBase64, "screenshot");
+                        logger.debug("find_and_click: Captured screenshot for not-found state");
+                    }
+                }
+                catch (e) {
+                    logger.warn("find_and_click: Failed to capture screenshot for not-found state", { error: String(e) });
+                }
+            }
             // Remove extractedText and pixelDiffImage from response to reduce context bloat
             delete rawResponse.extractedText;
             delete rawResponse.pixelDiffImage;
@@ -1045,6 +1092,7 @@ registerAppTool(server, "find_and_click", {
                 action: "find_and_click",
                 error: "Element not found",
                 croppedImageResourceUri,
+                screenshotResourceUri,
                 duration
             });
         }
@@ -1372,9 +1420,9 @@ You can optionally provide a reference image URI to compare against a previous s
 });
 // Exec
 server.registerTool("exec", {
-    description: "Execute code in the sandbox (JavaScript, shell, or PowerShell)",
+    description: "Execute shell or PowerShell commands in the sandbox",
     inputSchema: z.object({
-        language: z.enum(["js", "sh", "pwsh"]).default("js"),
+        language: z.enum(["sh", "pwsh"]).default("sh"),
         code: z.string().describe("Code to execute"),
         timeout: z.number().default(30000).describe("Timeout in ms"),
     }),

package/mcp-server/src/codegen.ts

@@ -161,7 +161,7 @@ export function generateActionCode(
     }
 
     case "exec": {
-      const language = (args.language as string) || "js";
+      const language = (args.language as string) || "sh";
       const code = args.code as string;
       const timeout = args.timeout as number | undefined;