testdriverai 7.0.0 → 7.1.0

package/testdriver/acceptance-sdk/setup/testHelpers.mjs

@@ -1,6 +1,8 @@
 /**
- * Test Helpers and Utilities
- * Shared functions for SDK tests
+ * Repo-Specific Test Helpers
+ * 
+ * These helpers are specific to this repository's test infrastructure.
+ * For reusable plugin helpers, import from 'testdriverai/vitest' (or src/vitest/index.mjs locally)
  */
 
 import crypto from "crypto";
@@ -9,36 +11,62 @@ import fs from "fs";
 import os from "os";
 import path, { dirname } from "path";
 import { fileURLToPath } from "url";
+
+// Import TestDriver SDK locally (for repo development)
 import TestDriver from "../../../sdk.js";
+
+// Import plugin helpers
 import {
   addDashcamLog,
   authDashcam,
   launchChrome,
+  launchChromeExtension,
+  launchChromeForTesting,
   runPostrun,
   runPrerun,
+  runPrerunChromeExtension,
+  runPrerunChromeForTesting,
   startDashcam,
   stopDashcam,
   waitForPage,
-} from "./lifecycleHelpers.mjs";
+} from "../../../src/vitest/lifecycle.mjs";
 
-// Re-export lifecycle helpers for backward compatibility
+import {
+  retryAsync,
+  setupEventLogging,
+  sleep,
+  waitFor,
+} from "../../../src/vitest/utils.mjs";
+
+// Re-export plugin lifecycle helpers for backward compatibility
 export {
   addDashcamLog,
   authDashcam,
   launchChrome,
+  launchChromeExtension,
+  launchChromeForTesting,
   runPostrun,
   runPrerun,
+  runPrerunChromeExtension,
+  runPrerunChromeForTesting,
   startDashcam,
   stopDashcam,
   waitForPage
 };
 
+// Re-export plugin utilities for backward compatibility
+  export {
+    retryAsync,
+    setupEventLogging,
+    sleep,
+    waitFor
+  };
+
 // Get the directory of the current module
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 // Load environment variables from .env file in the project root
-// Go up 3 levels from setup/ to reach the project root
 const envPath = path.resolve(__dirname, "../../../.env");
 config({ path: envPath });
 
@@ -46,12 +74,12 @@ config({ path: envPath });
 console.log("🔧 Environment variables loaded from:", envPath);
 console.log("   TD_API_KEY:", process.env.TD_API_KEY ? "✓ Set" : "✗ Not set");
 console.log("   TD_API_ROOT:", process.env.TD_API_ROOT || "Not set");
-console.log(
-  "   TD_OS:",
-  process.env.TD_OS || "Not set (will default to linux)",
-);
+console.log("   TD_OS:", process.env.TD_OS || "Not set (will default to linux)");
+
+// =============================================================================
+// TEST RESULTS STORAGE (Repo-specific CI/CD integration)
+// =============================================================================
 
