testdriverai 6.2.2 → 7.0.0

package/examples/sdk-cache-thresholds.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+/**
+ * TestDriver SDK - Cache Thresholds Example
+ *
+ * This example demonstrates how to configure cache thresholds for different
+ * operations and view cache debugging information.
+ *
+ * Run with VERBOSE=true to see cache hit/miss information:
+ * TD_API_KEY=your_key VERBOSE=true node examples/sdk-cache-thresholds.js
+ */
+
+const TestDriver = require("../sdk.js");
+
+(async () => {
+  try {
+    // Create client with custom cache thresholds
+    const client = new TestDriver(process.env.TD_API_KEY, {
+      os: "windows",
+      logging: true,
+      cacheThreshold: {
+        find: 0.03, // 3% difference = 97% similarity required for cache hit
+        findAll: 0.05, // 5% difference = 95% similarity required for cache hit
+      },
+    });
+
+    console.log("\n=== TestDriver SDK - Cache Thresholds Demo ===\n");
+    console.log("Cache thresholds configured:");
+    console.log("  - find: 0.03 (97% similarity required)");
+    console.log("  - findAll: 0.05 (95% similarity required)\n");
+    console.log("You can also override thresholds per-command:");
+    console.log('  await client.find("element", 0.01) // 99% similarity\n');
+
+    // Connect to sandbox
+    console.log("Connecting to sandbox...");
+    await client.connect({ headless: true });
+
+    // Open a test page
+    console.log("Opening test page...");
+    await client.focusApplication("Google Chrome");
+    await client.type("https://example.com");
+    await client.pressKeys(["enter"]);
+
+    // Wait for page load
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+
+    // Example 1: First find - should be a cache MISS
+    console.log("\n--- First find (cache MISS expected) ---");
+    const heading1 = await client.find("heading that says Example Domain");
+
+    if (heading1.found()) {
+      console.log(`✓ Element found at (${heading1.x}, ${heading1.y})`);
+    }
+
+    // Example 2: Second find - should be a cache HIT (same element, same screen)
+    console.log("\n--- Second find (cache HIT expected) ---");
+    // eslint-disable-next-line no-unused-vars
+    const _heading2 = await client.find("heading that says Example Domain");
+
+    // Example 3: Find with custom threshold override
+    console.log("\n--- Find with strict threshold (0.01 = 99% similarity) ---");
+    // eslint-disable-next-line no-unused-vars
+    const _heading3 = await client.find(
+      "heading that says Example Domain",
+      0.01,
+    );
+
+    // Example 4: Find a different element - cache MISS
+    console.log("\n--- Finding different element (cache MISS expected) ---");
+    // eslint-disable-next-line no-unused-vars
+    const _paragraph = await client.find(
+      "paragraph with text about illustrative examples",
+    );
+
+    // Example 5: Find the same paragraph again - cache HIT
+    console.log("\n--- Finding same paragraph again (cache HIT expected) ---");
+    // eslint-disable-next-line no-unused-vars
+    const _paragraph2 = await client.find(
+      "paragraph with text about illustrative examples",
+    );
+
+    console.log("\n=== Demo Complete ===");
+    console.log(
+      "\nNote: Run with VERBOSE=true to see detailed cache information:",
+    );
+    console.log("  - Cache hit/miss status");
+    console.log("  - Cache strategy (image/text)");
+    console.log("  - Similarity scores");
+    console.log("  - Response times\n");
+
+    await client.disconnect();
+  } catch (error) {
+    console.error("Test failed:", error);
+    process.exit(1);
+  }
+})();

