testdriverai 6.2.2 → 7.0.0

package/mcp-server/AI_GUIDELINES.md

@@ -0,0 +1,57 @@
+# TestDriver MCP Server - AI Agent Guidelines
+
+## Essential Workflow
+
+1. **Always connect first**: Call `testdriver_connect` before any other operations
+2. **Verify with screenshots**: Screenshots are automatically captured after actions - review them to confirm success
+3. **Wait before interacting**: Use `waitForText` or `waitForImage` before clicking/typing to ensure elements are ready
+4. **Assert expectations**: After critical actions, use `assert` to verify the expected outcome
+5. **Share debugger URL**: After connecting, share the debugger URL with users so they can watch in real-time
+
+## Common Patterns
+
+### Login Flow
+
+```
+1. connect() - start sandbox
+2. getScreenshot() - see initial state
+3. hoverText("Username") - click username field
+4. type("user@example.com") - enter username
+5. hoverText("Password") - click password field
+6. type("password123") - enter password
+7. hoverText("Login") - click login button
+8. waitForText("Welcome") - wait for success
+9. assert("the user is logged in") - verify outcome
+10. getScreenshot() - capture final state
+```
+
+### Form Testing
+
+```
+1. Always wait for form elements before interacting
+2. Take screenshots before and after form submission
+3. Assert success/error messages appear
+4. Use remember() to capture dynamic values (order IDs, timestamps, etc.)
+```
+
+## Best Practices
+
+- **Be patient**: Always wait for elements before clicking
+- **Be specific**: Use descriptive text in hoverText/assert (e.g., "the blue Submit button" not just "Submit")
+- **Verify everything**: Check screenshots to ensure actions succeeded
+- **Handle errors**: If an action fails, take a screenshot to diagnose
+- **Save tests**: Use `createTestFromActions` to save successful workflows
+
+## Common Mistakes to Avoid
+
+❌ Don't click elements that may not have loaded yet
+✅ Do use `waitForText` first
+
+❌ Don't assume actions succeeded without verification
+✅ Do check screenshots and use assertions
+
+❌ Don't chain many actions without pauses
+✅ Do add small waits between rapid actions
+
+❌ Don't forget to share the debugger URL
+✅ Do tell users where to watch the live VM screen

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "testdriverai",
-  "version": "6.2.2",
+  "version": "7.0.0",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
-  "main": "index.js",
+  "main": "sdk.js",
   "bin": {
     "testdriverai": "bin/testdriverai.js"
   },
@@ -10,12 +10,22 @@
     "start": "node bin/testdriverai.js",
     "dev": "DEV=true node bin/testdriverai.js",
     "debug": "DEV=true VERBOSE=true node bin/testdriverai.js",
-    "docs": "node docs/_scripts/link-replacer.js && cd docs && npx mint@latest dev",
+    "docs": "cd docs && npx mint@latest dev",
     "docs:dev": "cd docs && npx mint dev",
-    "docs:build": "node docs/_scripts/link-replacer.js && cd docs && npx mint@latest build",
+    "docs:build": "cd docs && npx mint@latest build",
     "docs:links": "node docs/_scripts/link-replacer.js",
     "bundle": "node build.mjs",
     "test": "mocha test/*",
+    "test:sdk": "vitest run",
+    "test:sdk:windows": "TEST_PLATFORM=windows vitest run",
+    "test:sdk:mac": "TEST_PLATFORM=mac vitest run",
+    "test:sdk:linux": "TEST_PLATFORM=linux vitest run",
+    "test:sdk:watch": "vitest",
+    "test:sdk:ui": "vitest --ui",
+    "test:sdk:coverage": "vitest run --coverage",
+    "test:sdk:single": "vitest run --reporter=verbose",
+    "test:sdk:report": "open test-results/index.html",
+    "test:sdk:results": "node scripts/view-test-results.mjs",
     "docs-lint": "cd docs && vale **/*.mdx",
     "docs-upload": "node upload-docs-to-openai.js",
     "runall": "dotenv testdriverai run --config testdriver.config.yaml --path './testdriver/*.testdriver.yaml'",
@@ -54,6 +64,7 @@
     "remark-parse": "^11.0.0",
     "sanitize-filename": "^1.6.3",
     "strip-ansi": "^6.0.1",
+    "terminal-image": "^4.1.0",
     "tmp": "^0.2.3",
     "winston": "^3.13.0",
     "winston-transport": "^4.9.0",
@@ -65,6 +76,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.10.0",
+    "@vitest/ui": "^4.0.8",
     "chai": "^5.1.2",
     "esbuild": "0.20.2",
     "esbuild-plugin-fileloc": "^0.0.6",
@@ -75,7 +87,8 @@
     "mint": "^4.2.67",
     "mocha": "^10.8.2",
     "node-addon-api": "^8.0.0",
