testdriverai 7.0.0 → 7.1.0

package/src/vitest/hooks.mjs

@@ -0,0 +1,298 @@
+/**
+ * Vitest Hooks for TestDriver
+ * 
+ * Provides lifecycle management for TestDriver in Vitest tests.
+ * 
+ * @example
+ * import { TestDriver } from 'testdriverai/vitest/hooks';
+ * 
+ * test('my test', async (context) => {
+ *   const testdriver = TestDriver(context, { headless: true });
+ *   
+ *   await testdriver.ready();
+ *   await testdriver.provision.chrome({ url: 'https://example.com' });
+ *   await testdriver.find('button').click();
+ * });
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import TestDriverSDK from '../../sdk.js';
+
+/**
+ * Intercept console logs and write to a log file on the remote machine
+ * This allows test logs to appear in Dashcam recordings
+ * @param {TestDriver} client - TestDriver client instance
+ * @param {string} taskId - Unique task identifier for this test
+ */
+function setupConsoleInterceptor(client, taskId) {
+  // Store original console methods
+  const originalConsole = {
+    log: console.log,
+    error: console.error,
+    warn: console.warn,
+    info: console.info,
+  };
+
+  // Determine log file path based on OS
+  const logPath = client.os === "windows" 
+    ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
+    : "/tmp/testdriver.log";
+
+  // Store log path on client for later use
+  client._testLogPath = logPath;
+
+  // Track if we're currently writing to avoid infinite loops
+  let isWriting = false;
+
+  // Create wrapper that writes to log file
+  const createInterceptor = (level, originalMethod) => {
+    return function (...args) {
+      // Call original console method first
+      originalMethod.apply(console, args);
+
+      // Skip if already writing to avoid infinite loops
+      if (isWriting) return;
+
+      // Format the log message
+      const message = args
+        .map((arg) =>
+          typeof arg === "object"
+            ? JSON.stringify(arg, null, 2)
+            : String(arg),
+        )
+        .join(" ");
+
+      // Also send to sandbox for immediate visibility
+      if (client.sandbox && client.sandbox.instanceSocketConnected) {
+  
+          client.sandbox.send({
+            type: "output",
+            output: Buffer.from(message, "utf8").toString("base64"),
+          });
+      }
+    };
+  };
+
+  // Replace console methods with interceptors
+  console.log = createInterceptor("log", originalConsole.log);
+  console.error = createInterceptor("error", originalConsole.error);
+  console.warn = createInterceptor("warn", originalConsole.warn);
+  console.info = createInterceptor("info", originalConsole.info);
+
+  // Store original methods and taskId on client for cleanup
+  client._consoleInterceptor = {
+    taskId,
+    original: originalConsole,
+  };
+
+  // Use original console for this message
+  originalConsole.log(
+    `[useTestDriver] Console interceptor enabled for task: ${taskId}`,
+  );
+}
+
+/**
+ * Remove console interceptor and restore original console methods
+ * @param {TestDriver} client - TestDriver client instance
+ */
+function removeConsoleInterceptor(client) {
+  if (client._consoleInterceptor) {
+    const { original, taskId } = client._consoleInterceptor;
+
+    // Restore original console methods
+    console.log = original.log;
+    console.error = original.error;
+    console.warn = original.warn;
+    console.info = original.info;
+
+    // Use original console for cleanup message
+    original.log(
+      `[useTestDriver] Console interceptor removed for task: ${taskId}`,
+    );
+
+    // Clean up reference
+    delete client._consoleInterceptor;
+  }
+}
+
+// Weak maps to store instances per test context
+const testDriverInstances = new WeakMap();
+const lifecycleHandlers = new WeakMap();
+
+/**
+ * Create a TestDriver client in a Vitest test with automatic lifecycle management
+ * 
+ * @param {object} context - Vitest test context (from async (context) => {})
+ * @param {object} options - TestDriver options (passed directly to TestDriver constructor)
+ * @param {string} [options.apiKey] - TestDriver API key (defaults to process.env.TD_API_KEY)
+ * @param {boolean} [options.headless] - Run sandbox in headless mode
+ * @param {boolean} [options.newSandbox] - Create new sandbox
+ * @param {boolean} [options.autoConnect=true] - Automatically connect to sandbox
+ * @returns {TestDriver} TestDriver client instance
+ * 
+ * @example
+ * test('my test', async (context) => {
+ *   const testdriver = TestDriver(context, { headless: true });
+ *   
+ *   // provision.chrome() automatically calls ready() and starts dashcam
+ *   await testdriver.provision.chrome({ url: 'https://example.com' });
+ *   
+ *   await testdriver.find('Login button').click();
+ * });
+ */
+export function TestDriver(context, options = {}) {
+  if (!context || !context.task) {
+    throw new Error('TestDriver() requires Vitest context. Pass the context parameter from your test function: test("name", async (context) => { ... })');
+  }
+  
+  // Return existing instance if already created for this test
+  if (testDriverInstances.has(context.task)) {
+    return testDriverInstances.get(context.task);
+  }
+  
+  // Get global plugin options if available
+  const pluginOptions = globalThis.__testdriverPlugin?.state?.testDriverOptions || {};
+  
+  // Merge options: plugin global options < test-specific options
+  const mergedOptions = { ...pluginOptions, ...options };
+  
+  // Extract TestDriver-specific options
+  const apiKey = mergedOptions.apiKey || process.env.TD_API_KEY;
+  
+  // Build config for TestDriverSDK constructor
+  const config = { ...mergedOptions };
+  delete config.apiKey;
+  
+  // Use TD_API_ROOT from environment if not provided in config
+  if (!config.apiRoot && process.env.TD_API_ROOT) {
+    config.apiRoot = process.env.TD_API_ROOT;
+  }
+  
+  const testdriver = new TestDriverSDK(apiKey, config);
+  testdriver.__vitestContext = context.task;
+  testDriverInstances.set(context.task, testdriver);
+  
+  // Auto-connect if enabled (default: true)
+  const autoConnect = config.autoConnect !== undefined ? config.autoConnect : true;
+  if (autoConnect) {
+    testdriver.__connectionPromise = (async () => {
+      try {
+        console.log('[testdriver] Connecting to sandbox...');
+        await testdriver.auth();
+        await testdriver.connect();
+        console.log('[testdriver] ✅ Connected to sandbox');
+        
+        // Set up console interceptor after connection
+        setupConsoleInterceptor(testdriver, context.task.id);
+        
+        // Create the log file on the remote machine
+        const shell = testdriver.os === "windows" ? "pwsh" : "sh";
+        const logPath = testdriver.os === "windows" 
+          ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
+          : "/tmp/testdriver.log";
+        
+        const createLogCmd = testdriver.os === "windows"
+          ? `New-Item -ItemType File -Path "${logPath}" -Force | Out-Null`
+          : `touch ${logPath}`;
+        
+        await testdriver.exec(shell, createLogCmd, 10000, true);
+        console.log('[testdriver] ✅ Created log file:', logPath);
+        
+        // Add automatic log tracking when dashcam starts
+        // Store original start method
+        const originalDashcamStart = testdriver.dashcam.start.bind(testdriver.dashcam);
+        testdriver.dashcam.start = async function() {
+          // Call original start (which handles auth)
+          await originalDashcamStart();
+          
+          // Add log file tracking after dashcam starts
+          try {
+            await testdriver.dashcam.addFileLog(logPath, "TestDriver Log");
+            console.log('[testdriver] ✅ Added log file to dashcam tracking');
+          } catch (error) {
+            console.warn('[testdriver] ⚠️  Failed to add log tracking:', error.message);
+          }
+        };
+      } catch (error) {
+        console.error('[testdriver] Error during setup:', error);
+        throw error;
+      }
+    })();
+  }
+  
+  // Register cleanup handler with dashcam.stop()
+  if (!lifecycleHandlers.has(context.task)) {
+    const cleanup = async () => {
+      console.log('[testdriver] Cleaning up TestDriver client...');
+      try {
+        // Stop dashcam if it was started
+        if (testdriver._dashcam && testdriver._dashcam.recording) {
+          try {
+            const dashcamUrl = await testdriver.dashcam.stop();
+            console.log('🎥 Dashcam URL:', dashcamUrl);
+            
+            // Write dashcam URL to file for the reporter (cross-process communication)
+            if (dashcamUrl) {
+              const testId = context.task.id;
+              const platform = testdriver.os || 'linux';
+              const testFile = context.task.file?.filepath || context.task.file?.name || 'unknown';
+              
+              // Create results directory if it doesn't exist
+              const resultsDir = path.join(os.tmpdir(), 'testdriver-results');
+              if (!fs.existsSync(resultsDir)) {
+                fs.mkdirSync(resultsDir, { recursive: true });
+              }
+              
+              // Write test result file
+              const testResultFile = path.join(resultsDir, `${testId}.json`);
+              const testResult = {
+                dashcamUrl,
+                platform,
+                testFile,
+                testOrder: 0,
+                sessionId: testdriver.getSessionId(),
+              };
+              
+              fs.writeFileSync(testResultFile, JSON.stringify(testResult, null, 2));
+              console.log(`[testdriver] ✅ Wrote dashcam URL to ${testResultFile}`);
+              
+              // Also register in memory if plugin is available
+              if (globalThis.__testdriverPlugin?.registerDashcamUrl) {
+                globalThis.__testdriverPlugin.registerDashcamUrl(testId, dashcamUrl, platform);
+                console.log(`[testdriver] ✅ Registered dashcam URL in memory for test ${testId}`);
+              }
+            }
+          } catch (error) {
+            // Log more detailed error information for debugging
+            console.error('❌ Failed to stop dashcam:', error.name || error.constructor?.name || 'Error');
+            if (error.message) console.error('   Message:', error.message);
+            // NotFoundError during cleanup is expected if sandbox already terminated
+            if (error.name === 'NotFoundError' || error.responseData?.error === 'NotFoundError') {
+              console.log('   ℹ️  Sandbox session already terminated - dashcam stop skipped');
+            }
+          }
+        }
+        
+        // Remove console interceptor before disconnecting
+        removeConsoleInterceptor(testdriver);
+        
+        // Wait for connection to finish if it was initiated
+        if (testdriver.__connectionPromise) {
+          await testdriver.__connectionPromise.catch(() => {}); // Ignore connection errors during cleanup
+        }
+        await testdriver.disconnect();
+        console.log('✅ Client disconnected');
+      } catch (error) {
+        console.error('Error disconnecting client:', error);
+      }
+    };
+    lifecycleHandlers.set(context.task, cleanup);
+    
+    // Vitest will call this automatically after the test
+    context.onTestFinished?.(cleanup);
+  }
+  
+  return testdriver;
+}