package/examples/sdk-element-properties.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+/**
+ * TestDriver SDK - Element Properties Example
+ *
+ * This example demonstrates accessing all available properties from located elements,
+ * including coordinates, dimensions, confidence scores, screenshots, and more.
+ */
+
+const TestDriverSDK = require("../sdk");
+
+(async () => {
+  const client = new TestDriverSDK(process.env.TD_API_KEY);
+
+  try {
+    await client.connect();
+
+    // Example 1: Basic coordinate properties
+    console.log("=== Example 1: Basic Coordinates ===");
+    const button = await client.find("the login button");
+
+    if (button.found()) {
+      console.log("Button found!");
+      console.log("  X (top-left):", button.x);
+      console.log("  Y (top-left):", button.y);
+      console.log("  Center X:", button.centerX);
+      console.log("  Center Y:", button.centerY);
+      console.log("  Coordinates object:", button.getCoordinates());
+    }
+
+    // Example 2: Element dimensions
+    console.log("\n=== Example 2: Element Dimensions ===");
+    const input = await client.find("username input field");
+
+    if (input.found()) {
+      console.log("Input field found!");
+      console.log("  Width:", input.width);
+      console.log("  Height:", input.height);
+
+      if (input.boundingBox) {
+        console.log("  Bounding box:", input.boundingBox);
+      }
+    }
+
+    // Example 3: Confidence and text data
+    console.log("\n=== Example 3: Match Quality & Text ===");
+    const link = await client.find("sign up link");
+
+    if (link.found()) {
+      console.log("Link found!");
+      console.log("  Confidence score:", link.confidence);
+      console.log("  Text content:", link.text);
+      console.log("  Label:", link.label);
+    }
+
+    // Example 4: Screenshot data
+    console.log("\n=== Example 4: Element Screenshot ===");
+    const icon = await client.find("settings icon");
+
+    if (icon.found() && icon.screenshot) {
+      console.log("Icon found with screenshot!");
+      console.log("  Screenshot (base64) length:", icon.screenshot.length);
+
+      // You could save this to a file:
+      // const fs = require('fs');
+      // fs.writeFileSync('element.png', Buffer.from(icon.screenshot, 'base64'));
+    }
+
+    // Example 5: Full API response
+    console.log("\n=== Example 5: Full API Response ===");
+    const widget = await client.find("main content area");
+
+    if (widget.found()) {
+      const fullResponse = widget.getResponse();
+      console.log("Full API response:", JSON.stringify(fullResponse, null, 2));
+
+      // Log all available properties
+      if (fullResponse) {
+        console.log("\nAll available properties:");
+        Object.keys(fullResponse).forEach((key) => {
+          const value = fullResponse[key];
+          const preview =
+            typeof value === "string" && value.length > 50
+              ? value.substring(0, 50) + "..."
+              : value;
+          console.log(`  ${key}:`, preview);
+        });
+      }
+    }
+
+    // Example 6: Property-based validation
+    console.log("\n=== Example 6: Property-based Validation ===");
+    const message = await client.find("error message");
+
+    if (message.found()) {
+      // Check position
+      if (message.centerY < 200) {
+        console.log("✓ Error message is at top of screen");
+      }
+
+      // Check confidence
+      if (message.confidence && message.confidence > 0.9) {
+        console.log("✓ High confidence match (", message.confidence, ")");
+      }
+
+      // Check text content
+      if (message.text) {
+        console.log("✓ Message text:", message.text);
+      }
+    }
+
+    // Example 7: Position-based logic
+    console.log("\n=== Example 7: Position-based Logic ===");
+    const menu = await client.find("dropdown menu");
+
+    if (menu.found()) {
+      // Calculate positions
+      const offsetX = menu.x + 10;
+      const offsetY = menu.y + 20;
+      console.log("Menu position:", { x: menu.x, y: menu.y });
+      console.log("Offset position:", { x: offsetX, y: offsetY });
+
+      // Check if element is in viewport
+      const viewportHeight = 768;
+      if (menu.y > 0 && menu.y < viewportHeight) {
+        console.log("✓ Element is visible in viewport");
+      }
+    }
+
+    // Example 8: Conditional actions based on properties
+    console.log("\n=== Example 8: Conditional Actions ===");
+    const notification = await client.find("notification popup");
+
+    if (notification.found()) {
+      // Only interact if confidence is high
+      if (notification.confidence && notification.confidence > 0.8) {
+        console.log("High confidence, clicking notification");
+        await notification.click();
+      } else {
+        console.log("Low confidence, skipping interaction");
+        console.log("Debug info:", {
+          coordinates: notification.getCoordinates(),
+          confidence: notification.confidence,
+          text: notification.text,
+        });
+      }
+    }
+
+    await client.disconnect();
+  } catch (error) {
+    console.error("Test failed:", error);
+    await client.disconnect();
+    process.exit(1);
+  }
+})();

package/examples/sdk-simple-example.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+/**
+ * TestDriver SDK - Simple Example with AWESOME Logs 🎨
+ *
+ * A straightforward example showing the beautiful logging in action.
+ *
+ * Run: TD_API_KEY=your_key node examples/sdk-simple-example.js
+ */
+
+const TestDriver = require("../sdk.js");
+
+(async () => {
+  try {
+    // Create client with logging enabled (default)
+    const client = new TestDriver(process.env.TD_API_KEY, {
+      os: "windows",
+      logging: true, // This enables the awesome logs!
+    });
+
+    console.log("\n🚀 Starting TestDriver SDK Example...\n");
+
+    // Connect to sandbox - you'll see: 🔌 Connected
+    await client.connect({ headless: true });
+
+    // Navigate to a test page
+    await client.focusApplication("Google Chrome");
+    await client.type("https://example.com");
+    await client.pressKeys(["enter"]);
+
+    // Wait for page load
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+
+    // Find an element - you'll see: 🔍 Found "heading..." · 📍 (x, y) · ⏱️ XXXms · ⚡ cached
+    const heading = await client.find("heading that says Example Domain");
+
+    if (heading.found()) {
+      // Click the element - you'll see: 👆 Click "heading..."
+      await heading.click();
+    }
+
+    // Find another element
+    const link = await client.find("More information link");
+
+    if (link.found()) {
+      // Hover over it - you'll see: 👉 Hover "More information link"
+      await link.hover();
+    }
+
+    // Scroll down - you'll see: 📜 Scroll
+    await client.scroll("down", 300);
+
+    // Take a screenshot - you'll see: 📸 Screenshot
+    const screenshot = await client.screenshot();
+    console.log(`\n📸 Screenshot captured (${screenshot.length} bytes)\n`);
+
+    // Disconnect - you'll see: 🔌 Disconnected
+    await client.disconnect();
+
+    console.log("\n✅ Example completed successfully!\n");
+  } catch (error) {
+    console.error(`\n❌ Error: ${error.message}\n`);
+    process.exit(1);
+  }
+})();