-    "prettier": "3.3.3"
+    "prettier": "3.3.3",
+    "vitest": "^4.0.8"
   },
   "optionalDependencies": {
     "@esbuild/linux-x64": "^0.21.5"

package/schema.json

@@ -301,13 +301,6 @@
           },
           "amount": {
             "type": "integer"
-          },
-          "method": {
-            "type": "string",
-            "enum": [
-              "keyboard",
-              "mouse"
-            ]
           }
         }
       },
@@ -353,8 +346,8 @@
               "right-click",
               "double-click",
               "hover",
-              "drag-start",
-              "drag-end"
+              "mouseDown",
+              "mouseUp"
             ]
           }
         }
@@ -405,8 +398,8 @@
               "right-click",
               "double-click",
               "hover",
-              "drag-start",
-              "drag-end"
+              "mouseDown",
+              "mouseUp"
             ]
           },
           "method": {
@@ -443,8 +436,8 @@
               "right-click",
               "double-click",
               "hover",
-              "drag-start",
-              "drag-end"
+              "mouseDown",
+              "mouseUp"
             ]
           }
         }
@@ -471,8 +464,8 @@
               "right-click",
               "double-click",
               "hover",
-              "drag-start",
-              "drag-end"
+              "mouseDown",
+              "mouseUp"
             ]
           },
           "invert": {
@@ -558,13 +551,6 @@
           "distance": {
             "type": "integer"
           },
-          "method": {
-            "type": "string",
-            "enum": [
-              "keyboard",
-              "mouse"
-            ]
-          },
           "invert": {
             "type": "boolean"
           }
@@ -598,13 +584,6 @@
           },
           "distance": {
             "type": "integer"
-          }, 
-          "method" : {
-            "type": "string",
-            "enum": [
-              "keyboard",
-              "mouse"
-            ]
           },
           "invert": {
             "type": "boolean"

package/scripts/view-test-results.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+/**
+ * TestDriver SDK Test Results Viewer
+ * Displays a formatted summary of test results from the JSON output
+ */
+
+import fs from "fs";
+import path from "path";
+
+const RESULTS_PATH = "test-results/results.json";
+
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+function displayResults() {
+  if (!fs.existsSync(RESULTS_PATH)) {
+    console.error("❌ No test results found. Run tests first:");
+    console.error("   npm run test:sdk");
+    process.exit(1);
+  }
+
+  const results = JSON.parse(fs.readFileSync(RESULTS_PATH, "utf8"));
+
+  const total = results.numTotalTests || 0;
+  const passed = results.numPassedTests || 0;
+  const failed = results.numFailedTests || 0;
+  const skipped = results.numPendingTests || 0;
+  const duration = results.testResults?.reduce(
+    (sum, file) => sum + (file.endTime - file.startTime),
+    0,
+  );
+
+  console.log("\n🧪 TestDriver SDK Test Results");
+  console.log("═".repeat(50));
+  console.log(`✅ Passed:   ${passed}/${total}`);
+  console.log(`❌ Failed:   ${failed}/${total}`);
+  console.log(`⏭️  Skipped:  ${skipped}/${total}`);
+  console.log(`⏱️  Duration: ${formatDuration(duration)}`);
+  console.log("═".repeat(50));
+
+  if (failed > 0) {
+    console.log("\n❌ Failed Tests:\n");
+    results.testResults?.forEach((file) => {
+      const failedTests =
+        file.assertionResults?.filter((test) => test.status === "failed") || [];
+
+      if (failedTests.length > 0) {
+        console.log(`📁 ${path.relative(process.cwd(), file.name)}`);
+        failedTests.forEach((test) => {
+          console.log(`   ❌ ${test.title}`);
+          console.log(`      Duration: ${formatDuration(test.duration)}`);
+          if (test.failureMessages?.length > 0) {
+            console.log("\n      Error:");
+            test.failureMessages.forEach((msg) => {
+              // Truncate very long error messages
+              const truncated =
+                msg.length > 500 ? msg.substring(0, 500) + "..." : msg;
+              console.log(
+                "      " + truncated.split("\n").join("\n      ") + "\n",
+              );
+            });
+          }
+        });
+        console.log();
+      }
+    });
+  }
+
+  if (passed > 0) {
+    console.log("✅ Passed Tests:\n");
+    results.testResults?.forEach((file) => {
+      const passedTests =
+        file.assertionResults?.filter((test) => test.status === "passed") || [];
+
+      if (passedTests.length > 0) {
+        console.log(`📁 ${path.relative(process.cwd(), file.name)}`);
+        passedTests.forEach((test) => {
+          console.log(`   ✅ ${test.title} (${formatDuration(test.duration)})`);
+        });
+        console.log();
+      }
+    });
+  }
+
+  console.log("\n📊 View detailed HTML report:");
+  console.log("   npm run test:sdk:report");
+  console.log("   or open: test-results/index.html\n");
+
+  // Exit with error code if tests failed
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+displayResults();