testdriverai 7.1.0 → 7.1.2

package/examples/sdk-awesome-logs-demo.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+/**
+ * TestDriver SDK - AWESOME Logs Demo 🎨
+ *
+ * This example showcases the beautiful, emoji-rich logging with great DX
+ * that makes your test output a joy to read!
+ *
+ * Run: TD_API_KEY=your_key node examples/sdk-awesome-logs-demo.js
+ */
+
+const TestDriver = require("../sdk.js");
+const { formatter } = require("../sdk-log-formatter.js");
+
+(async () => {
+  try {
+    console.log(
+      formatter.formatHeader("TestDriver SDK - AWESOME Logs Demo", "🚀"),
+    );
+
+    // Create client with logging enabled
+    const client = new TestDriver(process.env.TD_API_KEY, {
+      os: "windows",
+      logging: true,
+    });
+
+    // Demo 1: Connection
+    console.log(
+      formatter.formatConnection("connect", {
+        sandboxId: "demo-sandbox-123",
+        os: "Windows",
+      }),
+    );
+
+    await client.connect({ headless: true });
+
+    // Demo 2: Navigation
+    console.log(
+      "\n" + formatter.formatAction("navigate", "https://example.com"),
+    );
+    await client.focusApplication("Google Chrome");
+    await client.type("https://example.com");
+    await client.pressKeys(["enter"]);
+
+    // Demo 3: Wait with loading indicator
+    console.log("\n" + formatter.formatWaiting("for page to load", 2000));
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    // Demo 4: Finding elements (this will use the real formatElementFound from sdk.js)
+    console.log("\n" + formatter.formatHeader("Finding Elements", "🔍"));
+
+    const heading = await client.find("heading that says Example Domain");
+    // The actual find() call will emit the formatted log automatically
+
+    if (heading.found()) {
+      await heading.click();
+      // The click will also emit a formatted log automatically
+    }
+
+    // Demo 5: Multiple actions
+    console.log("\n" + formatter.formatHeader("User Actions", "👆"));
+
+    const link = await client.find("More information link");
+    if (link.found()) {
+      await link.hover();
+      await link.click();
+    }
+
+    // Demo 6: Typing
+    console.log(
+      "\n" +
+        formatter.formatAction("type", "search query", {
+          text: "TestDriver AI",
+        }),
+    );
+
+    // Demo 7: Scroll
+    console.log("\n" + formatter.formatAction("scroll", "down the page"));
+    await client.scroll("down", 300);
+
+    // Demo 8: Assertions
+    console.log("\n" + formatter.formatHeader("Assertions", "✅"));
+    console.log(
+      formatter.formatAssertion("Page title is correct", true, {
+        duration: "45ms",
+      }),
+    );
+    console.log(
+      formatter.formatAssertion("Footer is visible", true, {
+        duration: "23ms",
+      }),
+    );
+    console.log(
+      formatter.formatAssertion("Login button exists", false, {
+        duration: "1234ms",
+      }),
+    );
+
+    // Demo 9: Cache status
+    console.log("\n" + formatter.formatHeader("Cache Performance", "⚡"));
+    console.log(
+      formatter.formatCacheStatus(true, {
+        similarity: 0.98,
+        strategy: "image",
+      }),
+    );
+    console.log(
+      formatter.formatCacheStatus(false, {
+        strategy: "text",
+      }),
+    );
+
+    // Demo 10: Screenshot
+    console.log(
+      "\n" +
+        formatter.formatScreenshot({
+          path: "/tmp/testdriver-debug/screenshot-123.png",
+          size: "245 KB",
+        }),
+    );
+
+    // Demo 11: Progress
+    console.log("\n" + formatter.formatHeader("Multi-step Process", "📈"));
+    for (let i = 1; i <= 5; i++) {
+      console.log(formatter.formatProgress(i, 5, `Processing step ${i}`));
+      await new Promise((resolve) => setTimeout(resolve, 300));
+    }
+
+    // Demo 12: Divider
+    console.log("\n" + formatter.formatDivider());
+
+    // Demo 13: Test summary
+    console.log(
+      formatter.formatSummary({
+        passed: 12,
+        failed: 2,
+        skipped: 1,
+        total: 15,
+        duration: "45.23s",
+      }),
+    );
+
+    // Demo 14: Error handling
+    console.log(formatter.formatHeader("Error Examples", "🚨"));
+    console.log(
+      formatter.formatError(
+        "Element not found",
+        new Error("Timeout after 5000ms"),
+      ),
+    );
+    console.log(
+      formatter.formatError(
+        "Connection failed",
+        new Error("Network unreachable"),
+      ),
+    );
+
+    // Demo 15: Test lifecycle
+    console.log(formatter.formatTestStart("Login Flow Test"));
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    console.log(formatter.formatTestEnd("Login Flow Test", true, 2345));
+
+    console.log(formatter.formatTestStart("Checkout Process"));
+    await new Promise((resolve) => setTimeout(resolve, 800));
+    console.log(formatter.formatTestEnd("Checkout Process", false, 5678));
+
+    // Final summary
+    console.log("\n" + formatter.formatHeader("Demo Complete!", "🎉"));
+    console.log("\n✨ Your test logs now look AWESOME! ✨\n");
+
+    await client.disconnect();
+    console.log("\n" + formatter.formatConnection("disconnect"));
+  } catch (error) {
+    console.error(formatter.formatError("Demo failed", error));
+    process.exit(1);
+  }
+})();

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;
+    }
+  });
+});