package/examples/test-recording-example.test.js

@@ -0,0 +1,166 @@
+/**
+ * Example Vitest test file demonstrating TestDriver test recording
+ *
+ * This example shows how to:
+ * 1. Use TestDriver SDK in tests
+ * 2. Associate dashcam recordings with tests
+ * 3. Record custom test metadata
+ *
+ * Run with: npx vitest run examples/test-recording-example.test.js
+ */
+
+import { afterAll, beforeAll, describe, test } from "vitest";
+import TestDriverSDK from "../sdk.js";
+
+// Initialize TestDriver client
+let client;
+let runId;
+
+beforeAll(async () => {
+  // Connect to TestDriver
+  client = new TestDriverSDK({
+    apiKey: process.env.TD_API_KEY || "your-api-key",
+  });
+
+  await client.connect();
+
+  // Create a test run (usually done by the Vitest reporter, but shown here for demo)
+  runId = `example-${Date.now()}`;
+
+  const testRun = await client.createTestRun({
+    runId,
+    suiteName: "Example Test Suite",
+    platform: "windows",
+    git: {
+      repo: "testdriverai/cli",
+      branch: "main",
+      commit: "abc123",
+    },
+  });
+
+  console.log("Test run created:", testRun.runId);
+});
+
+afterAll(async () => {
+  // Complete the test run
+  await client.completeTestRun({
+    runId,
+    status: "passed",
+    totalTests: 3,
+    passedTests: 3,
+    failedTests: 0,
+  });
+
+  await client.disconnect();
+});
+
+describe("Login Tests", () => {
+  test("should display login page", async () => {
+    const testStart = Date.now();
+
+    try {
+      // Your test logic here
+      await client.click("Login");
+
+      // Record the test result
+      await client.recordTestCase({
+        runId,
+        testName: "should display login page",
+        testFile: "examples/test-recording-example.test.js",
+        suiteName: "Login Tests",
+        status: "passed",
+        startTime: testStart,
+        endTime: Date.now(),
+        duration: Date.now() - testStart,
+      });
+    } catch (error) {
+      // Record failure
+      await client.recordTestCase({
+        runId,
+        testName: "should display login page",
+        testFile: "examples/test-recording-example.test.js",
+        status: "failed",
+        errorMessage: error.message,
+        errorStack: error.stack,
+      });
+      throw error;
+    }
+  });
+
+  test("should login with valid credentials", async () => {
+    const testStart = Date.now();
+
+    try {
+      // Test logic
+      await client.type("username", "testuser");
+      await client.type("password", "password123");
+      await client.click("Submit");
+
+      // Wait for dashboard
+      await client.waitForText("Dashboard");
+
+      // Record success
+      await client.recordTestCase({
+        runId,
+        testName: "should login with valid credentials",
+        testFile: "examples/test-recording-example.test.js",
+        suiteName: "Login Tests",
+        status: "passed",
+        startTime: testStart,
+        endTime: Date.now(),
+        duration: Date.now() - testStart,
+        // Associate with dashcam replay (if you have the URL)
+        replayUrl: process.env.DASHCAM_REPLAY_URL,
+      });
+    } catch (error) {
+      await client.recordTestCase({
+        runId,
+        testName: "should login with valid credentials",
+        testFile: "examples/test-recording-example.test.js",
+        status: "failed",
+        errorMessage: error.message,
+        errorStack: error.stack,
+      });
+      throw error;
+    }
+  });
+
+  test("should show error with invalid credentials", async () => {
+    const testStart = Date.now();
+
+    try {
+      await client.type("username", "wrong");
+      await client.type("password", "wrong");
+      await client.click("Submit");
+
+      await client.waitForText("Invalid credentials");
+
+      await client.recordTestCase({
+        runId,
+        testName: "should show error with invalid credentials",
+        testFile: "examples/test-recording-example.test.js",
+        suiteName: "Login Tests",
+        status: "passed",
+        startTime: testStart,
+        endTime: Date.now(),
+        duration: Date.now() - testStart,
+        steps: [
+          { action: "type", target: "username", value: "wrong" },
+          { action: "type", target: "password", value: "wrong" },
+          { action: "click", target: "Submit" },
+          { action: "waitForText", target: "Invalid credentials" },
+        ],
+      });
+    } catch (error) {
+      await client.recordTestCase({
+        runId,
+        testName: "should show error with invalid credentials",
+        testFile: "examples/test-recording-example.test.js",
+        status: "failed",
+        errorMessage: error.message,
+        errorStack: error.stack,
+      });
+      throw error;
+    }
+  });
+});