package/src/vitest/index.mjs

@@ -0,0 +1,64 @@
+/**
+ * TestDriver Vitest Integration
+ * 
+ * Main entry point for the TestDriver Vitest plugin.
+ * 
+ * @example
+ * // Basic usage - auto-managed lifecycle
+ * import { TestDriver } from 'testdriverai/vitest';
+ * 
+ * test('my test', async (context) => {
+ *   const testdriver = TestDriver(context, { headless: true });
+ *   await testdriver.provision.chrome({ url: 'https://example.com' });
+ *   await testdriver.find('Login button').click();
+ * });
+ * 
+ * @example
+ * // With extended test functions (it.once for setup steps)
+ * import { describe, it, expect, TestDriver } from 'testdriverai/vitest';
+ * 
+ * describe('My Suite', () => {
+ *   it.once('launch app', async (context) => {
+ *     const testdriver = TestDriver(context);
+ *     await testdriver.provision.chrome({ url: 'https://example.com' });
+ *   });
+ *   
+ *   it('click button', async (context) => {
+ *     const testdriver = TestDriver(context);
+ *     await testdriver.find('Button').click();
+ *   });
+ * });
+ * 
+ * @example
+ * // Using lifecycle helpers directly
+ * import { TestDriver, launchChrome, waitForPage } from 'testdriverai/vitest';
+ * 
+ * test('custom setup', async (context) => {
+ *   const testdriver = TestDriver(context);
+ *   await testdriver.ready();
+ *   await launchChrome(testdriver, 'https://example.com', { guest: true });
+ *   await waitForPage(testdriver, 'Welcome');
+ * });
+ */
+
+// Core TestDriver hook
+export { TestDriver } from './hooks.mjs';
+
+// Extended Vitest functions
+export {
+    afterAll, beforeAll, describe, expect, getTestDriver,
+    isReconnected, it,
+    test
+} from './extended.mjs';
+
+// Lifecycle helpers
+export {
+    addDashcamLog, authDashcam, launchChrome, launchChromeExtension, launchChromeForTesting, runPostrun, runPrerun, runPrerunChromeExtension, runPrerunChromeForTesting, startDashcam,
+    stopDashcam, waitForPage
+} from './lifecycle.mjs';
+
+// Utility functions
+export {
+    generateTestId, retryAsync, setupEventLogging, sleep, waitFor
+} from './utils.mjs';
+

