testdriverai 7.2.37 → 7.2.39

package/.github/workflows/testdriver.yml

@@ -9,6 +9,10 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    
+    permissions:
+      contents: read
+      pull-requests: write  # Required to post comments on PRs
 
     steps:
     - uses: actions/checkout@v4
@@ -25,6 +29,8 @@ jobs:
     - name: Run TestDriver.ai tests
       env:
         TD_API_KEY: ${{ secrets.TD_API_KEY }}
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
       run: npx vitest run
 
     - name: Upload test results

package/interfaces/vitest-plugin.d.ts

@@ -0,0 +1,101 @@
+/**
+ * TypeScript definitions for TestDriver Vitest Plugin
+ * @module testdriverai/vitest/plugin
+ */
+
+import TestDriverSDK, { TestDriverOptions } from '../sdk';
+
+/**
+ * Plugin state object
+ */
+export interface PluginState {
+  dashcamUrls: Map<string, { url: string; platform: string }>;
+  suiteTestRuns: Map<string, any>;
+  testDriverOptions: TestDriverOptions;
+}
+
+/**
+ * Current plugin state
+ */
+export const pluginState: PluginState;
+
+/**
+ * Register a Dashcam URL for a test
+ */
+export function registerDashcamUrl(testId: string, url: string, platform: string): void;
+
+/**
+ * Get Dashcam URL for a test
+ */
+export function getDashcamUrl(testId: string): { url: string; platform: string } | undefined;
+
+/**
+ * Clear all Dashcam URLs
+ */
+export function clearDashcamUrls(): void;
+
+/**
+ * Get suite test run data
+ */
+export function getSuiteTestRun(suiteId: string): any;
+
+/**
+ * Set suite test run data
+ */
+export function setSuiteTestRun(suiteId: string, runData: any): void;
+
+/**
+ * Clear suite test run data
+ */
+export function clearSuiteTestRun(suiteId: string): void;
+
+/**
+ * Get the current plugin state
+ */
+export function getPluginState(): PluginState;
+
+/**
+ * Authenticate with API key
+ */
+export function authenticateWithApiKey(apiKey: string, apiRoot?: string): Promise<string>;
+
+/**
+ * Create a test run directly via API
+ */
+export function createTestRunDirect(token: string, apiRoot: string, testRunData: any): Promise<any>;
+
+/**
+ * Record a test case directly via API
+ */
+export function recordTestCaseDirect(token: string, apiRoot: string, testCaseData: any): Promise<any>;
+
+/**
+ * Create a TestDriver instance
+ */
+export function createTestDriver(options?: TestDriverOptions): Promise<TestDriverSDK>;
+
+/**
+ * Register a test with TestDriver
+ */
+export function registerTest(testdriver: TestDriverSDK, context: any): void;
+
+/**
+ * Cleanup a TestDriver instance
+ */
+export function cleanupTestDriver(testdriver: TestDriverSDK): Promise<void>;
+
+/**
+ * Plugin options
+ */
+export interface TestDriverPluginOptions extends TestDriverOptions {
+  /**
+   * API key (defaults to TD_API_KEY env var)
+   */
+  apiKey?: string;
+}
+
+/**
+ * TestDriver Vitest Plugin
+ * @param options - Plugin configuration options
+ */
+export default function testDriverPlugin(options?: TestDriverPluginOptions): any;

package/interfaces/vitest-plugin.mjs

@@ -2,8 +2,8 @@ import { execSync } from "child_process";
 import crypto from "crypto";
 import { createRequire } from "module";
 import path from "path";
+import { postOrUpdateTestResults } from "../lib/github-comment.mjs";
 import { setTestRunInfo } from "./shared-test-state.mjs";
-import { generateGitHubComment, postOrUpdateTestResults } from "../lib/github-comment.mjs";
 
 // Use createRequire to import CommonJS modules without esbuild processing
 const require = createRequire(import.meta.url);

