testdriverai 7.3.1 → 7.3.3

package/.prettierignore

@@ -0,0 +1,4 @@
+agent/lib/subimage/opencv.js
+node_modules
+schema.json
+docs

package/.prettierrc

@@ -0,0 +1 @@
+{}

package/CHANGELOG.md

@@ -0,0 +1,158 @@
+## [7.3.3](https://github.com/testdriverai/testdriverai/compare/v7.3.2...v7.3.3) (2026-02-06)
+
+
+
+## [7.3.2](https://github.com/testdriverai/testdriverai/compare/v7.3.1...v7.3.2) (2026-02-05)
+
+
+
+## [7.3.1](https://github.com/testdriverai/testdriverai/compare/v7.2.92...v7.3.1) (2026-02-05)
+
+
+
+## [7.2.92](https://github.com/testdriverai/testdriverai/compare/v7.2.91...v7.2.92) (2026-02-04)
+
+
+
+## [7.2.91](https://github.com/testdriverai/testdriverai/compare/v7.2.90...v7.2.91) (2026-02-04)
+
+
+
+## [7.2.90](https://github.com/testdriverai/testdriverai/compare/v7.2.89...v7.2.90) (2026-02-04)
+
+
+
+## [7.2.89](https://github.com/testdriverai/testdriverai/compare/v7.2.88...v7.2.89) (2026-02-04)
+
+
+
+## [7.2.88](https://github.com/testdriverai/testdriverai/compare/v7.2.87...v7.2.88) (2026-02-04)
+
+
+
+## [7.2.87](https://github.com/testdriverai/testdriverai/compare/v7.2.86...v7.2.87) (2026-02-04)
+
+
+
+## [7.2.86](https://github.com/testdriverai/testdriverai/compare/v7.2.85...v7.2.86) (2026-02-04)
+
+
+
+## [7.2.85](https://github.com/testdriverai/testdriverai/compare/v7.2.84...v7.2.85) (2026-02-04)
+
+
+
+## [7.2.84](https://github.com/testdriverai/testdriverai/compare/v7.2.82...v7.2.84) (2026-02-04)
+
+
+
+## [7.2.83](https://github.com/testdriverai/testdriverai/compare/v7.2.82...v7.2.83) (2026-02-04)
+
+
+
+## [7.2.82](https://github.com/testdriverai/testdriverai/compare/v7.2.81...v7.2.82) (2026-02-04)
+
+
+
+## [7.2.81](https://github.com/testdriverai/testdriverai/compare/v7.2.80...v7.2.81) (2026-02-04)
+
+
+
+## [7.2.80](https://github.com/testdriverai/testdriverai/compare/v7.2.79...v7.2.80) (2026-02-04)
+
+
+
+## [7.2.79](https://github.com/testdriverai/testdriverai/compare/v7.2.78...v7.2.79) (2026-02-03)
+
+
+
+## [7.2.78](https://github.com/testdriverai/testdriverai/compare/v7.2.77...v7.2.78) (2026-02-03)
+
+
+
+## [7.2.77](https://github.com/testdriverai/testdriverai/compare/v7.2.76...v7.2.77) (2026-02-02)
+
+
+
+## [7.2.76](https://github.com/testdriverai/testdriverai/compare/v7.2.75...v7.2.76) (2026-02-02)
+
+
+
+## [7.2.75](https://github.com/testdriverai/testdriverai/compare/v7.2.74...v7.2.75) (2026-02-02)
+
+
+
+## [7.2.74](https://github.com/testdriverai/testdriverai/compare/v7.2.73...v7.2.74) (2026-02-02)
+
+
+
+## [7.2.73](https://github.com/testdriverai/testdriverai/compare/v7.2.72...v7.2.73) (2026-02-02)
+
+
+
+## [7.2.72](https://github.com/testdriverai/testdriverai/compare/v7.2.71...v7.2.72) (2026-02-02)
+
+
+
+## [7.2.71](https://github.com/testdriverai/testdriverai/compare/v7.2.70...v7.2.71) (2026-02-02)
+
+
+
+## [7.2.70](https://github.com/testdriverai/testdriverai/compare/v7.2.69...v7.2.70) (2026-02-02)
+
+
+
+## [7.2.69](https://github.com/testdriverai/testdriverai/compare/v7.2.68...v7.2.69) (2026-02-02)
+
+
+
+## [7.2.68](https://github.com/testdriverai/testdriverai/compare/v7.2.67...v7.2.68) (2026-02-02)
+
+
+
+## [7.2.67](https://github.com/testdriverai/testdriverai/compare/v7.2.66...v7.2.67) (2026-02-02)
+
+
+
+## [7.2.66](https://github.com/testdriverai/testdriverai/compare/v7.2.65...v7.2.66) (2026-02-02)
+
+
+
+## [7.2.65](https://github.com/testdriverai/testdriverai/compare/v7.2.64...v7.2.65) (2026-02-02)
+
+
+
+## [7.2.64](https://github.com/testdriverai/testdriverai/compare/v7.2.63...v7.2.64) (2026-02-02)
+
+
+
+## [7.2.63](https://github.com/testdriverai/testdriverai/compare/v7.2.62...v7.2.63) (2026-01-30)
+
+
+
+## [7.2.62](https://github.com/testdriverai/testdriverai/compare/v7.2.61...v7.2.62) (2026-01-30)
+
+
+
+## [7.2.61](https://github.com/testdriverai/testdriverai/compare/v7.2.60...v7.2.61) (2026-01-30)
+
+
+
+## [7.2.60](https://github.com/testdriverai/testdriverai/compare/v7.2.59...v7.2.60) (2026-01-27)
+
+
+
+## [7.2.59](https://github.com/testdriverai/testdriverai/compare/v7.2.58...v7.2.59) (2026-01-27)
+
+
+
+## [7.2.58](https://github.com/testdriverai/testdriverai/compare/v6.1.8...v7.2.58) (2026-01-27)
+
+
+### Reverts
+
+* Revert "list dashcam version g" ([5037571](https://github.com/testdriverai/testdriverai/commit/5037571440c33f8966104874c542c6c57a809510))
+* Revert "update discord invite" ([b5a9b99](https://github.com/testdriverai/testdriverai/commit/b5a9b9955cf2b0b07fd0ebeb6abf65f89cd3d5a8))
+
+
+

package/SKILLs.md

@@ -0,0 +1,17 @@
+# TestDriver Skills for Claude Code
+
+This file is intended to be used as `SKILLs.md` for Claude Code and other MCP-compatible agents.
+
+For the complete, always-up-to-date guide to working with TestDriver, **see `agents.md` in this repository**. It contains:
+
+- How to initialize and use the `TestDriver` SDK
+- Recommended two-file workflow (`setup.test.mjs` + `experiment.test.mjs`)
+- Patterns for finding elements, asserting, typing, scrolling, screenshots, and more
+
+In short:
+
+- Use `agents.md` as your **primary reference** for how to write and iterate on tests.
+- Use the HTTP MCP server exposed by your API (e.g. `POST /api/v1/mcp`) to **query test results, runs, and analytics** from Claude Code.
+
+> Tip: When building tools or workflows for TestDriver inside Claude Code, prefer **explicit steps** (find/click/type/assert) guided by `agents.md`, and use the MCP tools only to **inspect test history and failures**, not to drive the sandbox itself.
+

package/agent/index.js

@@ -2046,12 +2046,13 @@ ${regression}
       // Use the debugger URL instead of the VNC URL
       const urlToOpen = `${this.debuggerUrl}?data=${encodedData}`;
 
-      // Check preview mode from config
-      const previewMode = this.config.TD_PREVIEW || "browser";
+      // Check preview mode from CLI options (SDK passes it directly)
+      const previewMode = (this.cliArgs.options && this.cliArgs.options.preview) || this.config.TD_PREVIEW || "browser";
+      console.log("[DEBUG renderSandbox] preview:", previewMode);
 
       if (previewMode === "ide") {
         // Send session to VS Code extension via HTTP
-        this.sendIdeSessionNotification(urlToOpen, data);
+        this.writeIdeSessionFile(urlToOpen, data);
       } else if (previewMode !== "none") {
         // Open in browser (default behavior)
         this.emitter.emit(events.showWindow, urlToOpen);
@@ -2060,6 +2061,34 @@ ${regression}
     }
   }
 
+  // Write session file for IDE preview (VSCode extension watches for these)
+  writeIdeSessionFile(debuggerUrl, data) {
+    const fs = require("fs");
+    const path = require("path");
+
+    const sessionId = `${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+    const previewsDir = path.join(process.cwd(), ".testdriver", ".previews");
+
+    // Create the previews directory if it doesn't exist
+    if (!fs.existsSync(previewsDir)) {
+      fs.mkdirSync(previewsDir, { recursive: true });
+    }
+
+    const sessionData = {
+      sessionId,
+      debuggerUrl,
+      resolution: Array.isArray(data.resolution) ? data.resolution : (data.resolution ? data.resolution.split("x").map(Number) : [1920, 1080]),
+      testFile: data.testFile || this.testFile || null,
+      os: data.os || this.sandboxOs || "linux",
+      timestamp: Date.now(),
+    };
+
+    const filePath = path.join(previewsDir, `${sessionId}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(sessionData, null, 2));
+
+    logger.log(`IDE preview session written to ${filePath}`);
+  }
+
   // Find the VS Code instance that contains the test file
   findTargetIdeInstance(testFilePath) {
     const fs = require("fs");

package/ai/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "testdriver",
+  "description": "TestDriver plugin: SDK guidance plus MCP access to test runs and results.",
+  "version": "1.0.0",
+  "author": {
+    "name": "TestDriver"
+  }
+}
+

package/docs/GITHUB_COMMENTS.md

@@ -0,0 +1,330 @@
+# GitHub Comment Integration
+
+TestDriver can automatically post beautiful, formatted comments to your GitHub pull requests and commits with test results, including dashcam replays, exceptions, and detailed statistics.
+
+## Features
+
+- 📊 **Test Results Summary** - Pass/fail statistics and duration
+- 🎥 **Dashcam GIF Replays** - Embedded GIF previews with links to full replays
+- ❌ **Exception Details** - Error messages and stack traces for failed tests
+- 📋 **Detailed Test Table** - Status, file, duration, and replay link for each test
+- 🔄 **Auto-update** - Updates existing comment instead of creating duplicates
+- 🎨 **Beautiful Formatting** - Professional markdown with emojis and badges
+
+## Setup
+
+### 1. Enable in CI Environment
+
+Set the required environment variables in your CI workflow:
+
+#### GitHub Actions
+
+```yaml
+name: TestDriver Tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      
+      - name: Install dependencies
+        run: npm install
+      
+      - name: Run TestDriver tests
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: npm run test:sdk
+```
+
+**Important:** For pull request events, `GITHUB_PR_NUMBER` must be explicitly set from `github.event.pull_request.number`.
+
+### 2. Environment Variables
+
+| Variable | Description | Required | Example |
+|----------|-------------|----------|---------|
+| `TD_API_KEY` | TestDriver API key | ✅ Yes | Get from [console.testdriver.ai](https://console.testdriver.ai/team) |
+| `GITHUB_TOKEN` | GitHub token with PR write permissions | ✅ Yes | Automatically available in GitHub Actions |
+| `GITHUB_PR_NUMBER` | Pull request number | For PR comments | `123` |
+| `GITHUB_SHA` | Commit SHA | For commit comments | Automatically set in GitHub Actions |
+
+**Token Alternatives:**
+- `GITHUB_TOKEN` (preferred)
+- `GH_TOKEN` (alternative)
+
+### 3. Comment Destinations
+
+TestDriver will post comments based on available context:
+
+- **Pull Request Comment** - If `GITHUB_PR_NUMBER` is set (recommended)
+- **Commit Comment** - If only `GITHUB_SHA` is available (fallback)
+
+## Example Comment
+
+Here's what a TestDriver GitHub comment looks like:
+
+---
+
+# 🟢 TestDriver Test Results
+
+**Status:** ✅ PASSED  
+**Duration:** 2m 34s  
+**Platform:** linux  
+**Branch:** `feature/new-test`  
+**Commit:** `a1b2c3d`
+
+## 📊 Test Summary
+
+```
+Total:   5
+Passed:  4 ✅
+Failed:  1 ❌
+Skipped: 0 ⏭️
+```
+
+### [📋 View Full Test Run](https://console.testdriver.ai/runs/123)
+
+## 📝 Test Results
+
+| Status | Test | File | Duration | Replay |
+|--------|------|------|----------|--------|
+| ✅ | should login successfully | `tests/auth.test.mjs` | 12.5s | [🎥 View](https://console.testdriver.ai/replay/abc123) |
+| ✅ | should add item to cart | `tests/cart.test.mjs` | 8.2s | [🎥 View](https://console.testdriver.ai/replay/def456) |
+| ❌ | should complete checkout | `tests/checkout.test.mjs` | 15.3s | [🎥 View](https://console.testdriver.ai/replay/ghi789) |
+
+## 🎥 Dashcam Replays
+
+### should login successfully
+
+[![should login successfully](https://console.testdriver.ai/api/replay/abc123/gif)](https://console.testdriver.ai/replay/abc123)
+
+[🎬 View Full Replay](https://console.testdriver.ai/replay/abc123)
+
+## 🔴 Failures
+
+### should complete checkout
+
+**File:** `tests/checkout.test.mjs`
+
+**📹 [Watch Replay](https://console.testdriver.ai/replay/ghi789)**
+
+```
+AssertionError: expected false to be truthy
+```
+
+<details>
+<summary>Stack Trace</summary>
+
+```
+AssertionError: expected false to be truthy
+    at /workspace/tests/checkout.test.mjs:45:7
+    ...
+```
+</details>
+
+---
+<sub>Generated by [TestDriver](https://testdriver.ai) • Run ID: `1234567890-abc123`</sub>
+
+---
+
+## Configuration
+
+### Customizing Comment Behavior
+
+You can control GitHub comment posting with environment variables:
+
+```bash
+# Disable GitHub comments entirely
+TESTDRIVER_SKIP_GITHUB_COMMENT=true npm run test
+
+# Use custom GitHub token
+GH_TOKEN=ghp_yourtoken npm run test
+```
+
+### GitLab / Other CI Systems
+
+While the integration is optimized for GitHub, you can use the comment generator programmatically:
+
+```javascript
+import { generateGitHubComment } from 'testdriverai/lib/github-comment.mjs';
+
+const testRunData = {
+  runId: '1234567890-abc',
+  status: 'passed',
+  totalTests: 5,
+  passedTests: 4,
+  failedTests: 1,
+  skippedTests: 0,
+  duration: 154000,
+  testRunUrl: 'https://console.testdriver.ai/runs/123',
+  platform: 'linux',
+  branch: 'main',
+  commit: 'a1b2c3d',
+};
+
+const testCases = [
+  {
+    testName: 'should work',
+    testFile: 'test.test.mjs',
+    status: 'passed',
+    duration: 5000,
+    replayUrl: 'https://console.testdriver.ai/replay/abc',
+  },
+  // ... more tests
+];
+
+const markdown = generateGitHubComment(testRunData, testCases);
+console.log(markdown);
+```
+
+## Troubleshooting
+
+### Comment not posting
+
+1. **Check environment variables:**
+   ```bash
+   echo $GITHUB_TOKEN
+   echo $GITHUB_PR_NUMBER
+   ```
+
+2. **Check CI logs:**
+   Look for log messages:
+   - `"GitHub token not found, skipping comment posting"`
+   - `"Repository info not available"`
+   - `"Posted GitHub comment"`
+
+3. **Verify token permissions:**
+   - GitHub Actions: `GITHUB_TOKEN` should have `write` permissions for `pull-requests` or `contents`
+   - Personal tokens: Needs `repo` scope
+
+### Comment not updating
+
+If you see duplicate comments instead of updates:
+- Ensure the bot/user posting comments is consistent across runs
+- The update mechanism looks for existing comments with "Generated by [TestDriver]" signature
+
+### Replays not showing
+
+If dashcam replays aren't included:
+- Verify dashcam is starting correctly (check for `🎥 Dashcam URL:` in logs)
+- Ensure tests are calling `await testdriver.provision.*()` which auto-starts dashcam
+- Check that dashcam stops successfully (look for replay URLs in output)
+
+### GIF embeds not loading
+
+The GIF embeds are generated dynamically by the TestDriver API:
+- URL format: `https://console.testdriver.ai/api/replay/{replayId}/gif`
+- If GIFs don't load, the API endpoint may be unavailable
+- Fallback: Users can still click the "View Full Replay" link
+
+## API Reference
+
+### `generateGitHubComment(testRunData, testCases)`
+
+Generates markdown for a GitHub comment.
+
+**Parameters:**
+- `testRunData` (Object): Test run summary data
+  - `runId` (string): Unique test run ID
+  - `status` (string): Overall status ('passed', 'failed', 'cancelled')
+  - `totalTests` (number): Total number of tests
+  - `passedTests` (number): Number of passed tests
+  - `failedTests` (number): Number of failed tests
+  - `skippedTests` (number): Number of skipped tests
+  - `duration` (number): Total duration in milliseconds
+  - `testRunUrl` (string): URL to full test run
+  - `platform` (string): Test platform ('linux', 'windows', 'mac')
+  - `branch` (string): Git branch name
+  - `commit` (string): Git commit SHA
+- `testCases` (Array): Array of test case objects
+  - `testName` (string): Test name
+  - `testFile` (string): Test file path
+  - `status` (string): Test status
+  - `duration` (number): Test duration in ms
+  - `replayUrl` (string): Dashcam replay URL (optional)
+  - `errorMessage` (string): Error message if failed (optional)
+  - `errorStack` (string): Stack trace if failed (optional)
+
+**Returns:** String (markdown)
+
+### `postOrUpdateTestResults(testRunData, testCases, githubOptions)`
+
+Posts or updates a GitHub comment with test results.
+
+**Parameters:**
+- `testRunData` (Object): Same as `generateGitHubComment`
+- `testCases` (Array): Same as `generateGitHubComment`
+- `githubOptions` (Object): GitHub API configuration
+  - `token` (string): GitHub token
+  - `owner` (string): Repository owner
+  - `repo` (string): Repository name
+  - `prNumber` (number): PR number (optional)
+  - `commitSha` (string): Commit SHA (optional)
+
+**Returns:** `Promise<Object>` - GitHub API response
+
+## Examples
+
+### Manual Comment Posting
+
+```javascript
+import { postOrUpdateTestResults } from 'testdriverai/lib/github-comment.mjs';
+
+await postOrUpdateTestResults(
+  {
+    runId: '123',
+    status: 'passed',
+    totalTests: 10,
+    passedTests: 10,
+    failedTests: 0,
+    skippedTests: 0,
+    duration: 60000,
+    testRunUrl: 'https://console.testdriver.ai/runs/123',
+    platform: 'linux',
+    branch: 'main',
+    commit: 'abc123',
+  },
+  testCases,
+  {
+    token: process.env.GITHUB_TOKEN,
+    owner: 'myorg',
+    repo: 'myrepo',
+    prNumber: 456,
+  }
+);
+```
+
+### Custom Formatting
+
+```javascript
+import { generateGitHubComment } from 'testdriverai/lib/github-comment.mjs';
+
+const markdown = generateGitHubComment(testRunData, testCases);
+
+// Customize markdown
+const customMarkdown = markdown.replace(
+  '# 🟢 TestDriver Test Results',
+  '# 🟢 My Custom Test Report'
+);
+
+// Post using GitHub API directly
+// ... your posting logic
+```
+
+## Support
+
+- **Documentation:** [testdriver.ai/docs](https://testdriver.ai/docs)
+- **Issues:** [github.com/testdriverai/testdriverai/issues](https://github.com/testdriverai/testdriverai/issues)
+- **Discord:** Join our [community Discord](https://discord.gg/testdriver)