testdriverai 7.0.0 → 7.1.0

package/src/vitest/utils.mjs

@@ -0,0 +1,150 @@
+/**
+ * Utility Functions for TestDriver Vitest Plugin
+ * 
+ * General-purpose utilities for testing with TestDriver.
+ * 
+ * @example
+ * import { retryAsync, setupEventLogging } from 'testdriverai/vitest';
+ */
+
+/**
+ * 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);
+  });
+}
+
+/**
+ * Retry an async function with configurable attempts and delay
+ * @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
+ * @throws {Error} Last error if all retries fail
+ * 
+ * @example
+ * const result = await retryAsync(
+ *   () => testdriver.find("Flaky Element"),
+ *   5,
+ *   2000
+ * );
+ */
+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;
+}
+
+/**
+ * Wait for a condition to be true
+ * @param {Function} condition - Function that returns boolean or Promise<boolean>
+ * @param {object} options - Wait options
+ * @param {number} options.timeout - Maximum time to wait in ms (default: 30000)
+ * @param {number} options.interval - Poll interval in ms (default: 500)
+ * @param {string} options.message - Error message if timeout (default: "Condition not met")
+ * @returns {Promise<boolean>} True if condition met
+ * @throws {Error} If timeout reached
+ * 
+ * @example
+ * await waitFor(() => element.exists(), { timeout: 10000 });
+ */
+export async function waitFor(condition, options = {}) {
+  const { 
+    timeout = 30000, 
+    interval = 500, 
+    message = "Condition not met within timeout" 
+  } = options;
+  
+  const startTime = Date.now();
+  
+  while (Date.now() - startTime < timeout) {
+    try {
+      const result = await condition();
+      if (result) {
+        return true;
+      }
+    } catch (error) {
+      // Condition threw, keep polling
+    }
+    await new Promise(resolve => setTimeout(resolve, interval));
+  }
+  
+  throw new Error(`${message} (timeout: ${timeout}ms)`);
+}
+
+/**
+ * Sleep for a specified duration
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ * 
+ * @example
+ * await sleep(1000); // Wait 1 second
+ */
+export function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Generate a unique test ID
+ * @param {string} prefix - Optional prefix for the ID
+ * @returns {string} Unique ID
+ */
+export function generateTestId(prefix = "test") {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 8);
+  return `${prefix}-${timestamp}-${random}`;
+}

package/test/dashcam.test.js