package/jsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "ES2022",
+    "checkJs": true,
+    "strict": false,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "baseUrl": ".",
+    "typeRoots": ["."]
+  },
+  "include": [
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.d.ts",
+    "sdk.d.ts",
+    "lib/**/*.d.ts",
+    "interfaces/**/*.d.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "build"
+  ]
+}

package/lib/github-comment.mjs

@@ -47,10 +47,17 @@ function generateTestResultsTable(testCases, testRunUrl) {
     return '_No test cases recorded_';
   }
 
+  // Filter out skipped tests
+  const nonSkippedTests = testCases.filter(test => test.status !== 'skipped');
+  
+  if (nonSkippedTests.length === 0) {
+    return '_No test cases to display (all tests were skipped)_';
+  }
+
   let table = '| Status | Test | File | Duration | Replay |\n';
   table += '|--------|------|------|----------|--------|\n';
 
-  for (const test of testCases) {
+  for (const test of nonSkippedTests) {
     const status = getStatusEmoji(test.status);
     const name = test.testName || 'Unknown';
     const file = test.testFile || 'unknown';
@@ -65,8 +72,8 @@ function generateTestResultsTable(testCases, testRunUrl) {
       const replayId = extractReplayId(test.replayUrl);
       if (replayId) {
         const gifUrl = getReplayGifUrl(test.replayUrl, replayId);
-        // Embed GIF with link using HTML for width control
-        replay = `<a href="${linkUrl}"><img src="${gifUrl}" width="250" alt="${name}" /></a>`;
+        // Embed GIF with link using HTML for height control
+        replay = `<a href="${linkUrl}"><img src="${gifUrl}" height="100" alt="Test replay" /></a>`;
       } else {
         // Fallback to text link if no GIF available
         replay = `[🎥 View](${linkUrl})`;
@@ -258,9 +265,15 @@ export function generateGitHubComment(testRunData, testCases = []) {
   comment += ` • **Duration:** ${formatDuration(duration)}`;
   comment += ` • ${passedTests} passed`;
   if (failedTests > 0) comment += `, ${failedTests} failed`;
-  if (skippedTests > 0) comment += `, ${skippedTests} skipped`;
+  // Only show skipped count if there are no passed or failed tests
+  if (skippedTests > 0 && passedTests === 0 && failedTests === 0) {
+    comment += `, ${skippedTests} skipped`;
+  }
   comment += `\n\n`;
   
+  // Exceptions section (only if there are failures) - show first
+  comment += generateExceptionsSection(testCases, testRunUrl);
+  
   // Test results table (now includes embedded GIFs)
   comment += '## 📝 Test Results\n\n';
   comment += generateTestResultsTable(testCases, testRunUrl);
@@ -270,9 +283,6 @@ export function generateGitHubComment(testRunData, testCases = []) {
     comment += `\n[📋 View Full Test Run](${testRunUrl})\n`;
   }
   
-  // Exceptions section (only if there are failures)
-  comment += generateExceptionsSection(testCases, testRunUrl);
-  
   // Footer
   comment += '\n---\n';
   comment += `<sub>Generated by [TestDriver](https://testdriver.ai) • Run ID: \`${runId}\`</sub>\n`;

package/lib/vitest/hooks.d.ts

@@ -3,7 +3,7 @@
  * @module testdriverai/vitest/hooks
  */
 
-import { Dashcam, DashcamOptions, TestDriver, TestDriverOptions } from '../core/index';
+import TestDriverSDK, { TestDriverOptions } from '../../sdk';
 
 /**
  * Vitest test context (from test function parameter)
@@ -21,99 +21,49 @@ export interface VitestContext {
 }
 
 /**
- * Options for useTestDriver hook
+ * Options for TestDriver hook
  */
-export interface UseTestDriverOptions extends TestDriverOptions {
+export interface TestDriverHookOptions extends TestDriverOptions {
   /**
-   * Automatically connect to sandbox (default: true)
+   * Force creation of a new sandbox (default: true)
    */
-  autoConnect?: boolean;
+  newSandbox?: boolean;
   
   /**
-   * Create new sandbox (default: true)
+   * Reconnect to the last used sandbox
    */
-  new?: boolean;
-}
-
-/**
- * Options for useDashcam hook
- */
-export interface UseDashcamOptions extends DashcamOptions {
-  /**
-   * Automatically authenticate (default: true)
-   */
-  autoAuth?: boolean;
+  reconnect?: boolean;
   
   /**
-   * Automatically start recording (default: false)
+   * Direct IP address to connect to a running sandbox instance
    */
-  autoStart?: boolean;
-  
-  /**
-   * Automatically stop recording at test end (default: false)
-   */
-  autoStop?: boolean;
+  ip?: string;
 }
 
 /**
- * Use TestDriver client in a test
- * Creates and manages TestDriver instance for the current test
+ * Create a TestDriver client for use in Vitest tests
+ * Manages lifecycle automatically (connects on first use, disconnects after test)
  * 
  * @param context - Vitest test context (from async (context) => {})
  * @param options - TestDriver options
- * @returns TestDriver client instance
+ * @returns TestDriver SDK instance
  * 
  * @example
- * test('my test', async (context) => {
- *   const client = useTestDriver(context, { os: 'linux' });
- *   await client.find('Login button').click();
- * });
- */
-export function useTestDriver(context: VitestContext, options?: UseTestDriverOptions): TestDriver;
-
-/**
- * Use Dashcam in a test
- * Creates and manages Dashcam instance for the current test
- * 
- * @param context - Vitest test context
- * @param client - TestDriver client instance (from useTestDriver)
- * @param options - Dashcam options
- * @returns Dashcam instance
+ * import { describe, expect, it } from "vitest";
+ * import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
  * 
- * @example
- * test('my test', async (context) => {
- *   const client = useTestDriver(context);
- *   const dashcam = useDashcam(context, client, {
- *     autoStart: true,
- *     autoStop: true
- *   });
- *   
- *   await client.find('button').click();
- * });
- */
-export function useDashcam(context: VitestContext, client: TestDriver, options?: UseDashcamOptions): Dashcam;
-
-/**
- * Use TestDriver with Dashcam in one call
- * Combined hook for the simplest usage pattern
- * 
- * @param context - Vitest test context
- * @param options - Combined options for TestDriver and Dashcam
- * @returns Object with client and dashcam instances
- * 
- * @example
- * test('my test', async (context) => {
- *   const { client, dashcam } = useTestDriverWithDashcam(context, {
- *     os: 'linux'
+ * describe("My Test Suite", () => {
+ *   it("should do something", async (context) => {
+ *     const testdriver = TestDriver(context, { newSandbox: true, headless: false });
+ *     
+ *     await testdriver.provision.chrome({ url: 'https://example.com' });
+ *     
+ *     const button = await testdriver.find("Sign In button");
+ *     await button.click();
+ *     
+ *     const result = await testdriver.assert("the dashboard is visible");
+ *     expect(result).toBeTruthy();
  *   });
- *   
- *   await client.find('button').click();
  * });
  */
-export function useTestDriverWithDashcam(
-  context: VitestContext,
-  options?: UseTestDriverOptions & UseDashcamOptions
-): {
-  client: TestDriver;
-  dashcam: Dashcam;
-};
+export function TestDriver(context: VitestContext, options?: TestDriverHookOptions): TestDriverSDK;

package/package.json

@@ -1,15 +1,31 @@
 {
   "name": "testdriverai",
-  "version": "7.2.37",
+  "version": "7.2.39",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
+  "types": "sdk.d.ts",
   "exports": {
-    ".": "./sdk.js",
-    "./core": "./lib/core/index.js",
-    "./vitest": "./interfaces/vitest-plugin.mjs",
-    "./vitest/plugin": "./interfaces/vitest-plugin.mjs",
+    ".": {
+      "types": "./sdk.d.ts",
+      "default": "./sdk.js"
+    },
+    "./core": {
+      "types": "./lib/core/index.d.ts",
+      "default": "./lib/core/index.js"
+    },
+    "./vitest": {
+      "types": "./interfaces/vitest-plugin.d.ts",
+      "default": "./interfaces/vitest-plugin.mjs"
+    },
+    "./vitest/plugin": {
+      "types": "./interfaces/vitest-plugin.d.ts",
+      "default": "./interfaces/vitest-plugin.mjs"
+    },
     "./vitest/setup": "./lib/vitest/setup.mjs",
-    "./vitest/hooks": "./lib/vitest/hooks.mjs",
+    "./vitest/hooks": {
+      "types": "./lib/vitest/hooks.d.ts",
+      "default": "./lib/vitest/hooks.mjs"
+    },
     "./presets": "./lib/presets/index.mjs"
   },
   "bin": {
@@ -47,12 +63,12 @@
   "license": "ISC",
   "dependencies": {
     "@npmcli/redact": "^3.2.2",
-    "@octokit/rest": "^20.1.1",
     "@oclif/core": "^4.5.0",
     "@oclif/plugin-commands": "^4.1.28",
     "@oclif/plugin-help": "^6.2.30",
     "@oclif/plugin-not-found": "^3.2.59",
     "@oclif/plugin-warn-if-update-available": "^3.1.43",
+    "@octokit/rest": "^20.1.1",
     "@sentry/node": "^9.47.1",
     "@stoplight/yaml-ast-parser": "^0.0.50",
     "ajv": "^8.17.1",
@@ -107,7 +123,6 @@
     "mocha": "^10.8.2",
     "node-addon-api": "^8.0.0",
     "prettier": "3.3.3",
-    "testdriverai": "^7.2.3",
     "vitest": "^4.0.16"
   },
   "optionalDependencies": {

package/sdk.d.ts

@@ -683,9 +683,139 @@ export class Element {
   readonly label: string | null;
 }
 
+// ====================================
+// Provision API Interfaces
+// ====================================
+
+/** Options for provision.chrome */
+export interface ProvisionChromeOptions {
+  /** URL to navigate to (default: 'http://testdriver-sandbox.vercel.app/') */
+  url?: string;
+  /** Start maximized (default: true) */
+  maximized?: boolean;
+  /** Use guest mode (default: false) */
+  guest?: boolean;
+}
+
+/** Options for provision.chromeExtension */
+export interface ProvisionChromeExtensionOptions {
+  /** Local filesystem path to the unpacked extension directory */
+  extensionPath?: string;
+  /** Chrome Web Store extension ID */
+  extensionId?: string;
+  /** Start maximized (default: true) */
+  maximized?: boolean;
+}
+
+/** Options for provision.vscode */
+export interface ProvisionVSCodeOptions {
+  /** Path to workspace or folder to open */
+  workspace?: string;
+  /** Array of extension IDs to install */
+  extensions?: string[];
+}
+
+/** Options for provision.installer */
+export interface ProvisionInstallerOptions {
+  /** URL to download the installer from */
+  url: string;
+  /** Filename to save as (auto-detected from URL if not provided) */
+  filename?: string;
+  /** Application name to focus after install */
+  appName?: string;
+  /** Whether to launch the app after installation (default: true) */
+  launch?: boolean;
+}
+
+/** Options for provision.electron */
+export interface ProvisionElectronOptions {
+  /** Path to Electron app (required) */
+  appPath: string;
+  /** Additional electron args */
+  args?: string[];
+}
+
+/** Provision API for launching applications */
+export interface ProvisionAPI {
+  /**
+   * Launch Chrome browser
+   * @param options - Chrome launch options
+   */
+  chrome(options?: ProvisionChromeOptions): Promise<void>;
+
+  /**
+   * Launch Chrome browser with a custom extension loaded
+   * @param options - Chrome extension launch options
+   */
+  chromeExtension(options?: ProvisionChromeExtensionOptions): Promise<void>;
+
+  /**
+   * Launch VS Code
+   * @param options - VS Code launch options
+   */
+  vscode(options?: ProvisionVSCodeOptions): Promise<void>;
+
+  /**
+   * Download and install an application
+   * @param options - Installer options
+   * @returns Path to the downloaded file
+   */
+  installer(options: ProvisionInstallerOptions): Promise<string>;
+
+  /**
+   * Launch Electron app
+   * @param options - Electron launch options
+   */
+  electron(options: ProvisionElectronOptions): Promise<void>;
+}
+
+/** Dashcam API for screen recording */
+export interface DashcamAPI {
+  /**
+   * Start recording
+   */
+  start(): Promise<void>;
+
+  /**
+   * Stop recording and get replay URL
+   */
+  stop(): Promise<string | null>;
+
+  /**
+   * Check if currently recording
+   */
+  isRecording(): boolean;
+}
+
 export default class TestDriverSDK {
   constructor(apiKey: string, options?: TestDriverOptions);
 
+  /**
+   * Whether the SDK is currently connected to a sandbox
+   */
+  readonly connected: boolean;
+
+  /**
+   * The operating system of the sandbox
+   */
+  readonly os: 'windows' | 'linux';
+
+  /**
+   * Provision API for launching applications
+   */
+  readonly provision: ProvisionAPI;
+
+  /**
+   * Dashcam API for screen recording
+   */
+  readonly dashcam: DashcamAPI;
+
+  /**
+   * Wait for the sandbox to be ready
+   * Called automatically by provision methods
+   */
+  ready(): Promise<void>;
+
   /**
    * Authenticate with TestDriver API
    */

package/setup/aws/cloudformation.yaml

@@ -168,8 +168,8 @@ Resources:
             IpProtocol: tcp,
             FromPort: 8765,
             ToPort: 8765,
-            CidrIp: 0.0.0.0/0,
-            Description: "pyautogui-cli WebSockets - Open for testing",
+            CidrIp: !Ref AllowedIngressCidr,
+            Description: "pyautogui-cli WebSockets"
           }
         - {
             IpProtocol: tcp,

package/test/testdriver/hover-text.test.mjs

@@ -8,7 +8,7 @@ import { TestDriver } from "../../lib/vitest/hooks.mjs";
 
 describe("Hover Text Test", () => {
   it("should click Sign In and verify error message", async (context) => {
-    const testdriver = TestDriver(context, { headless: false, newSandbox: true, cacheKey: 'hover-text-test' });
+    const testdriver = TestDriver(context, { headless: false, ip: '3.138.116.105'});
     await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
 
     // Click on Sign In button using new find() API

package/.github/workflows/test-with-comments.yml

@@ -1,73 +0,0 @@
-name: TestDriver Tests with GitHub Comments
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-  push:
-    branches: [main]
-  workflow_dispatch: # Allows manual trigger from Actions tab
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    
-    permissions:
-      contents: read
-      pull-requests: write  # Required to post comments on PRs
-    
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-      
-      - name: Install dependencies
-        run: npm ci
-      
-      - name: Run assert test with GitHub comments
-        env:
-          # TestDriver API key (from repository secrets)
-          TD_API_KEY: ${{ secrets.TD_API_KEY }}
-          
-          # GitHub token for posting comments (auto-provided)
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          
-          # PR number for PR comments (auto-extracted for pull_request events)
-          GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
-          
-          # Git information (automatically provided by GitHub Actions)
-          # GITHUB_SHA, GITHUB_REF, GITHUB_REPOSITORY are already set
-          
-        run: |
-          echo "🚀 Running TestDriver assert test..."
-          echo "📍 Repository: $GITHUB_REPOSITORY"
-          echo "🔢 PR Number: ${{ github.event.pull_request.number || 'N/A (not a PR)' }}"
-          echo "📦 Running test..."
-          npm run test:sdk -- test/testdriver/assert.test.mjs
-        
-      - name: Upload test results (on failure)
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: test-results
-          path: |
-            test-report.junit.xml
-            .testdriver/
-          retention-days: 7
-      
-      - name: Comment on PR (manual fallback if auto-comment fails)
-        if: failure() && github.event_name == 'pull_request'
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const testRunUrl = process.env.TESTDRIVER_RUN_URL || 'Check workflow logs';
-            github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: `⚠️ TestDriver tests encountered an error. ${testRunUrl}`
-            })