testdriverai 7.2.78 → 7.2.80

package/lib/init-project.js

@@ -0,0 +1,426 @@
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+/**
+ * Initialize a TestDriver project with all necessary files and configuration
+ * @param {Object} options - Initialization options
+ * @param {string} [options.targetDir] - Target directory (defaults to current working directory)
+ * @param {string} [options.apiKey] - TestDriver API key (will be saved to .env)
+ * @param {boolean} [options.skipInstall=false] - Skip npm install step
+ * @param {boolean} [options.interactive=false] - Whether to prompt for missing values (CLI mode)
+ * @returns {Promise<{success: boolean, results: string[], errors: string[]}>}
+ */
+async function initProject(options = {}) {
+  const targetDir = options.targetDir || process.cwd();
+  const results = [];
+  const errors = [];
+
+  try {
+    // Create target directory if it doesn't exist
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+      results.push(`✓ Created directory: ${targetDir}`);
+    }
+
+    // 1. Setup package.json
+    const packageJsonPath = path.join(targetDir, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+      const packageJson = {
+        name: path.basename(targetDir),
+        version: "1.0.0",
+        description: "TestDriver.ai test suite",
+        type: "module",
+        scripts: {
+          test: "vitest run",
+          "test:watch": "vitest",
+          "test:ui": "vitest --ui",
+        },
+        keywords: ["testdriver", "testing", "e2e"],
+        author: "",
+        license: "ISC",
+        engines: {
+          node: ">=20.19.0",
+        },
+      };
+      fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+      results.push("✓ Created package.json");
+    } else {
+      results.push("⊘ package.json already exists, skipping");
+    }
+
+    // 2. Create test directory and example files
+    const testDir = path.join(targetDir, "tests");
+    if (!fs.existsSync(testDir)) {
+      fs.mkdirSync(testDir, { recursive: true });
+    }
+
+    // Create login snippet file
+    const loginSnippetFile = path.join(testDir, "login.js");
+    if (!fs.existsSync(loginSnippetFile)) {
+      const loginSnippetContent = `/**
+ * Login snippet - reusable login function
+ * 
+ * This demonstrates how to create reusable test snippets that can be
+ * imported and used across multiple test files.
+ */
+export async function login(testdriver) {
+
+  // The password is displayed on screen, have TestDriver extract it
+  const password = await testdriver.extract('the password');
+
+  // Find the username field
+  const usernameField = await testdriver.find(
+    'username input'
+  );
+  await usernameField.click();
+
+  // Type username
+  await testdriver.type('standard_user');
+
+  // Enter password form earlier 
+  // Marked as secret so it's not logged or stored
+  await testdriver.pressKeys(['tab']);
+  await testdriver.type(password, { secret: true });
+
+  // Submit the form
+  await testdriver.find('submit button on the login form').click();
+}
+`;
+      fs.writeFileSync(loginSnippetFile, loginSnippetContent);
+      results.push("✓ Created login snippet: tests/login.js");
+    }
+
+    // Create example test file
+    const testFile = path.join(testDir, "example.test.js");
+    if (!fs.existsSync(testFile)) {
+      const vitestContent = `import { test, expect } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+import { login } from './login.js';
+
+test('should login and add item to cart', async (context) => {
+
+  // Create TestDriver instance - automatically connects to sandbox
+  const testdriver = TestDriver(context);
+
+  // Launch chrome and navigate to demo app
+  await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+  // Use the login snippet to handle authentication
+  // This demonstrates how to reuse test logic across multiple tests
+  await login(testdriver);
+
+  // Add item to cart
+  const addToCartButton = await testdriver.find(
+    'add to cart button under TestDriver Hat'
+  );
+  await addToCartButton.click();
+
+  // Open cart
+  const cartButton = await testdriver.find(
+    'cart button in the top right corner'
+  );
+  await cartButton.click();
+
+  // Verify item in cart
+  const result = await testdriver.assert('There is an item in the cart');
+  expect(result).toBeTruthy();
+  
+});
+`;
+      fs.writeFileSync(testFile, vitestContent);
+      results.push("✓ Created test file: tests/example.test.js");
+    }
+
+    // 3. Create vitest.config.js
+    const configFile = path.join(targetDir, "vitest.config.js");
+    if (!fs.existsSync(configFile)) {
+      const configContent = `import { defineConfig } from 'vitest/config';
+import TestDriver from 'testdriverai/vitest';
+
+// Note: dotenv is loaded automatically by the TestDriver SDK
+export default defineConfig({
+  test: {
+    testTimeout: 300000,
+    hookTimeout: 300000,
+    reporters: [
+      'default',
+      TestDriver(),
+    ],
+    setupFiles: ['testdriverai/vitest/setup'],
+  },
+});
+`;
+      fs.writeFileSync(configFile, configContent);
+      results.push("✓ Created vitest.config.js");
+    }
+
+    // 4. Create/update .gitignore
+    const gitignorePath = path.join(targetDir, ".gitignore");
+    let gitignoreContent = "";
+    if (fs.existsSync(gitignorePath)) {
+      gitignoreContent = fs.readFileSync(gitignorePath, "utf8");
+      if (!gitignoreContent.includes(".env")) {
+        const ignoresToAdd = [
+          "",
+          "# TestDriver.ai",
+          ".env",
+          "node_modules/",
+          "test-results/",
+          "*.log",
+        ];
+        const newContent = gitignoreContent.trim() + "\n" + ignoresToAdd.join("\n") + "\n";
+        fs.writeFileSync(gitignorePath, newContent);
+        results.push("✓ Updated .gitignore");
+      } else {
+        results.push("⊘ .env already in .gitignore");
+      }
+    } else {
+      const ignoresToAdd = [
+        "# TestDriver.ai",
+        ".env",
+        "node_modules/",
+        "test-results/",
+        "*.log",
+      ];
+      fs.writeFileSync(gitignorePath, ignoresToAdd.join("\n") + "\n");
+      results.push("✓ Created .gitignore");
+    }
+
+    // 5. Create GitHub Actions workflow
+    const workflowDir = path.join(targetDir, ".github", "workflows");
+    if (!fs.existsSync(workflowDir)) {
+      fs.mkdirSync(workflowDir, { recursive: true });
+    }
+
+    const workflowFile = path.join(workflowDir, "testdriver.yml");
+    if (!fs.existsSync(workflowFile)) {
+      const workflowContent = `name: TestDriver.ai Tests
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Run TestDriver.ai tests
+      env:
+        TD_API_KEY: \${{ secrets.TD_API_KEY }}
+      run: npx vitest run
+
+    - name: Upload test results
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: test-results
+        path: test-results/
+        retention-days: 30
+`;
+      fs.writeFileSync(workflowFile, workflowContent);
+      results.push("✓ Created GitHub workflow: .github/workflows/testdriver.yml");
+    } else {
+      results.push("⊘ GitHub workflow already exists");
+    }
+
+    // 6. Create VSCode MCP config
+    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@beta", "testdriverai-mcp"],
+            env: {
+              TD_API_KEY: "${input:testdriver-api-key}",
+            },
+          },
+        },
+      };
+      fs.writeFileSync(mcpConfigFile, JSON.stringify(mcpConfig, null, 2) + "\n");
+      results.push("✓ Created MCP config: .vscode/mcp.json");
+    } else {
+      results.push("⊘ MCP config already exists");
+    }
+
+    // 7. Create VSCode extensions recommendations
+    const extensionsFile = path.join(vscodeDir, "extensions.json");
+    if (!fs.existsSync(extensionsFile)) {
+      const extensionsConfig = {
+        recommendations: [
+          "vitest.explorer",
+        ],
+      };
+      fs.writeFileSync(extensionsFile, JSON.stringify(extensionsConfig, null, 2) + "\n");
+      results.push("✓ Created extensions config: .vscode/extensions.json");
+    } else {
+      results.push("⊘ Extensions config already exists");
+    }
+
+    // 8. Copy TestDriver skills
+    const skillsDestDir = path.join(targetDir, ".github", "skills");
+    const possibleSkillsSources = [
+      path.join(targetDir, "node_modules", "testdriverai", "ai", "skills"),
+      path.join(__dirname, "..", "ai", "skills"),
+    ];
+
+    let skillsSourceDir = null;
+    for (const source of possibleSkillsSources) {
+      if (fs.existsSync(source)) {
+        skillsSourceDir = source;
+        break;
+      }
+    }
+
+    if (skillsSourceDir) {
+      if (!fs.existsSync(skillsDestDir)) {
+        fs.mkdirSync(skillsDestDir, { recursive: true });
+      }
+
+      const skillDirs = fs.readdirSync(skillsSourceDir);
+      let copiedCount = 0;
+
+      for (const skillDir of skillDirs) {
+        const sourcePath = path.join(skillsSourceDir, skillDir);
+        const destPath = path.join(skillsDestDir, skillDir);
+
+        if (fs.statSync(sourcePath).isDirectory()) {
+          if (!fs.existsSync(destPath)) {
+            fs.mkdirSync(destPath, { recursive: true });
+          }
+
+          const skillFile = path.join(sourcePath, "SKILL.md");
+          if (fs.existsSync(skillFile)) {
+            fs.copyFileSync(skillFile, path.join(destPath, "SKILL.md"));
+            copiedCount++;
+          }
+        }
+      }
+
+      if (copiedCount > 0) {
+        results.push(`✓ Copied ${copiedCount} skills to .github/skills/`);
+      }
+    } else {
+      results.push("⚠ Skills directory not found (will be available after npm install)");
+    }
+
+    // 9. Copy TestDriver agents
+    const agentsDestDir = path.join(targetDir, ".github", "agents");
+    const possibleAgentsSources = [
+      path.join(targetDir, "node_modules", "testdriverai", "ai", "agents"),
+      path.join(__dirname, "..", "ai", "agents"),
+    ];
+
+    let agentsSourceDir = null;
+    for (const source of possibleAgentsSources) {
+      if (fs.existsSync(source)) {
+        agentsSourceDir = source;
+        break;
+      }
+    }
+
+    if (agentsSourceDir) {
+      if (!fs.existsSync(agentsDestDir)) {
+        fs.mkdirSync(agentsDestDir, { recursive: true });
+      }
+
+      const agentFiles = fs.readdirSync(agentsSourceDir).filter(f => f.endsWith(".md"));
+      let copiedCount = 0;
+
+      for (const agentFile of agentFiles) {
+        const sourcePath = path.join(agentsSourceDir, agentFile);
+        const agentName = agentFile.replace(".md", "");
+        const destPath = path.join(agentsDestDir, `${agentName}.agent.md`);
+
+        if (!fs.existsSync(destPath)) {
+          fs.copyFileSync(sourcePath, destPath);
+          copiedCount++;
+        }
+      }
+
+      if (copiedCount > 0) {
+        results.push(`✓ Copied ${copiedCount} agent(s) to .github/agents/`);
+      }
+    } else {
+      results.push("⚠ Agents directory not found (will be available after npm install)");
+    }
+
+    // 10. Handle API key if provided
+    if (options.apiKey) {
+      const envPath = path.join(targetDir, ".env");
+      let envContent = "";
+      
+      if (fs.existsSync(envPath)) {
+        envContent = fs.readFileSync(envPath, "utf8");
+        if (!envContent.includes("TD_API_KEY=")) {
+          envContent += "\n";
+        } else {
+          // Replace existing key
+          envContent = envContent.replace(/^TD_API_KEY=.*$/m, "");
+        }
+      }
+      
+      const newEnvContent = envContent.trim() + `\nTD_API_KEY=${options.apiKey}\n`;
+      fs.writeFileSync(envPath, newEnvContent);
+      results.push("✓ Saved API key to .env");
+    } else {
+      results.push("ℹ No API key provided - add it to .env manually:");
+      results.push("  TD_API_KEY=your_api_key");
+    }
+
+    // 11. Install dependencies (unless skipped)
+    if (!options.skipInstall) {
+      results.push("\n📦 Installing dependencies...");
+      try {
+        execSync("npm install -D vitest testdriverai@beta && npm install dotenv", {
+          cwd: targetDir,
+          stdio: "pipe",
+        });
+        results.push("✓ Dependencies installed successfully");
+      } catch (error) {
+        errors.push("Failed to install dependencies. Run manually:");
+        errors.push("  npm install -D vitest testdriverai@beta");
+        errors.push("  npm install dotenv");
+      }
+    } else {
+      results.push("\nℹ Skipped dependency installation. Run manually:");
+      results.push("  npm install -D vitest testdriverai@beta");
+      results.push("  npm install dotenv");
+    }
+
+    return { success: true, results, errors };
+  } catch (error) {
+    errors.push(`Initialization failed: ${error.message}`);
+    return { success: false, results, errors };
+  }
+}
+
+module.exports = { initProject };

