testdriverai 6.2.2 → 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/test/mcp-example-test.yaml

@@ -0,0 +1,27 @@
+name: MCP Example Test
+description: Test created using TestDriver MCP to navigate example.com
+
+steps:
+  # Open Chrome browser and navigate to example.com
+  - exec:
+      code: Start-Process chrome "https://example.com"
+      language: pwsh
+      timeout: 5000
+
+  # Wait for the page to load
+  - wait-for-text:
+      text: Example Domain
+      timeout: 10000
+
+  # Assert that the Example Domain heading is visible
+  - assert:
+      expect: The text "Example Domain" is visible on the page
+
+  # Click on the "Learn more" link
+  - hover-text:
+      text: Learn more
+      action: click
+
+  # Wait for navigation to complete
+  - wait:
+      timeout: 2000

package/testdriver/acceptance-sdk/QUICK_REFERENCE.md

@@ -0,0 +1,61 @@
+# SDK Test Reporting - Quick Reference
+
+## 🚀 Commands
+
+```bash
+# Run all tests
+npm run test:sdk
+
+# View terminal summary
+npm run test:sdk:results
+
+# Open HTML report
+npm run test:sdk:report
+
+# Watch mode (dev)
+npm run test:sdk:watch
+
+# Interactive UI
+npm run test:sdk:ui
+```
+
+## 📊 What You Get
+
+### Locally
+
+1. **Console**: Verbose logs with full test output
+2. **Terminal Summary**: `npm run test:sdk:results` - Quick pass/fail counts
+3. **HTML Report**: `npm run test:sdk:report` - Interactive browser viewer
+
+### GitHub Actions
+
+1. **Step Summary**: Markdown tables in workflow summary page
+2. **Test Summary Action**: Badge counts and annotations
+3. **Artifacts**: Download junit.xml, results.json, and index.html
+
+## 📁 Output Files
+
+```
+test-results/
+├── junit.xml       # For CI/CD tools
+├── results.json    # Machine-readable
+└── index.html      # Interactive report
+```
+
+## ⚡ Quick Tips
+
+- **Debugging failures?** → `npm run test:sdk:report` (HTML has best error context)
+- **Quick status check?** → `npm run test:sdk:results` (terminal summary)
+- **PR review?** → Check GitHub Actions summary tab
+- **Need history?** → Download artifacts from GitHub Actions runs
+
+## 🔍 GitHub Summary Preview
+
+Every test run creates a summary with:
+
+- ✅ Pass/fail counts table
+- ❌ Failed test details with errors
+- ✅ List of all passing tests
+- ⏱️ Duration metrics
+
+Find it: Actions → Your workflow run → Summary tab

package/testdriver/acceptance-sdk/README.md

@@ -0,0 +1,128 @@
+# TestDriver SDK Acceptance Tests
+
+This directory contains acceptance tests for the TestDriver SDK using Vitest.
+
+## Running Tests
+
+### Run All Tests (Cross-Platform)
+
+```bash
+npm run test:sdk
+```
+
+### Run Platform-Specific Tests
+
+Use the `TEST_PLATFORM` environment variable to run tests for a specific platform:
+
+```bash
+# Run Windows-only tests
+npm run test:sdk:windows
+
+# Run macOS-only tests
+npm run test:sdk:mac
+
+# Run Linux-only tests
+npm run test:sdk:linux
+```
+
+Or set the environment variable directly:
+
+```bash
+TEST_PLATFORM=windows npm run test:sdk
+TEST_PLATFORM=mac npm run test:sdk
+```
+
+## Test Organization
+
+### Cross-Platform Tests
+
+Tests without a platform suffix run on all platforms:
+
+- `hover-text.test.mjs` - Runs everywhere
+- `scroll.test.mjs` - Runs everywhere
+- `screenshot.test.mjs` - Runs everywhere
+
+### Platform-Specific Tests
+
+Platform-specific tests use naming conventions:
+
+- `*.windows.test.mjs` - Windows-only tests (e.g., `exec-pwsh.windows.test.mjs`)
+- `*.mac.test.mjs` - macOS-only tests
+- `*.linux.test.mjs` - Linux-only tests
+
+### Conditional Test Skipping
+
+Some tests use `skipIf` to conditionally skip based on the platform:
+
+```javascript
+it.skipIf(() => testdriver.os === "linux")(
+  "should run on Windows/Mac",
+  async () => {
+    // This test will be skipped on Linux
+  },
+);
+```
+
+## Environment Variables
+
+- `TEST_PLATFORM` - Filter tests by platform (`windows`, `mac`, `linux`)
+- `TD_OS` - Override the sandbox OS (defaults to `linux`)
+- `TD_API_KEY` - Your TestDriver API key (required)
+- `TD_API_ROOT` - API endpoint (optional)
+- `DEBUG_ENV` - Show environment variable loading (optional)
+- `DEBUG_EVENTS` - Enable detailed event logging (optional)
+
+## Examples
+
+```bash
+# Run only Windows tests on a Windows sandbox
+TEST_PLATFORM=windows npm run test:sdk
+
+# Run all tests but use a Windows sandbox
+TD_OS=windows npm run test:sdk
+
+# Run with debugging enabled
+DEBUG_ENV=true DEBUG_EVENTS=true npm run test:sdk
+
+# Watch mode for development
+npm run test:sdk:watch
+
+# Generate coverage report
+npm run test:sdk:coverage
+```
+
+## Test Structure
+
+Each test follows this pattern:
+
+```javascript
+import { afterEach, beforeEach, describe, it } from "vitest";
+import {
+  createTestClient,
+  setupTest,
+  teardownTest,
+} from "./setup/testHelpers.mjs";
+
+describe("My Test", () => {
+  let testdriver;
+
+  beforeEach(async () => {
+    testdriver = createTestClient();
+    await setupTest(testdriver);
+  });
+
+  afterEach(async () => {
+    await teardownTest(testdriver);
+  });
+
+  it("should do something", async () => {
+    // Your test logic
+  });
+});
+```
+
+## See Also
+
+- [SDK README](../../SDK_README.md) - Full SDK documentation
+- [Quick Reference](./QUICK_REFERENCE.md) - SDK method quick reference
+- [Test Reporting](./TEST_REPORTING.md) - Test recording and reporting docs