package/src/vitest/lifecycle.mjs

@@ -0,0 +1,277 @@
+/**
+ * Lifecycle Helpers for TestDriver Vitest Plugin
+ * 
+ * Provides reusable lifecycle hook functions for common test patterns.
+ * These are thin wrappers around the Dashcam class.
+ * 
+ * @example
+ * import { launchChrome, waitForPage } from 'testdriverai/vitest';
+ * 
+ * test('my test', async (context) => {
+ *   const testdriver = TestDriver(context);
+ *   await testdriver.provision.chrome({ url: 'https://example.com' });
+ *   
+ *   // Or use manual lifecycle helpers
+ *   await launchChrome(testdriver, 'https://other-site.com');
+ *   await waitForPage(testdriver, 'Welcome');
+ * });
+ */
+
+import Dashcam from '../core/Dashcam.js';
+
+// Module-level cache to maintain Dashcam instance state across helper calls
+const dashcamInstances = new WeakMap();
+
+/**
+ * Get or create Dashcam instance for a client
+ * @private
+ * @param {TestDriver} client 
+ * @param {object} options 
+ * @returns {Dashcam}
+ */
+function getDashcam(client, options = {}) {
+  if (!dashcamInstances.has(client)) {
+    dashcamInstances.set(client, new Dashcam(client, options));
+  }
+  return dashcamInstances.get(client);
+}
+
+/**
+ * Authenticate dashcam with API key
+ * @param {TestDriver} client - TestDriver client
+ * @param {string} apiKey - Dashcam API key (default from environment)
+ */
+export async function authDashcam(client, apiKey) {
+  const dashcam = getDashcam(client, { apiKey });
+  await dashcam.auth();
+}
+
+/**
+ * Add log file tracking to dashcam
+ * @param {TestDriver} client - TestDriver client
+ * @param {string} logName - Name for the log in dashcam (default: "TestDriver Log")
+ */
+export async function addDashcamLog(client, logName = "TestDriver Log") {
+  const dashcam = getDashcam(client);
+  const logPath = client.os === "windows" 
+    ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
+    : "/tmp/testdriver.log";
+  
+  // Create log file first
+  const shell = client.os === "windows" ? "pwsh" : "sh";
+  if (client.os === "windows") {
+    await client.exec(shell, `New-Item -ItemType File -Path "${logPath}" -Force`, 10000, true);
+  } else {
+    await client.exec(shell, `touch ${logPath}`, 10000, true);
+  }
+  
+  await dashcam.addFileLog(logPath, logName);
+}
+
+/**
+ * Start dashcam recording
+ * @param {TestDriver} client - TestDriver client
+ */
+export async function startDashcam(client) {
+  const dashcam = getDashcam(client);
+  await dashcam.start();
+}
+
+/**
+ * Stop dashcam recording and retrieve URL
+ * @param {TestDriver} client - TestDriver client
+ * @returns {Promise<string|null>} Dashcam URL if available
+ */
+export async function stopDashcam(client) {
+  console.log("🎬 Stopping dashcam and retrieving URL...");
+  const dashcam = getDashcam(client);
+  const url = await dashcam.stop();
+  
+  if (url) {
+    console.log("✅ Found dashcam URL:", url);
+    console.log("🎥 Dashcam URL:", url);
+  } else {
+    console.warn("⚠️  No replay URL found in dashcam output");
+  }
+  
+  return url;
+}
+
+/**
+ * Launch Chrome browser
+ * @param {TestDriver} client - TestDriver client
+ * @param {string} url - URL to open
+ * @param {object} options - Browser options
+ * @param {boolean} options.guest - Launch in guest mode (default: true)
+ * @param {boolean} options.maximized - Start maximized (default: true)
+ */
+export async function launchChrome(client, url = "about:blank", options = {}) {
+  const { guest = true, maximized = true } = options;
+  const shell = client.os === "windows" ? "pwsh" : "sh";
+  
+  const guestFlag = guest ? "--guest" : "";
+  const maxFlag = maximized ? "--start-maximized" : "";
+
+  if (client.os === "windows") {
+    const args = [maxFlag, guestFlag, `"${url}"`].filter(Boolean).join('", "');
+    await client.exec(
+      "pwsh",
+      `Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList "${args}"`,
+      30000,
+    );
+  } else {
+    const flags = [maxFlag, "--disable-fre", "--no-default-browser-check", "--no-first-run", guestFlag].filter(Boolean).join(" ");
+    await client.exec(
+      shell,
+      `google-chrome ${flags} "${url}" >/dev/null 2>&1 &`,
+      30000,
+    );
+  }
+}
+
+/**
+ * Launch Chrome for Testing browser
+ * @param {TestDriver} client - TestDriver client
+ * @param {string} url - URL to open
+ * @param {object} options - Browser options
+ */
+export async function launchChromeForTesting(client, url = "about:blank", options = {}) {
+  const { guest = true, maximized = true } = options;
+  const shell = client.os === "windows" ? "pwsh" : "sh";
+  
+  const guestFlag = guest ? "--guest" : "";
+  const maxFlag = maximized ? "--start-maximized" : "";
+
+  if (client.os === "windows") {
+    // Fallback to regular Chrome on Windows
+    await launchChrome(client, url, options);
+  } else {
+    const flags = [maxFlag, "--disable-fre", "--no-default-browser-check", "--no-first-run", guestFlag].filter(Boolean).join(" ");
+    await client.exec(
+      shell,
+      `chrome-for-testing ${flags} "${url}" >/dev/null 2>&1 &`,
+      30000,
+    );
+  }
+}
+
+/**
+ * Launch Chrome with a Chrome extension loaded
+ * @param {TestDriver} client - TestDriver client
+ * @param {string} extensionId - Chrome Web Store extension ID
+ * @param {string} url - URL to open
+ * @example
+ * // Launch with uBlock Origin extension
+ * await launchChromeExtension(client, "cjpalhdlnbpafiamejdnhcphjbkeiagm");
+ */
+export async function launchChromeExtension(client, extensionId, url = "about:blank") {
+  const shell = client.os === "windows" ? "pwsh" : "sh";
+
+  if (client.os === "windows") {
+    await client.exec(
+      "pwsh",
+      `Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList "--start-maximized", "--load-extension=${extensionId}", "${url}"`,
+      30000,
+    );
+  } else {
+    await client.exec(
+      shell,
+      `chrome-for-testing --start-maximized --disable-fre --no-default-browser-check --no-first-run --load-extension=${extensionId} "${url}" >/dev/null 2>&1 &`,
+      30000,
+    );
+  }
+}
+
+/**
+ * Wait for page to load by polling for text
+ * @param {TestDriver} client - TestDriver client
+ * @param {string} text - Text to wait for
+ * @param {number} maxAttempts - Maximum number of attempts (default: 60)
+ * @param {number} pollInterval - Interval between polls in ms (default: 5000)
+ * @returns {Promise<boolean>} True if text was found
+ */
+export async function waitForPage(client, text, maxAttempts = 60, pollInterval = 5000) {
+  console.log("Waiting for page to load, looking for text:", text);
+  for (let i = 0; i < maxAttempts; i++) {
+    const element = await client.find(text);
+    if (element.found()) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  }
+  return false;
+}
+
+/**
+ * Run standard prerun lifecycle hooks
+ * Authenticates, starts dashcam, launches Chrome
+ * @param {TestDriver} client - TestDriver client
+ * @param {object} options - Options
+ * @param {string} options.url - URL to open (default: sandbox)
+ * @param {string} options.waitForText - Text to wait for after page load
+ */
+export async function runPrerun(client, options = {}) {
+  const { 
+    url = "http://testdriver-sandbox.vercel.app/", 
+    waitForText = "TestDriver.ai Sandbox" 
+  } = options;
+  
+  await authDashcam(client);
+  await addDashcamLog(client);
+  await startDashcam(client);
+  await launchChrome(client, url);
+  if (waitForText) {
+    await waitForPage(client, waitForText);
+  }
+}
+
+/**
+ * Run prerun with Chrome for Testing
+ * @param {TestDriver} client - TestDriver client
+ * @param {object} options - Options
+ */
+export async function runPrerunChromeForTesting(client, options = {}) {
+  const { 
+    url = "http://testdriver-sandbox.vercel.app/", 
+    waitForText = "TestDriver.ai Sandbox" 
+  } = options;
+  
+  await authDashcam(client);
+  await addDashcamLog(client);
+  await startDashcam(client);
+  await launchChromeForTesting(client, url);
+  if (waitForText) {
+    await waitForPage(client, waitForText);
+  }
+}
+
+/**
+ * Run prerun with Chrome extension
+ * @param {TestDriver} client - TestDriver client
+ * @param {string} extensionId - Chrome extension ID
+ * @param {object} options - Options
+ */
+export async function runPrerunChromeExtension(client, extensionId, options = {}) {
+  const { 
+    url = "http://testdriver-sandbox.vercel.app/", 
+    waitForText = "TestDriver.ai Sandbox" 
+  } = options;
+  
+  await authDashcam(client);
+  await addDashcamLog(client);
+  await startDashcam(client);
+  await launchChromeExtension(client, extensionId, url);
+  if (waitForText) {
+    await waitForPage(client, waitForText);
+  }
+}
+
+/**
+ * Run standard postrun lifecycle hooks
+ * Stops dashcam and returns URL
+ * @param {TestDriver} client - TestDriver client
+ * @returns {Promise<string|null>} Dashcam URL if available
+ */
+export async function runPostrun(client) {
+  return await stopDashcam(client);
+}