@@ -0,0 +1,137 @@
+/**
+ * Dashcam Class - Unit Tests
+ * Tests for the new Dashcam class
+ */
+
+const { Dashcam } = require('../src/core');
+
+// Mock TestDriver client
+class MockTestDriver {
+  constructor(os = 'linux') {
+    this.os = os;
+    this.commands = [];
+  }
+  
+  async exec(shell, command, timeout, silent) {
+    this.commands.push({ shell, command, timeout, silent });
+    
+    // Mock responses
+    if (command.includes('npm prefix -g')) {
+      return this.os === 'windows' 
+        ? 'C:\\Users\\testdriver\\AppData\\Roaming\\npm'
+        : '/usr/local';
+    }
+    
+    if (command.includes('stop')) {
+      return 'Recording stopped\nReplay URL: https://app.testdriver.ai/replay/abc123?share=xyz';
+    }
+    
+    return 'OK';
+  }
+  
+  wait(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+async function testDashcamCreation() {
+  console.log('🧪 Test: Dashcam creation');
+  
+  const client = new MockTestDriver();
+  const dashcam = new Dashcam(client);
+  
+  console.assert(dashcam.client === client, 'Client should be stored');
+  console.assert(dashcam.recording === false, 'Should not be recording initially');
+  console.assert(dashcam._authenticated === false, 'Should not be authenticated initially');
+  
+  console.log('✅ Dashcam creation test passed');
+}
+
+async function testDashcamWithOptions() {
+  console.log('\n🧪 Test: Dashcam with options');
+  
+  const client = new MockTestDriver();
+  const dashcam = new Dashcam(client, {
+    apiKey: 'custom-key',
+    autoStart: true,
+    logs: [
+      { type: 'file', path: '/tmp/test.log', name: 'Test Log' }
+    ]
+  });
+  
+  console.assert(dashcam.apiKey === 'custom-key', 'Custom API key should be used');
+  console.assert(dashcam.autoStart === true, 'Auto start should be enabled');
+  console.assert(dashcam.logs.length === 1, 'Logs should be stored');
+  
+  console.log('✅ Dashcam options test passed');
+}
+
+async function testErrorOnMissingClient() {
+  console.log('\n🧪 Test: Error when client missing');
+  
+  try {
+    new Dashcam();
+    console.error('❌ Should have thrown error');
+    process.exit(1);
+  } catch (error) {
+    console.assert(
+      error.message.includes('TestDriver client'),
+      'Error message should mention TestDriver client'
+    );
+  }
+  
+  console.log('✅ Missing client error test passed');
+}
+
+async function testStopReturnsUrl() {
+  console.log('\n🧪 Test: Stop returns URL');
+  
+  const client = new MockTestDriver();
+  const dashcam = new Dashcam(client);
+  
+  dashcam.recording = true;  // Simulate recording state
+  const url = await dashcam.stop();
+  
+  console.assert(url !== null, 'URL should be returned');
+  console.assert(url.includes('replay'), 'URL should contain replay');
+  console.assert(dashcam.recording === false, 'Should stop recording');
+  
+  console.log('✅ Stop returns URL test passed');
+  console.log('   URL:', url);
+}
+
+async function testIsRecording() {
+  console.log('\n🧪 Test: isRecording method');
+  
+  const client = new MockTestDriver();
+  const dashcam = new Dashcam(client);
+  
+  let recording = await dashcam.isRecording();
+  console.assert(recording === false, 'Should not be recording initially');
+  
+  dashcam.recording = true;
+  recording = await dashcam.isRecording();
+  console.assert(recording === true, 'Should return recording state');
+  
+  console.log('✅ isRecording test passed');
+}
+
+async function runAllTests() {
+  console.log('🚀 Running Dashcam class tests...\n');
+  
+  try {
+    await testDashcamCreation();
+    await testDashcamWithOptions();
+    await testErrorOnMissingClient();
+    await testStopReturnsUrl();
+    await testIsRecording();
+    
+    console.log('\n✅ All tests passed!');
+  } catch (error) {
+    console.error('\n❌ Test failed:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+runAllTests();

package/testdriver/acceptance-sdk/assert.test.mjs

@@ -3,42 +3,24 @@
  * Converted from: testdriver/acceptance/assert.yaml
  */
 
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  createTestClient,
-  setupTest,
-  teardownTest,
-} from "./setup/testHelpers.mjs";
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../../src/vitest/hooks.mjs";
 
 describe("Assert Test", () => {
-  let testdriver;
-
-  beforeEach(async (context) => {
-    // Create a new client for each test
-    testdriver = createTestClient({
-      task: context.task,
-    });
-
-    await setupTest(testdriver);
-  }, 600000);
-
-  afterEach(async (context) => {
-    // Teardown after each test, passing the individual test context
-    const sessionInfo = await teardownTest(testdriver, {
-      task: context.task,
+  it("should assert the testdriver login page shows", async (context) => {
+    const testdriver = TestDriver(context, { headless: true, newSandbox: true });
+    
+    // provision.chrome() automatically calls ready() and starts dashcam
+    await testdriver.provision.chrome({
+      url: 'http://testdriver-sandbox.vercel.app/login',
     });
-    console.log(
-      `[Test] Teardown complete, dashcam URL: ${sessionInfo.dashcamUrl}`,
-    );
-  });
 
-  it("should assert the testdriver login page shows", async () => {
     // Assert the TestDriver.ai Sandbox login page is displayed
-    // const result = await testdriver.assert(
-    //   "the TestDriver.ai Sandbox login page is displayed",
-    // );
+    const result = await testdriver.assert(
+      "the TestDriver.ai Sandbox login page is displayed",
+    );
 
-    // expect(result).toBeTruthy();
-    return true;
+    expect(result).toBeTruthy();
   });
 });
+

package/testdriver/acceptance-sdk/auto-cache-key-demo.test.mjs

@@ -0,0 +1,56 @@
+/**
+ * TestDriver SDK - Auto Cache Key Demo
+ * 
+ * This test demonstrates the auto-generated cache key feature.
+ * When no cacheKey is provided, TestDriver will automatically generate
+ * one based on the hash of this test file.
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../../src/vitest/hooks.mjs";
+
+describe("Auto Cache Key Demo", () => {
+  it("should use auto-generated cache key based on file hash", async (context) => {
+    // NOTE: No cacheKey is provided here!
+    // TestDriver will automatically generate one from the hash of this file
+    const testdriver = TestDriver(context, { 
+      headless: true, 
+      newSandbox: true 
+      // cacheKey NOT specified - will be auto-generated
+    });
+    
+    // The cache key should be auto-generated
+    console.log('Auto-generated cache key:', testdriver.options.cacheKey);
+    expect(testdriver.options.cacheKey).toBeTruthy();
+    expect(testdriver.options.cacheKey).toMatch(/^[0-9a-f]{16}$/); // 16 hex chars
+    
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+    // First find - will be cached with auto-generated key
+    const signInButton1 = await testdriver.find(
+      "Sign In, black button below the password field"
+    );
+    
+    // Second find - should hit cache because it's the same file (same cache key)
+    const signInButton2 = await testdriver.find(
+      "Sign In, black button below the password field"
+    );
+    
+    expect(signInButton1.found()).toBe(true);
+    expect(signInButton2.found()).toBe(true);
+  });
+
+  it("should use same auto-generated cache key for multiple tests in the same file", async (context) => {
+    // This test is in the same file, so it should get the same auto-generated cache key
+    const testdriver = TestDriver(context, { 
+      headless: true, 
+      newSandbox: true 
+    });
+    
+    console.log('Auto-generated cache key (test 2):', testdriver.options.cacheKey);
+    expect(testdriver.options.cacheKey).toBeTruthy();
+    
+    // If you modify this file, the hash (and therefore cache key) will change,
+    // invalidating the cache for this test file
+  });
+});

package/testdriver/acceptance-sdk/chrome-extension.test.mjs

@@ -0,0 +1,89 @@
+/**
+ * Chrome Extension Loading Demo
+ * Demonstrates how to load Chrome extensions using Chrome for Testing
+ * 
+ * This test shows how to launch Chrome with a specific extension loaded
+ * by using its Chrome Web Store extension ID.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import TestDriver from "../../sdk.js";
+import {
+  runPostrun,
+  runPrerunChromeExtension
+} from "./setup/lifecycleHelpers.mjs";
+
+describe("Chrome Extension Loading", () => {
+  let client;
+  let dashcamUrl;
+
+  beforeAll(async () => {
+    // Initialize TestDriver client
+    client = await TestDriver.create({
+      apiKey: process.env.TD_API_KEY,
+      apiRoot: process.env.TD_API_ROOT,
+      os: "linux",
+      verbosity: 1,
+    });
+
+    // Run prerun with uBlock Origin extension loaded
+    // Extension ID: cjpalhdlnbpafiamejdnhcphjbkeiagm
+    await runPrerunChromeExtension(client, "cjpalhdlnbpafiamejdnhcphjbkeiagm");
+  });
+
+  afterAll(async () => {
+    if (client) {
+      dashcamUrl = await runPostrun(client);
+      await client.cleanup();
+    }
+  });
+
+  it("should load Chrome with extension and verify functionality", async () => {
+    // Focus Chrome browser
+    await client.focusApplication("Google Chrome");
+
+    // Verify the page loaded
+    const pageElement = await client.find("TestDriver.ai Sandbox");
+    expect(pageElement.found()).toBe(true);
+
+    // Test basic interaction to ensure Chrome is working with the extension
+    const signInButton = await client.find(
+      "Sign In, black button below the password field",
+    );
+    await signInButton.click();
+
+    // Verify error message appears
+    const result = await client.assert(
+      "an error shows that fields are required",
+    );
+    expect(result).toBeTruthy();
+
+    console.log("✅ Chrome extension loaded successfully!");
+    if (dashcamUrl) {
+      console.log("🎥 Dashcam URL:", dashcamUrl);
+    }
+  });
+
+  it("should demonstrate extension interaction", async () => {
+    // You can add specific tests here to interact with the extension
+    // For example, if testing uBlock Origin, you might:
+    // 1. Navigate to a page with ads
+    // 2. Verify ads are blocked
+    // 3. Access the extension's popup or settings
+    
+    await client.focusApplication("Google Chrome");
+    
+    // Example: Navigate to extension management page to verify it's loaded
+    await client.exec(
+      "sh",
+      `xdotool key --clearmodifiers ctrl+shift+e`,
+      5000,
+      true
+    );
+
+    // Wait a moment for the extensions page to potentially load
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    console.log("✅ Extension interaction test completed");
+  });
+});

package/testdriver/acceptance-sdk/drag-and-drop.test.mjs

@@ -3,31 +3,19 @@
  * Converted from: testdriver/acceptance/drag-and-drop.yaml
  */
 
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  createTestClient,
-  setupTest,
-  teardownTest,
-} from "./setup/testHelpers.mjs";
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../../src/vitest/hooks.mjs";
 
 const isLinux = (process.env.TD_OS || "linux") === "linux";
 
 describe("Drag and Drop Test", () => {
-  let testdriver;
-
-  beforeEach(async (context) => {
-    testdriver = createTestClient({ task: context.task });
-
-    await setupTest(testdriver);
-  });
-
-  afterEach(async (context) => {
-    await teardownTest(testdriver, { task: context.task });
-  });
-
   it.skipIf(isLinux)(
     'should drag "New Text Document" to "Recycle Bin"',
-    async () => {
+    async (context) => {
+      const testdriver = TestDriver(context, { headless: true });
+      await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+      //
       // Show the desktop
       await testdriver.pressKeys(["win", "d"]);
 

package/testdriver/acceptance-sdk/element-not-found.test.mjs

@@ -3,28 +3,15 @@
  * Tests that finding a non-existent element returns properly without timing out
  */
 
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  createTestClient,
-  setupTest,
-  teardownTest,
-} from "./setup/testHelpers.mjs";
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../../src/vitest/hooks.mjs";
 
 describe("Element Not Found Test", () => {
-  let testdriver;
+  it("should handle non-existent element gracefully without timing out", async (context) => {
+    const testdriver = TestDriver(context, { headless: true });
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
 
-  beforeEach(async (context) => {
-    testdriver = createTestClient({ task: context.task });
-
-    await setupTest(testdriver);
-  });
-
-  afterEach(async (context) => {
-    await teardownTest(testdriver, { task: context.task });
-  });
-
-  it("should handle non-existent element gracefully without timing out", async () => {
-    await testdriver.focusApplication("Google Chrome");
+    //
 
     // Try to find an element that definitely doesn't exist
     const element = await testdriver.find(

package/testdriver/acceptance-sdk/exec-js.test.mjs

@@ -3,27 +3,15 @@
  * Converted from: testdriver/acceptance/exec-js.yaml
  */
 
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  createTestClient,
-  setupTest,
-  teardownTest,
-} from "./setup/testHelpers.mjs";
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../../src/vitest/hooks.mjs";
 
 describe("Exec JavaScript Test", () => {
-  let testdriver;
+  it("should fetch user data from API and enter email", async (context) => {
+    const testdriver = TestDriver(context, { headless: true });
+    await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
 
-  beforeEach(async (context) => {
-    testdriver = createTestClient({ task: context.task });
-
-    await setupTest(testdriver);
-  });
-
-  afterEach(async (context) => {
-    await teardownTest(testdriver, { task: context.task });
-  });
-
-  it("should fetch user data from API and enter email", async () => {
+    //
     // Execute JavaScript to fetch user data
     const userEmail = await testdriver.exec(
       "js",

package/testdriver/acceptance-sdk/exec-output.test.mjs

@@ -3,29 +3,17 @@
  * Converted from: testdriver/acceptance/exec-output.yaml
  */
 
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  createTestClient,
-  setupTest,
-  teardownTest,
-} from "./setup/testHelpers.mjs";
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../../src/vitest/hooks.mjs";
 
 describe("Exec Output Test", () => {
-  let testdriver;
-
-  beforeEach(async (context) => {
-    testdriver = createTestClient({ task: context.task });
-
-    await setupTest(testdriver);
-  });
-
-  afterEach(async (context) => {
-    await teardownTest(testdriver, { task: context.task });
-  });
-
-  it.skipIf(() => testdriver.os === "linux")(
+  it.skipIf(process.env.TD_OS === "linux")(
     "should set date using PowerShell and navigate to calendar",
-    async () => {
+    async (context) => {
+      const testdriver = TestDriver(context, { headless: true });
+      await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+      //
       // Generate date in query string format
       const queryString = await testdriver.exec(
         "pwsh",

package/testdriver/acceptance-sdk/exec-pwsh.test.mjs

@@ -3,33 +3,21 @@
  * Converted from: testdriver/acceptance/exec-shell.yaml
  */
 
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  createTestClient,
-  setupTest,
-  teardownTest,
-} from "./setup/testHelpers.mjs";
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../../src/vitest/hooks.mjs";
 
 describe("Exec PowerShell Test", () => {
-  let testdriver;
-
-  beforeEach(async (context) => {
-    testdriver = createTestClient({ task: context.task });
-
-    await setupTest(testdriver);
-  });
-
-  afterEach(async (context) => {
-    await teardownTest(testdriver, { task: context.task });
-  });
-
-  it.skipIf(() => testdriver.os === "linux")(
+  it.skipIf(process.env.TD_OS === "linux")(
     "should generate random email using PowerShell and enter it",
-    async () => {
+    async (context) => {
+      const testdriver = TestDriver(context, { headless: true });
+      await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+      //
       // Generate random email using PowerShell
-      const randomEmail = await testdriver.exec(
-        "pwsh",
-        `
+      const randomEmail = await testdriver.exec({
+        language: "pwsh",
+        code: `
 # Random email generator in PowerShell
 
 # Arrays of possible names and domains
@@ -49,8 +37,8 @@ $email = "$first.$last$number@$domain".ToLower()
 # Output
 Write-Output "$email"
     `,
-        10000,
-      );
+        timeout: 10000,
+      });
 
       // Enter the email in username field
       const usernameField = await testdriver.find(