package/mcp-server/dist/server.mjs

@@ -14,7 +14,7 @@ import * as Sentry from "@sentry/node";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
-import { fileURLToPath } from "url";
+import { fileURLToPath, pathToFileURL } from "url";
 import { z } from "zod";
 import { generateActionCode } from "./codegen.js";
 import { getProvisionOptions, SessionStartInputSchema } from "./provision-types.js";
@@ -406,7 +406,26 @@ Debug mode (connect to existing sandbox):
         logger.debug("session_start: Preview mode", { preview: previewMode });
         // Get IP from params or environment (for self-hosted instances)
         const instanceIp = params.ip || process.env.TD_IP;
-        sdk = new TestDriverSDK(process.env.TD_API_KEY || "", {
+        // Get API key - check multiple sources for GitHub Copilot coding agent compatibility
+        // 1. TD_API_KEY (standard environment variable)
+        // 2. COPILOT_MCP_TD_API_KEY (fallback for GitHub Copilot coding agent)
+        const apiKey = process.env.TD_API_KEY || process.env.COPILOT_MCP_TD_API_KEY || "";
+        if (!apiKey) {
+            logger.error("session_start: No API key found", {
+                hasTD_API_KEY: !!process.env.TD_API_KEY,
+                hasCOPILOT_MCP_TD_API_KEY: !!process.env.COPILOT_MCP_TD_API_KEY,
+                availableEnvVars: Object.keys(process.env).filter(k => k.includes('TD') || k.includes('COPILOT_MCP'))
+            });
+            return createToolResult(false, "No API key found. Please set TD_API_KEY or COPILOT_MCP_TD_API_KEY environment variable.", {
+                error: "Missing API key",
+                hint: "For GitHub Copilot coding agent, create a Copilot environment secret named COPILOT_MCP_TD_API_KEY"
+            });
+        }
+        logger.debug("session_start: API key found", {
+            source: process.env.TD_API_KEY ? "TD_API_KEY" : "COPILOT_MCP_TD_API_KEY",
+            keyPrefix: apiKey.substring(0, 7) + "..."
+        });
+        sdk = new TestDriverSDK(apiKey, {
             os: params.os,
             logging: false,
             apiRoot,
@@ -992,7 +1011,29 @@ registerAppTool(server, "find_and_click", {
         const found = element.found();
         if (!found) {
             logger.warn("find_and_click: Element not found", { description: params.description });
-            return createToolResult(false, `Element not found: "${params.description}"`, { error: "Element not found", duration: Date.now() - startTime });
+            // Capture screenshot to show current state even when element not found
+            const rawResponse = element._response || {};
+            const duration = Date.now() - startTime;
+            // Store cropped image (screenshot) for resource serving
+            let croppedImageResourceUri;
+            const croppedImage = rawResponse.croppedImage;
+            if (croppedImage) {
+                const imageData = croppedImage.startsWith('data:')
+                    ? croppedImage.replace(/^data:image\/\w+;base64,/, '')
+                    : croppedImage;
+                croppedImageResourceUri = storeImage(imageData, "screenshot");
+                delete rawResponse.croppedImage;
+            }
+            // Remove extractedText and pixelDiffImage from response to reduce context bloat
+            delete rawResponse.extractedText;
+            delete rawResponse.pixelDiffImage;
+            return createToolResult(false, `Element not found: "${params.description}"`, {
+                ...rawResponse,
+                action: "find_and_click",
+                error: "Element not found",
+                croppedImageResourceUri,
+                duration
+            });
         }
         const coords = element.getCoordinates();
         // Store element ref for later use (in case user wants to interact again)
@@ -1587,6 +1628,80 @@ Only use 'screenshot' when you explicitly want to show something to the human us
         return createToolResult(false, `Screenshot failed: ${error}`, { error: String(error) });
     }
 });
+// Init - Initialize a new TestDriver project
+server.registerTool("init", {
+    description: `Initialize a new TestDriver project with Vitest SDK examples.
+
+This creates:
+- package.json with proper dependencies
+- Example test files (tests/example.test.js, tests/login.js)
+- vitest.config.js
+- .gitignore
+- GitHub Actions workflow (.github/workflows/testdriver.yml)
+- VSCode MCP config (.vscode/mcp.json)
+- VSCode extensions recommendations (.vscode/extensions.json)
+- TestDriver skills (.github/skills/)
+- TestDriver agents (.github/agents/)
+- .env file with API key (if provided)
+
+API Key: The apiKey parameter is optional. If not provided, you'll need to manually add TD_API_KEY to the .env file after initialization. The project structure will still be created successfully.`,
+    inputSchema: z.object({
+        directory: z.string().optional().describe("Target directory (defaults to current working directory)"),
+        apiKey: z.string().optional().describe("TestDriver API key (will be saved to .env)"),
+        skipInstall: z.boolean().default(false).describe("Skip npm install step"),
+    }),
+}, async (params) => {
+    const startTime = Date.now();
+    const targetDir = params.directory ? path.resolve(params.directory) : process.cwd();
+    logger.info("init: Starting", { targetDir, hasApiKey: !!params.apiKey, skipInstall: params.skipInstall });
+    try {
+        // Import the shared init logic (dynamic import for ESM/CJS compatibility)
+        const initProjectPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "lib", "init-project.js");
+        const { initProject } = await import(pathToFileURL(initProjectPath).href);
+        // Run the shared init logic
+        const result = await initProject({
+            targetDir,
+            apiKey: params.apiKey,
+            skipInstall: params.skipInstall,
+        });
+        const duration = Date.now() - startTime;
+        logger.info("init: Completed", { targetDir, duration, success: result.success });
+        const nextSteps = `
+
+📚 Next steps:
+
+1. Run your tests:
+   npx vitest run
+
+2. Use AI agents to write tests:
+   Open VSCode/Cursor and use @testdriver agent
+
+3. MCP server configured:
+   TestDriver tools available via MCP in .vscode/mcp.json
+
+4. For CI/CD, add TD_API_KEY to your GitHub repository secrets:
+   Settings → Secrets → Actions → New repository secret
+
+Learn more at https://docs.testdriver.ai/v7/getting-started/
+`;
+        const allMessages = [...result.results, ...result.errors.map((e) => `⚠️ ${e}`)];
+        return createToolResult(result.success, result.success
+            ? `✅ TestDriver project initialized successfully!\n\n${allMessages.join("\n")}${nextSteps}`
+            : `⚠️ TestDriver project initialization completed with errors:\n\n${allMessages.join("\n")}`, {
+            action: "init",
+            targetDir,
+            filesCreated: result.results.length,
+            hasApiKey: !!params.apiKey,
+            errors: result.errors,
+            duration
+        });
+    }
+    catch (error) {
+        logger.error("init: Failed", { error: String(error), targetDir });
+        captureException(error, { tags: { tool: "init" }, extra: { targetDir } });
+        throw error;
+    }
+});
 // Start the server
 async function main() {
     logger.info("Starting TestDriver MCP Server", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.2.78",
+  "version": "7.2.80",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",
@@ -62,7 +62,8 @@
     "serve-report": "npx http-server . -p 8080 -o report.html",
     "report": "npm run generate-report && npm run serve-report",
     "generate:skills": "node scripts/generate-skills.js",
-    "prepack": "cd mcp-server && npm ci && npm run build"
+    "build:mcp": "cd mcp-server && npm ci && npm run build",
+    "prepublishOnly": "npm run build:mcp"
   },
   "author": "",
   "license": "ISC",

package/sdk.js

@@ -1279,12 +1279,24 @@ class TestDriverSDK {
     // Use provided API key or fall back to environment variable
     const resolvedApiKey = apiKey || process.env.TD_API_KEY;
 
+    // Handle preview mode with backwards compatibility for headless option
+    // Preview  can be "browser" (default), "ide", or "none" (headless)
+    let previewMode = options.preview || process.env.TD_PREVIEW;
+    
+    // Backwards compatibility: headless: true maps to preview: "none"
+    if (options.headless === true && !options.preview) {
+      previewMode = "none";
+    } else if (!previewMode) {
+      previewMode = "browser"; // default
+    }
+
     // Set up environment with API key
     const environment = {
       TD_API_KEY: resolvedApiKey,
       TD_API_ROOT: options.apiRoot || "https://testdriver-api.onrender.com",
       TD_RESOLUTION: options.resolution || "1366x768",
       TD_ANALYTICS: options.analytics !== false,
+      TD_PREVIEW: previewMode,
       ...options.environment,
     };