package/interfaces/cli/lib/base.js

@@ -37,12 +37,14 @@ class BaseCommand extends Command {
   }
 
   sendToSandbox(message) {
+    if (!message) return;
+
     // ensure message is a string
     if (typeof message !== "string") {
       message = JSON.stringify(message);
     }
+
     this.agent.sandbox.send({
-      os: "linux",
       type: "output",
       output: Buffer.from(message).toString("base64"),
     });
@@ -95,7 +97,7 @@ class BaseCommand extends Command {
     });
 
     // Handle sandbox connection with pattern matching for subsequent events
-    this.agent.emitter.on("sandbox:connected", () => {
+    this.agent.emitter.once("sandbox:connected", () => {
       isConnected = true;
       // Once sandbox is connected, send all log and error events to sandbox
       this.agent.emitter.on("log:*", (message) => {
@@ -145,8 +147,12 @@ class BaseCommand extends Command {
       console.log(`Live test execution: `);
       if (this.agent.config.CI) {
         let u = new URL(url);
-        u = JSON.parse(u.searchParams.get("data"));
-        console.log(`${u.url}&view_only=true`);
+        try {
+          u = JSON.parse(u.searchParams.get("data"));
+          console.log(`${u.url}&view_only=true`);
+        } catch {
+          console.log(url);
+        }
       } else {
         console.log(url);
         await openBrowser(url);

package/interfaces/logger.js

@@ -21,6 +21,8 @@ class CustomTransport extends Transport {
         this.sandbox = require("../agent/lib/sandbox");
       }
 
+      console.log("CustomTransport log message:", message);
+
       if (this.sandbox && this.sandbox.instanceSocketConnected) {
         if (typeof message === "object") {
           console.log(chalk.cyan("protecting against base64 error"));
@@ -29,7 +31,6 @@ class CustomTransport extends Transport {
         }
 
         this.sandbox.send({
-          os: "linux",
           type: "output",
           output: Buffer.from(message).toString("base64"),
         });

package/interfaces/shared-test-state.mjs

@@ -0,0 +1,69 @@
+/**
+ * Shared Test State Module
+ *
+ * This module uses Node.js module caching to share state between
+ * the reporter process and worker processes in Vitest.
+ *
+ * Since Node.js caches modules, all imports of this file will
+ * receive the same state object instance.
+ */
+
+// Shared state object that persists across all imports
+const sharedState = {
+  testRun: null,
+  testRunId: null,
+  token: null,
+  apiKey: null,
+  apiRoot: null,
+  startTime: null,
+};
+
+/**
+ * Set the test run information
+ */
+export function setTestRunInfo(info) {
+  console.log("[SharedState] Setting test run info:", {
+    testRunId: info.testRunId,
+    hasToken: !!info.token,
+    hasTestRun: !!info.testRun,
+  });
+
+  if (info.testRun) sharedState.testRun = info.testRun;
+  if (info.testRunId) sharedState.testRunId = info.testRunId;
+  if (info.token) sharedState.token = info.token;
+  if (info.apiKey) sharedState.apiKey = info.apiKey;
+  if (info.apiRoot) sharedState.apiRoot = info.apiRoot;
+  if (info.startTime) sharedState.startTime = info.startTime;
+}
+
+/**
+ * Get the test run information
+ */
+export function getTestRunInfo() {
+  return {
+    testRun: sharedState.testRun,
+    testRunId: sharedState.testRunId,
+    token: sharedState.token,
+    apiKey: sharedState.apiKey,
+    apiRoot: sharedState.apiRoot,
+    startTime: sharedState.startTime,
+  };
+}
+
+/**
+ * Clear the test run information
+ */
+export function clearTestRunInfo() {
+  console.log("[SharedState] Clearing test run info");
+  sharedState.testRun = null;
+  sharedState.testRunId = null;
+  sharedState.token = null;
+  sharedState.startTime = null;
+}
+
+/**
+ * Direct access to state (for debugging)
+ */
+export function getState() {
+  return sharedState;
+}