-// Global test results storage
 const testResults = {
   tests: [],
   startTime: Date.now(),
@@ -64,16 +92,10 @@ const testResults = {
  * @param {string|null} dashcamUrl - Dashcam URL if available
  * @param {Object} sessionInfo - Session information
  */
-export function storeTestResult(
-  testName,
-  testFile,
-  dashcamUrl,
-  sessionInfo = {},
-) {
+export function storeTestResult(testName, testFile, dashcamUrl, sessionInfo = {}) {
   console.log(`📝 Storing test result: ${testName}`);
   console.log(`   Dashcam URL: ${dashcamUrl || "none"}`);
 
-  // Extract replay object ID from dashcam URL
   let replayObjectId = null;
   if (dashcamUrl) {
     const replayIdMatch = dashcamUrl.match(/\/replay\/([^?]+)/);
@@ -113,7 +135,6 @@ export function saveTestResults(outputPath = "test-results/sdk-summary.json") {
   const results = getTestResults();
   const dir = path.dirname(outputPath);
 
-  // Create directory if it doesn't exist
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
@@ -121,7 +142,6 @@ export function saveTestResults(outputPath = "test-results/sdk-summary.json") {
   fs.writeFileSync(outputPath, JSON.stringify(results, null, 2));
   console.log(`\n📊 Test results saved to: ${outputPath}`);
 
-  // Also print dashcam URLs to console
   console.log("\n🎥 Dashcam URLs:");
   results.tests.forEach((test) => {
     if (test.dashcamUrl) {
@@ -132,161 +152,48 @@ export function saveTestResults(outputPath = "test-results/sdk-summary.json") {
   return results;
 }
 
-/**
- * Intercept console logs and forward to TestDriver sandbox
- * @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,
-  };
-
-  // Create wrapper that forwards to sandbox
-  const createInterceptor = (level, originalMethod) => {
-    return function (...args) {
-      // Call original console method first
-      originalMethod.apply(console, args);
-
-      // Forward to sandbox if connected
-      if (client.sandbox && client.sandbox.instanceSocketConnected) {
-        try {
-          // Format the log message
-          const message = args
-            .map((arg) =>
-              typeof arg === "object"
-                ? JSON.stringify(arg, null, 2)
-                : String(arg),
-            )
-            .join(" ");
-
-          // Preserve ANSI color codes and emojis for rich sandbox output
-          // (don't add level prefix - sdk-log-formatter handles styling)
-          const logOutput = message;
-
-          client.sandbox.send({
-            type: "output",
-            output: Buffer.from(logOutput, "utf8").toString("base64"),
-          });
-        } catch (error) {
-          // Silently fail to avoid breaking the test
-          // Use original console to avoid infinite loop
-          originalConsole.error(
-            `[TestHelpers] Failed to forward log to sandbox:`,
-            error.message,
-          );
-        }
-      }
-    };
-  };
-
-  // 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(
-    `[TestHelpers] 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(
-      `[TestHelpers] Console interceptor removed for task: ${taskId}`,
-    );
-
-    // Clean up reference
-    delete client._consoleInterceptor;
-  }
-}
+// =============================================================================
+// REPO-SPECIFIC CLIENT CREATION
+// =============================================================================
 
 /**
- * Create a configured TestDriver client
+ * Create a configured TestDriver client for this repo's tests
+ * Uses local SDK path for development
  * @param {Object} options - Additional options
- * @param {Object} options.task - Vitest task context (from beforeEach/it context)
  * @returns {TestDriver} Configured client
  */
 export function createTestClient(options = {}) {
-  // Check if API key is set
   if (!process.env.TD_API_KEY) {
     console.error("\n❌ Error: TD_API_KEY is not set!");
     console.error("Please set it in one of the following ways:");
-    console.error(
-      "  1. Create a .env file in the project root with: TD_API_KEY=your_key",
-    );
-    console.error(
-      "  2. Pass it as an environment variable: TD_API_KEY=your_key npm run test:sdk",
-    );
+    console.error("  1. Create a .env file in the project root with: TD_API_KEY=your_key");
+    console.error("  2. Pass it as an environment variable: TD_API_KEY=your_key npm run test:sdk");
     console.error("  3. Export it in your shell: export TD_API_KEY=your_key\n");
     throw new Error("TD_API_KEY environment variable is required");
   }
 
-  // Determine OS from TEST_PLATFORM or TD_OS
-  const os = process.env.TEST_PLATFORM || "linux";
-
-  // Extract task context if provided - we use taskId but remove task from clientOptions
-  let taskId = options.task?.id || options.task?.name || null;
-
-  // Remove task from options before passing to TestDriver (eslint wants us to use 'task')
-  // eslint-disable-next-line no-unused-vars
+  const osConfig = process.env.TEST_PLATFORM || "linux";
   const { task, ...clientOptions } = options;
+  const taskId = task?.id || task?.name || null;
 
   const client = new TestDriver(process.env.TD_API_KEY, {
     resolution: "1366x768",
     analytics: true,
-    os: os, // Use OS from environment variable (windows or linux)
+    os: osConfig,
     apiKey: process.env.TD_API_KEY,
     apiRoot: process.env.TD_API_ROOT || "https://testdriver-api.onrender.com",
-    // headless: false,
-    // newSandbox: true, 
-    // ip: '18.217.194.23'
-    // ...clientOptions,
-    // cache: false,
+    newSandbox: true,
+    ...clientOptions,
   });
 
-  console.log(
-    "🔧 createTestClient: SDK created, cacheThresholds =",
-    client.cacheThresholds,
-  );
-
+  console.log("🔧 createTestClient: SDK created, cacheThresholds =", client.cacheThresholds);
   console.log(`[TestHelpers] Client OS configured as: ${client.os}`);
 
-  // Set Vitest task ID if available (for log filtering in parallel tests)
   if (taskId) {
     console.log(`[TestHelpers] Storing task ID on client: ${taskId}`);
-    // Store task ID directly on client for later use in teardown
     client.vitestTaskId = taskId;
-  } else {
-    console.log(`[TestHelpers] No task ID available`);
   }
 
-  // Enable detailed event logging if requested
   if (process.env.DEBUG_EVENTS === "true") {
     setupEventLogging(client);
   }
@@ -294,124 +201,67 @@ export function createTestClient(options = {}) {
   return client;
 }
 
-/**
- * Set up detailed event logging for debugging
- * @param {TestDriver} client - TestDriver client
- */
-export function setupEventLogging(client) {
-  const emitter = client.getEmitter();
-
-  // Log all events
-  emitter.on("**", function (data) {
-    const event = this.event;
-    if (event.startsWith("log:debug")) return; // Skip debug logs
-    console.log(`[EVENT] ${event}`, data || "");
-  });
-
-  // Log command lifecycle
-  emitter.on("command:start", (data) => {
-    console.log("🚀 Command started:", data);
-  });
-
-  emitter.on("command:success", (data) => {
-    console.log("✅ Command succeeded:", data);
-  });
-
-  emitter.on("command:error", (data) => {
-    console.error("❌ Command error:", data);
-  });
-
-  // Log sandbox events
-  emitter.on("sandbox:connected", () => {
-    console.log("🔌 Sandbox connected");
-  });
-
-  emitter.on("sandbox:authenticated", () => {
-    console.log("🔐 Sandbox authenticated");
-  });
-
-  emitter.on("sandbox:error", (error) => {
-    console.error("⚠️  Sandbox error:", error);
-  });
-
-  // Log SDK API calls
-  emitter.on("sdk:request", (data) => {
-    console.log("📤 SDK Request:", data);
-  });
-
-  emitter.on("sdk:response", (data) => {
-    console.log("📥 SDK Response:", data);
-  });
-}
+// =============================================================================
+// REPO-SPECIFIC LOGIN HELPER (for TestDriver Sandbox)
+// =============================================================================
 
 /**
- * Setup function to run before each test
- * Authenticates and connects to sandbox
+ * Perform login flow on TestDriver Sandbox
+ * This is specific to http://testdriver-sandbox.vercel.app/login
  * @param {TestDriver} client - TestDriver client
- * @param {Object} options - Connection options
- * @returns {Promise<Object>} Sandbox instance
+ * @param {string} username - Username (default: 'standard_user')
+ * @param {string} password - Password (default: retrieved from screen)
  */
-export async function setupTest(client, options = {}) {
-  await client.auth();
-  const instance = await client.connect({
-    ...options,
-  });
+export async function performLogin(client, username = "standard_user", password = null) {
+  await client.focusApplication("Google Chrome");
 
-  // Set up console interceptor after connection (needs sandbox to be connected)
-  if (client.vitestTaskId) {
-    setupConsoleInterceptor(client, client.vitestTaskId);
+  if (!password) {
+    password = await client.remember("the password");
   }
 
-  // Run prerun lifecycle if enabled
-  if (options.prerun !== false) {
-    await runPrerun(client);
-  }
+  const usernameField = await client.find(
+    "Username, label above the username input field on the login form",
+  );
+  await usernameField.click();
+  await client.type(username);
 
-  return instance;
+  await client.pressKeys(["tab"]);
+  await client.type(password, { secret: true });
+
+  await client.pressKeys(["tab"]);
+  await client.pressKeys(["enter"]);
 }
 
+// =============================================================================
+// SUITE TEST RUN MANAGEMENT (CI/CD Integration)
+// =============================================================================
+
 /**
  * Initialize a test run for the entire suite
- * Should be called once in beforeEach
  * @param {Object} suiteTask - Vitest suite task context
  * @returns {Promise<Object>} Test run info { runId, testRunDbId, token }
  */
 export async function initializeSuiteTestRun(suiteTask) {
   const apiKey = process.env.TD_API_KEY;
-  const apiRoot =
-    process.env.TD_API_ROOT || "https://testdriver-api.onrender.com";
+  const apiRoot = process.env.TD_API_ROOT || "https://testdriver-api.onrender.com";
 
   if (!apiKey || !globalThis.__testdriverPlugin) {
-    console.log(
-      `[TestHelpers] Skipping suite test run initialization - no API key or plugin`,
-    );
+    console.log(`[TestHelpers] Skipping suite test run initialization - no API key or plugin`);
     return null;
   }
 
-  // Check if test run already exists for this suite
-  const existingRun = globalThis.__testdriverPlugin.getSuiteTestRun(
-    suiteTask.id,
-  );
+  const existingRun = globalThis.__testdriverPlugin.getSuiteTestRun(suiteTask.id);
   if (existingRun) {
-    console.log(
-      `[TestHelpers] Test run already exists for suite: ${existingRun.runId}`,
-    );
+    console.log(`[TestHelpers] Test run already exists for suite: ${existingRun.runId}`);
     return existingRun;
   }
 
   try {
-    console.log(
-      `[TestHelpers] Initializing test run for suite: ${suiteTask.name}`,
-    );
+    console.log(`[TestHelpers] Initializing test run for suite: ${suiteTask.name}`);
 
-    // Authenticate
-    const token = await globalThis.__testdriverPlugin.authenticateWithApiKey(
-      apiKey,
-      apiRoot,
-    );
+    const token = await globalThis.__testdriverPlugin.authenticateWithApiKey(apiKey, apiRoot);
     console.log(`[TestHelpers] ✅ Authenticated for suite`);
 
-    // Create test run for the suite
     const runId = `${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
     const testFile = suiteTask.file?.name || "unknown";
     const testRunData = {
@@ -419,46 +269,53 @@ export async function initializeSuiteTestRun(suiteTask) {
       suiteName: suiteTask.name || testFile,
     };
 
-    const testRunResponse =
-      await globalThis.__testdriverPlugin.createTestRunDirect(
-        token,
-        apiRoot,
-        testRunData,
-      );
+    const testRunResponse = await globalThis.__testdriverPlugin.createTestRunDirect(
+      token,
+      apiRoot,
+      testRunData,
+    );
     const testRunDbId = testRunResponse.data?.id;
 
     const runInfo = { runId, testRunDbId, token };
-
-    // Store in plugin state
     globalThis.__testdriverPlugin.setSuiteTestRun(suiteTask.id, runInfo);
 
-    // Set environment variables for the reporter to use
     process.env.TD_TEST_RUN_ID = runId;
     process.env.TD_TEST_RUN_DB_ID = testRunDbId;
     process.env.TD_TEST_RUN_TOKEN = token;
 
-    console.log(
-      `[TestHelpers] ✅ Created test run for suite: ${runId} (DB ID: ${testRunDbId})`,
-    );
-
+    console.log(`[TestHelpers] ✅ Created test run for suite: ${runId} (DB ID: ${testRunDbId})`);
     return runInfo;
   } catch (error) {
-    console.error(
-      `[TestHelpers] ❌ Failed to initialize suite test run:`,
-      error.message,
-    );
+    console.error(`[TestHelpers] ❌ Failed to initialize suite test run:`, error.message);
     return null;
   }
 }
 
+// =============================================================================
+// SETUP/TEARDOWN HELPERS
+// =============================================================================
+
+/**
+ * Setup function to run before each test
+ * @param {TestDriver} client - TestDriver client
+ * @param {Object} options - Connection options
+ * @returns {Promise<Object>} Sandbox instance
+ */
+export async function setupTest(client, options = {}) {
+  await client.auth();
+  const instance = await client.connect({ ...options });
+
+  if (options.prerun !== false) {
+    await runPrerun(client);
+  }
+
+  return instance;
+}
+
 /**
  * Teardown function to run after each test
  * @param {TestDriver} client - TestDriver client
  * @param {Object} options - Teardown options
- * @param {Object} options.task - Vitest task context (optional, for storing in task.meta)
- * @param {string} options.dashcamUrl - Dashcam URL if already retrieved
- * @param {boolean} options.postrun - Whether to run postrun lifecycle (default: true)
- * @param {boolean} options.disconnect - Whether to disconnect client (default: true)
  * @returns {Promise<Object>} Session info including dashcam URL
  */
 export async function teardownTest(client, options = {}) {
@@ -467,14 +324,10 @@ export async function teardownTest(client, options = {}) {
   console.log("🧹 Running teardown...");
 
   try {
-    // Run postrun lifecycle if enabled and dashcamUrl not already provided
     if (options.postrun !== false && !dashcamUrl) {
       dashcamUrl = await runPostrun(client);
 
-      // Store dashcamUrl in client for reporter access
-      if (dashcamUrl) {
-        // Extract replay object ID from URL
-        // URL format: https://app.testdriver.ai/replay/{replayObjectId}?share={shareToken}
+      if (dashcamUrl && options.task) {
         const replayIdMatch = dashcamUrl.match(/\/replay\/([^?]+)/);
         const replayObjectId = replayIdMatch ? replayIdMatch[1] : null;
 
@@ -483,20 +336,15 @@ export async function teardownTest(client, options = {}) {
           console.log(`📝 Replay Object ID: ${replayObjectId}`);
         }
 
-        // Store dashcam URL in task meta
-        if (options.task) {
-          options.task.meta.testdriverDashcamUrl = dashcamUrl;
-          options.task.meta.testdriverReplayObjectId = replayObjectId;
-          console.log(
-            `[TestHelpers] ✅ Stored dashcam URL in task.meta for test: ${options.task.name}`,
-          );
-        }
+        options.task.meta.testdriverDashcamUrl = dashcamUrl;
+        options.task.meta.testdriverReplayObjectId = replayObjectId;
+        console.log(`[TestHelpers] ✅ Stored dashcam URL in task.meta for test: ${options.task.name}`);
       }
     } else {
       console.log("⏭️  Postrun skipped (disabled in options)");
     }
 
-    // Write test result to a file for the reporter to pick up (cross-process communication)
+    // Write test result to temp file for reporter
     if (options.task) {
       const testResultFile = path.join(
         os.tmpdir(),
@@ -505,58 +353,42 @@ export async function teardownTest(client, options = {}) {
       );
 
       try {
-        // Ensure directory exists
         const dir = path.dirname(testResultFile);
         if (!fs.existsSync(dir)) {
           fs.mkdirSync(dir, { recursive: true });
         }
 
-        // Get test file path
-        const testFile =
-          options.task.file?.filepath || options.task.file?.name || "unknown";
-
-        // Calculate test order (index within parent suite)
+        const testFile = options.task.file?.filepath || options.task.file?.name || "unknown";
         let testOrder = 0;
         if (options.task.suite && options.task.suite.tasks) {
           testOrder = options.task.suite.tasks.indexOf(options.task);
         }
 
-        // Note: Duration is calculated by Vitest and passed via result.duration
-        // We don't need to track start time ourselves
+        const result = options.task.result?.();
+        const duration = result?.duration || 0;
 
-        // Write test result with dashcam URL, platform, and metadata
         const testResult = {
           testId: options.task.id,
           testName: options.task.name,
           testFile: testFile,
           testOrder: testOrder,
           dashcamUrl: dashcamUrl,
-          replayObjectId: dashcamUrl
-            ? dashcamUrl.match(/\/replay\/([^?]+)/)?.[1]
-            : null,
-          platform: client.os, // Include platform from SDK client (source of truth)
+          replayObjectId: dashcamUrl ? dashcamUrl.match(/\/replay\/([^?]+)/)?.[1] : null,
+          platform: client.os,
           timestamp: Date.now(),
+          duration: duration,
         };
 
         fs.writeFileSync(testResultFile, JSON.stringify(testResult, null, 2));
-        console.log(
-          `[TestHelpers] ✅ Wrote test result to file: ${testResultFile} (testFile: ${testFile}, testOrder: ${testOrder})`,
-        );
+        console.log(`[TestHelpers] ✅ Wrote test result to file: ${testResultFile}`);
       } catch (error) {
-        console.error(
-          `[TestHelpers] ❌ Failed to write test result file:`,
-          error.message,
-        );
+        console.error(`[TestHelpers] ❌ Failed to write test result file:`, error.message);
       }
     }
   } catch (error) {
     console.error("❌ Error in postrun:", error);
     console.error("❌ Error stack:", error.stack);
   } finally {
-    // Remove console interceptor before disconnecting
-    removeConsoleInterceptor(client);
-
-    // Only disconnect if not explicitly disabled
     if (options.disconnect !== false) {
       console.log("🔌 Disconnecting client...");
       try {
@@ -564,14 +396,12 @@ export async function teardownTest(client, options = {}) {
         console.log("✅ Client disconnected");
       } catch (disconnectError) {
         console.error("❌ Error disconnecting:", disconnectError.message);
-        // Don't throw - we're already in cleanup
       }
     } else {
       console.log("⏭️  Disconnect skipped (disabled in options)");
     }
   }
 
-  // Extract replay object ID from dashcam URL
   let replayObjectId = null;
   if (dashcamUrl) {
     const replayIdMatch = dashcamUrl.match(/\/replay\/([^?]+)/);
@@ -586,63 +416,5 @@ export async function teardownTest(client, options = {}) {
   };
 
   console.log("📊 Session info:", JSON.stringify(sessionInfo, null, 2));
-
   return sessionInfo;
 }
-
-/**
- * Perform login flow (reusable snippet)
- * @param {TestDriver} client - TestDriver client
- * @param {string} username - Username (default: 'standard_user')
- * @param {string} password - Password (default: retrieved from screen)
- */
-export async function performLogin(
-  client,
-  username = "standard_user",
-  password = null,
-) {
-  await client.focusApplication("Google Chrome");
-
-  // Get password from screen if not provided
-  if (!password) {
-    password = await client.remember("the password");
-  }
-
-  const usernameField = await client.find(
-    "Username, label above the username input field on the login form",
-  );
-  await usernameField.click();
-  await client.type(username);
-
-  // Enter password
-  await client.pressKeys(["tab"]);
-  await client.type(password);
-
-  // Submit form
-  await client.pressKeys(["tab"]);
-  await client.pressKeys(["enter"]);
-}
-
-/**
- * Wait with retry logic
- * @param {Function} fn - Async function to retry
- * @param {number} retries - Number of retries (default: 3)
- * @param {number} delay - Delay between retries in ms (default: 1000)
- * @returns {Promise} Result of successful execution
- */
-export async function retryAsync(fn, retries = 3, delay = 1000) {
-  let lastError;
-
-  for (let i = 0; i < retries; i++) {
-    try {
-      return await fn();
-    } catch (error) {
-      lastError = error;
-      if (i < retries - 1) {
-        await new Promise((resolve) => setTimeout(resolve, delay));
-      }
-    }
-  }
-
-  throw lastError;
-}