testdriverai 7.2.39 → 7.2.41

package/agent/lib/sandbox.js

@@ -1,5 +1,4 @@
 const WebSocket = require("ws");
-const marky = require("marky");
 const crypto = require("crypto");
 const { events } = require("../events");
 
@@ -83,10 +82,6 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
           }
         }
 
-        // Start timing for this message
-        const timingKey = `sandbox-${message.type}`;
-        marky.mark(timingKey);
-
         let p = new Promise((resolve, reject) => {
           this.socket.send(JSON.stringify(message));
           emitter.emit(events.sandbox.sent, message);
@@ -99,13 +94,6 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
         // Set up timeout to prevent hanging requests
         const timeoutId = setTimeout(() => {
           if (this.ps[requestId]) {
-            const pendingMessage = this.ps[requestId];
-            // Stop the timing marker to prevent memory leak
-            try {
-              marky.stop(pendingMessage.timingKey);
-            } catch (e) {
-              // Ignore timing errors
-            }
             delete this.ps[requestId];
             rejectPromise(new Error(`Sandbox message '${message.type}' timed out after ${timeout}ms`));
           }
@@ -122,7 +110,6 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
             rejectPromise(error);
           },
           message,
-          timingKey,
           startTime: Date.now(),
         };
 
@@ -252,25 +239,6 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
             this.ps[message.requestId].reject(error);
           } else {
             emitter.emit(events.sandbox.received);
-
-            // Get timing information for this message
-            const pendingMessage = this.ps[message.requestId];
-            if (pendingMessage) {
-              const timing = marky.stop(pendingMessage.timingKey);
-
-              // Track timing for each message type
-              await analytics.track("sandbox", {
-                operation: pendingMessage.message.type,
-                timing,
-                requestId: message.requestId,
-                timestamp: Date.now(),
-                data: {
-                  messageType: pendingMessage.message.type,
-                  ...pendingMessage.message,
-                },
-              });
-            }
-
             this.ps[message.requestId]?.resolve(message);
           }
           delete this.ps[message.requestId];

package/agents.md

@@ -241,6 +241,8 @@ describe("Experiment", () => {
 });
 ```
 
+> ⚠️ **NEVER REMOVE `reconnect: true`**: If a test file already has `reconnect: true`, do NOT remove it. This option is intentional and removing it will break the two-file workflow. Only remove `reconnect: true` when explicitly combining files into a final standalone test.
+
 ### Step 4: Iterate in Experiment File
 
 - Run experiment, see output, fix issues
@@ -260,13 +262,15 @@ vitest run tests/experiment.test.mjs
 
 ### After Experimentation: Combine and Rename
 
-**IMPORTANT:** Once the test is working, combine both files into a single, properly-named test file:
+**IMPORTANT:** Once the test is working AND the user explicitly asks to combine/finalize the test, combine both files into a single, properly-named test file:
 
 1. **Merge the code** - Copy the working steps from `experiment.test.mjs` into `setup.test.mjs`
-2. **Remove reconnect options** - Delete `reconnect: true` since the final test runs standalone
+2. **Remove reconnect options** - Delete `reconnect: true` since the final test runs standalone (ONLY do this when creating the final combined test - never remove it from an existing experiment file!)
 3. **Rename the file** - Give it a meaningful name like `login-flow.test.mjs` or `checkout-process.test.mjs`
 4. **Delete the experiment file** - Clean up `experiment.test.mjs`
 
+> ⚠️ **WARNING FOR AI AGENTS**: Do NOT remove `reconnect: true` from any existing test file unless you are explicitly combining files into a final test. If a test has `reconnect: true`, it is there intentionally.
+
 ```javascript
 // Final combined test: login-flow.test.mjs
 import { describe, expect, it } from "vitest";

package/docs/v7/_drafts/best-practices.mdx

@@ -20,7 +20,7 @@ describe('Login Flow', () => {
       os: 'linux'
     });
     await client.auth();
-    await client.connect({ newSandbox: true });
+    await client.connect();
     testdriver = client;
   });
   

package/docs/v7/_drafts/configuration.mdx

@@ -49,7 +49,6 @@ const client = await TestDriver.create({
   // Sandbox Configuration
   os: 'linux',
   resolution: '1920x1080',
-  newSandbox: true,
   sandboxId: null,
   
   // API Configuration
@@ -137,7 +136,6 @@ const { testdriver, dashcam } = await chrome(context, {
   resolution: '1920x1080',
   
   // Chrome-specific options
-  headless: false,
   incognito: false,
 });
 ```

package/docs/v7/_drafts/core.mdx

@@ -389,7 +389,6 @@ import { TestDriver, Dashcam, TestDriverOptions, DashcamOptions } from 'testdriv
 const options: TestDriverOptions = {
   os: 'linux',
   resolution: '1366x768',
-  newSandbox: true,
   analytics: true
 };
 

package/docs/v7/_drafts/migration.mdx

@@ -61,7 +61,7 @@ describe('Login Test', () => {
       os: 'windows'
     });
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect();
   });
 
   afterAll(async () => {
@@ -489,7 +489,7 @@ describe('Login Flow', () => {
     });
     
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect();
     
     // Prerun
     await testdriver.exec('pwsh', 'dashcam start', 5000, true);

package/docs/v7/_drafts/provision.mdx

@@ -10,7 +10,7 @@ import { TestDriver } from 'testdriverai/lib/vitest/hooks.mjs';
 
 describe('My Test Suite', () => {
   it('should test Chrome browser', async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
     
     await testdriver.provision.chrome({
       url: 'https://example.com'
@@ -53,7 +53,7 @@ await testdriver.provision.chrome({
 
 ```javascript
 it('should login to my app', async (context) => {
-  const testdriver = TestDriver(context, { newSandbox: true });
+  const testdriver = TestDriver(context, ());
   
   await testdriver.provision.chrome({
     url: 'https://myapp.com/login'
@@ -91,7 +91,7 @@ await testdriver.provision.vscode({
 
 ```javascript
 it('should launch VS Code', async (context) => {
-  const testdriver = TestDriver(context, { newSandbox: true });
+  const testdriver = TestDriver(context, ());
   
   await testdriver.provision.vscode();
   
@@ -106,7 +106,7 @@ it('should launch VS Code', async (context) => {
 
 ```javascript
 it('should install and use a VS Code extension', async (context) => {
-  const testdriver = TestDriver(context, { newSandbox: true });
+  const testdriver = TestDriver(context, ());
   
   // Launch VS Code with extensions installed
   await testdriver.provision.vscode({
@@ -164,7 +164,7 @@ const filePath = await testdriver.provision.installer({
 
 ```javascript
 it('should install a .deb package', async (context) => {
-  const testdriver = TestDriver(context, { newSandbox: true });
+  const testdriver = TestDriver(context, ());
   
   const filePath = await testdriver.provision.installer({
     url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb'
@@ -179,7 +179,7 @@ it('should install a .deb package', async (context) => {
 
 ```javascript
 it('should download a script', async (context) => {
-  const testdriver = TestDriver(context, { newSandbox: true });
+  const testdriver = TestDriver(context, ());
   
   const filePath = await testdriver.provision.installer({
     url: 'https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh',
@@ -195,7 +195,7 @@ it('should download a script', async (context) => {
 
 ```javascript
 it('should run AppImage with custom flags', async (context) => {
-  const testdriver = TestDriver(context, { newSandbox: true });
+  const testdriver = TestDriver(context, ());
   
   const filePath = await testdriver.provision.installer({
     url: 'https://example.com/app.AppImage',
@@ -235,7 +235,7 @@ await testdriver.provision.electron({
 
 ```javascript
 it('should launch Electron app', async (context) => {
-  const testdriver = TestDriver(context, { newSandbox: true });
+  const testdriver = TestDriver(context, ());
   
   await testdriver.provision.electron({
     appPath: '/path/to/my-electron-app',
@@ -271,7 +271,7 @@ import { TestDriver } from 'testdriverai/lib/vitest/hooks.mjs';
 
 describe('Application Testing', () => {
   it('should test Chrome login flow', async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
     
     await testdriver.provision.chrome({
       url: 'https://myapp.com/login'
@@ -286,7 +286,7 @@ describe('Application Testing', () => {
   });
 
   it('should test VS Code extension', async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
     
     await testdriver.provision.vscode({
       extensions: ['ms-python.python']
@@ -301,7 +301,7 @@ describe('Application Testing', () => {
   });
 
   it('should install and test CLI tool', async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
     
     await testdriver.provision.installer({
       url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb'
@@ -315,7 +315,7 @@ describe('Application Testing', () => {
 
 ## Best Practices
 
-1. **Use `newSandbox: true`** - Each test gets a clean environment
+1. **Use clean environments** - Each test gets a fresh sandbox by default
 2. **Enable Dashcam** - Great for debugging test failures (enabled by default)
 3. **Check assertions** - Always verify the expected state after actions
 4. **Use appropriate provision method** - Match the method to your test target

package/docs/v7/_drafts/screenshot.mdx

@@ -113,7 +113,7 @@ const screenshot = await testdriver.screenshot(1, false, true);
 
 ```javascript
 it('should complete checkout', async (context) => {
-  const testdriver = TestDriver(context, { newSandbox: true });
+  const testdriver = TestDriver(context, ());
   await testdriver.provision.chrome({ url: 'https://shop.example.com' });
 
   try {

package/docs/v7/_drafts/troubleshooting.mdx

@@ -84,7 +84,7 @@ const client = await TestDriver.create({
 let attempts = 0;
 while (attempts < 3) {
   try {
-    await client.connect({ newSandbox: true });
+    await client.connect();
     break;
   } catch (error) {
     attempts++;

package/docs/v7/ai.mdx

@@ -167,7 +167,7 @@ describe('E-commerce Flow with AI', () => {
   beforeAll(async () => {
     client = new TestDriver(process.env.TD_API_KEY);
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect(());
   });
 
   afterAll(async () => {

package/docs/v7/assert.mdx

@@ -214,7 +214,7 @@ describe('Assertions', () => {
   beforeAll(async () => {
     client = new TestDriver(process.env.TD_API_KEY);
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect(());
   });
 
   afterAll(async () => {

package/docs/v7/ci-cd.mdx

@@ -579,8 +579,6 @@ describe("Cross-platform tests", () => {
     const os = process.env.TD_OS || 'linux';
     
     const testdriver = TestDriver(context, { 
-      newSandbox: true, 
-      headless: false,
       os: os  // 'linux' or 'windows'
     });
     

package/docs/v7/click.mdx

@@ -235,7 +235,7 @@ describe('Click Interactions', () => {
   beforeAll(async () => {
     client = new TestDriver(process.env.TD_API_KEY);
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect(());
   });
 
   afterAll(async () => {

package/docs/v7/client.mdx

@@ -133,7 +133,7 @@ await testdriver.connect(options)
 
 **Basic connection:**
 ```javascript
-await testdriver.connect({ newSandbox: true });
+await testdriver.connect(());
 ```
 
 **Reconnect to existing sandbox:**
@@ -273,7 +273,7 @@ describe('My Test Suite', () => {
     
     // Authenticate and connect
     await testdriver.auth();
-    const instance = await testdriver.connect({ newSandbox: true });
+    const instance = await testdriver.connect(());
     
     console.log('Connected to sandbox:', instance.instanceId);
   });
@@ -300,7 +300,7 @@ describe('My Test Suite', () => {
     
     ```javascript
     try {
-      await testdriver.connect({ newSandbox: true });
+      await testdriver.connect(());
     } catch (error) {
       console.error('Failed to connect:', error.message);
       throw error;

package/docs/v7/customizing-devices.mdx

@@ -10,32 +10,10 @@ Configure TestDriver behavior with options passed to the `TestDriver()` function
 
 ```javascript
 const testdriver = TestDriver(context, {
-  headless: false,
   reconnect: false,
 });
 ```
 
-### Headless Mode
-
-Run tests without a visible browser window. Useful for CI/CD pipeline or spawning multiple tests locally:
-
-```javascript
-const testdriver = TestDriver(context, {
-  headless: true,  // No visible browser window
-});
-```
-
-### IP Target
-
-If self-hosting TestDriver, use `ip` to specify the device IP. See [Self-Hosting TestDriver](../self-hosting.md) for details.
-
-```javascript
-const testdriver = TestDriver(context, {
-  newSandbox: true,
-  ip: "203.0.113.42",  // Your allowlisted IP
-});
-```
-
 ### Operating System
 
 Set the `os` property to run tests on a specific operating system. Available options are `linux` (default) and `windows`.
@@ -77,6 +55,26 @@ steps:
   - run: TD_OS=${{ matrix.os }} npx vitest run
 ```
 
+### Headless Mode
+
+Run tests without a visible browser window. Useful for CI/CD pipeline or spawning multiple tests locally:
+
+```javascript
+const testdriver = TestDriver(context, {
+  headless: true,  // No visible browser window
+});
+```
+
+### IP Target
+
+If self-hosting TestDriver, use `ip` to specify the device IP. See [Self-Hosting TestDriver](../self-hosting.md) for details.
+
+```javascript
+const testdriver = TestDriver(context, {
+  ip: "203.0.113.42",  // Your allowlisted IP
+});
+```
+
 ## Keepalive
 
 By default, sandboxes terminate immediately when the test finishes. Set this value to keep the sandbox alive for reconnection.
@@ -97,8 +95,6 @@ Split your test into two files: one for known-good steps that set up the desired
 
 ```javascript known-good.test.mjs
 const testdriver = TestDriver(context, {
-  newSandbox: true,
-  headless: false,
   keepAlive: 60000,  // Keep sandbox alive for 60 seconds after test
 });
 ```
@@ -106,8 +102,6 @@ const testdriver = TestDriver(context, {
 ```javascript work-in-progress.test.mjs
 // Second test file: experiment.test.mjs (run within keepAlive window)
 const testdriver = TestDriver(context, {
-  newSandbox: true,
-  headless: false,
   reconnect: true,  // Reconnect to existing sandbox
 });
 ```

package/docs/v7/device-config.mdx

@@ -32,7 +32,7 @@ import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
 
 describe("Login Flow", () => {
   it("should log in successfully", async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
     
     await testdriver.provision.chrome({
       url: 'https://myapp.com/login',
@@ -117,7 +117,7 @@ import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
 
 describe("Chrome Extension Test", () => {
   it("should load and interact with extension", async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
 
     // Clone extension from GitHub
     await testdriver.ready();
@@ -192,7 +192,7 @@ import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
 
 describe("Desktop App Test", () => {
   it("should install and launch app", async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
 
     // Download and install
     const installerPath = await testdriver.provision.installer({
@@ -215,7 +215,6 @@ import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
 describe("Windows App Test", () => {
   it("should install on Windows", async (context) => {
     const testdriver = TestDriver(context, { 
-      newSandbox: true,
       os: 'windows'
     });
 
@@ -282,7 +281,7 @@ import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
 
 describe("VS Code Test", () => {
   it("should open workspace with extensions", async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
 
     // Create a test project
     await testdriver.ready();

package/docs/v7/exec.mdx

@@ -282,7 +282,7 @@ describe('Code Execution', () => {
   beforeAll(async () => {
     client = new TestDriver(process.env.TD_API_KEY);
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect(());
   });
 
   afterAll(async () => {

package/docs/v7/find.mdx

@@ -299,7 +299,7 @@ describe('Element Finding', () => {
   beforeAll(async () => {
     client = new TestDriver(process.env.TD_API_KEY);
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect(());
   });
 
   afterAll(async () => {

package/docs/v7/focus-application.mdx

@@ -209,7 +209,7 @@ describe('Multi-Application Workflow', () => {
   beforeAll(async () => {
     client = new TestDriver(process.env.TD_API_KEY);
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect(());
   });
 
   afterAll(async () => {

package/docs/v7/hover.mdx

@@ -204,7 +204,7 @@ describe('Hover Interactions', () => {
   beforeAll(async () => {
     client = new TestDriver(process.env.TD_API_KEY);
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect(());
   });
 
   afterAll(async () => {

package/docs/v7/press-keys.mdx

@@ -286,7 +286,7 @@ describe('Keyboard Navigation', () => {
   beforeAll(async () => {
     client = new TestDriver(process.env.TD_API_KEY);
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect(());
   });
 
   afterAll(async () => {

package/docs/v7/reusable-code.mdx

@@ -45,7 +45,7 @@ import { login } from './helpers/auth.js';
 
 describe("Checkout", () => {
   it("should complete checkout as logged in user", async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
     
     await testdriver.provision.chrome({
       url: 'https://shop.example.com',
@@ -116,7 +116,7 @@ import { LoginPage } from './pages/LoginPage.js';
 
 describe("Authentication", () => {
   it("should show error for invalid credentials", async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
     
     await testdriver.provision.chrome({
       url: 'https://app.example.com/login',
@@ -131,7 +131,7 @@ describe("Authentication", () => {
   });
 
   it("should redirect to dashboard on success", async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
     
     await testdriver.provision.chrome({
       url: 'https://app.example.com/login',
@@ -186,7 +186,7 @@ import { testUsers, testUrls, setupAuthenticatedSession } from './fixtures/index
 
 describe("Admin Panel", () => {
   it("should access admin settings", async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context, ());
     
     await testdriver.provision.chrome({
       url: `${testUrls.staging}/login`,

package/docs/v7/scroll.mdx

@@ -242,7 +242,7 @@ describe('Scrolling', () => {
   beforeAll(async () => {
     client = new TestDriver(process.env.TD_API_KEY);
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect(());
   });
 
   afterAll(async () => {

package/docs/v7/type.mdx

@@ -296,7 +296,7 @@ describe('Form Filling with Type', () => {
   beforeAll(async () => {
     client = new TestDriver(process.env.TD_API_KEY);
     await testdriver.auth();
-    await testdriver.connect({ newSandbox: true });
+    await testdriver.connect(());
   });
 
   afterAll(async () => {

package/lib/core/Dashcam.js

@@ -117,36 +117,11 @@ class Dashcam {
     const shell = this._getShell();
     const apiRoot = this._getApiRoot();
 
-    let install = await this.client.exec(
-      shell,
-      'npm ls dashcam -g || echo "not installed"',
-      40000,
-      true
-    );
-    this._log('debug', 'Dashcam install check:', install);
-
     if (this.client.os === 'windows') {
 
       const dashcamPath = await this._getDashcamPath();
       this._log('debug', 'Dashcam executable path:', dashcamPath);
       
-      const installedVersion = await this.client.exec(
-        shell,
-        'npm ls dashcam -g',
-        40000,
-        true
-      );
-      this._log('debug', 'Installed dashcam version:', installedVersion);
-      
-      // Test version command
-      const versionTest = await this.client.exec(
-        shell,
-        `& "${dashcamPath}" version`,
-        40000,
-        true
-      );
-      this._log('debug', 'Dashcam version test:', versionTest);
-      
       // Authenticate with TD_API_ROOT
       const authOutput = await this.client.exec(
         shell,
@@ -292,18 +267,6 @@ class Dashcam {
 
     if (this.client.os === 'windows') {
       
-      const dashcamPath = await this._getDashcamPath();
-      this._log('debug', 'Dashcam path:', dashcamPath);
-      
-      // Verify dashcam exists
-      const dashcamExists = await this.client.exec(
-        shell,
-        `Test-Path "${dashcamPath}"`,
-        10000,
-        true
-      );
-      this._log('debug', 'Dashcam.cmd exists:', dashcamExists);
-      
       // Start dashcam record and redirect output with TD_API_ROOT
       const outputFile = 'C:\\Users\\testdriver\\.dashcam-cli\\dashcam-start.log';
       //  const titleArg = this.title ? ` --title=\`"${this.title.replace(/"/g, '`"')}\`"` : '';

package/lib/vitest/hooks.d.ts

@@ -3,7 +3,8 @@
  * @module testdriverai/vitest/hooks
  */
 
-import TestDriverSDK, { TestDriverOptions } from '../../sdk';
+import type TestDriverSDK from '../../sdk';
+import type { TestDriverOptions } from '../../sdk';
 
 /**
  * Vitest test context (from test function parameter)
@@ -21,23 +22,10 @@ export interface VitestContext {
 }
 
 /**
- * Options for TestDriver hook
+ * Options for TestDriver hook (includes all TestDriverOptions)
  */
 export interface TestDriverHookOptions extends TestDriverOptions {
-  /**
-   * Force creation of a new sandbox (default: true)
-   */
-  newSandbox?: boolean;
-  
-  /**
-   * Reconnect to the last used sandbox
-   */
-  reconnect?: boolean;
-  
-  /**
-   * Direct IP address to connect to a running sandbox instance
-   */
-  ip?: string;
+  // All TestDriverOptions are already included via extends
 }
 
 /**

package/lib/vitest/hooks.mjs

@@ -169,14 +169,9 @@ const lifecycleHandlers = new WeakMap();
 /**
  * Create a TestDriver client in a Vitest test with automatic lifecycle management
  * 
- * @param {object} context - Vitest test context (from async (context) => {})
- * @param {object} options - TestDriver options (passed directly to TestDriver constructor)
- * @param {string} [options.apiKey] - TestDriver API key (defaults to process.env.TD_API_KEY)
- * @param {boolean} [options.headless] - Run sandbox in headless mode
- * @param {boolean} [options.newSandbox] - Create new sandbox
- * @param {number} [options.timeout=0] - Sandbox timeout (TTL) in milliseconds. 0 = use provider default (5 min for E2B Linux)
- * @param {boolean} [options.autoConnect=true] - Automatically connect to sandbox
- * @returns {TestDriver} TestDriver client instance
+ * @param {import('vitest').TestContext} context - Vitest test context (from async (context) => {})
+ * @param {import('../../sdk.js').TestDriverOptions} [options] - TestDriver options (passed directly to TestDriver constructor)
+ * @returns {import('../../sdk.js').default} TestDriver client instance
  * 
  * @example
  * test('my test', async (context) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.2.39",
+  "version": "7.2.41",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",

package/sdk.d.ts

@@ -13,7 +13,7 @@ export type ClickAction =
 export type ScrollDirection = "up" | "down" | "left" | "right";
 export type ScrollMethod = "keyboard" | "mouse";
 export type TextMatchMethod = "ai" | "turbo";
-export type ExecLanguage = "js" | "pwsh";
+export type ExecLanguage = "js" | "pwsh" | "sh";
 export type KeyboardKey =
   | "\t"
   | "\n"
@@ -242,7 +242,7 @@ export interface TestDriverOptions {
   sandboxInstance?: string;
   /** Cache key for element finding operations. If provided, enables caching tied to this key */
   cacheKey?: string;
-  /** Reconnect to the last used sandbox (throws error if no last sandbox exists) */
+  /** Reconnect to the last used sandbox instead of creating a new one. When true, provision methods (chrome, vscode, installer, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists. */
   reconnect?: boolean;
   /** Redraw configuration for screen change detection */
   redraw?: boolean | {
@@ -266,7 +266,7 @@ export interface ConnectOptions {
   sandboxId?: string;
   /** Force creation of a new sandbox */
   newSandbox?: boolean;
-  /** Reconnect to the last used sandbox (throws error if no last sandbox exists) */
+  /** Reconnect to the last used sandbox instead of creating a new one. When true, provision methods (chrome, vscode, installer, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists. */
   reconnect?: boolean;
   /** Direct IP address to connect to a running sandbox instance */
   ip?: string;

package/sdk.js

@@ -1362,10 +1362,29 @@ class TestDriverSDK {
 
   /**
    * Create the provision API with methods for launching applications
+   * Automatically skips provisioning when reconnect mode is enabled
    * @private
    */
+  /**
+   * Get the path to the dashcam-chrome extension
+   * Uses preinstalled dashcam-chrome on both Linux and Windows
+   * @returns {Promise<string>} Path to dashcam-chrome/build directory
+   * @private
+   */
+  async _getDashcamChromeExtensionPath() {
+    if (this.os !== 'windows') {
+      return '/usr/lib/node_modules/dashcam-chrome/build';
+    }
+
+    // dashcam-chrome is preinstalled on Windows at C:\Program Files\nodejs\node_modules\dashcam-chrome\build
+    // Use the actual long path - we'll handle quoting in the chrome launch
+    return 'C:\\PROGRA~1\\nodejs\\node_modules\\dashcam-chrome\\build';
+  }
+
   _createProvisionAPI() {
-    return {
+    const self = this;
+    
+    const provisionMethods = {
       /**
        * Launch Chrome browser
        * @param {Object} options - Chrome launch options
@@ -1473,9 +1492,10 @@ class TestDriverSDK {
         if (guest) chromeArgs.push('--guest');
         chromeArgs.push('--disable-fre', '--no-default-browser-check', '--no-first-run', '--no-experiments', '--disable-infobars', `--user-data-dir=${userDataDir}`);
         
-        // Add dashcam-chrome extension on Linux
-        if (this.os === 'linux') {
-          chromeArgs.push('--load-extension=/usr/lib/node_modules/dashcam-chrome/build');
+        // Add dashcam-chrome extension
+        const dashcamChromePath = await this._getDashcamChromeExtensionPath();
+        if (dashcamChromePath) {
+          chromeArgs.push(`--load-extension=${dashcamChromePath}`);
         }
 
         // Launch Chrome
@@ -1484,7 +1504,7 @@ class TestDriverSDK {
           const argsString = chromeArgs.map(arg => `"${arg}"`).join(', ');
           await this.exec(
             shell,
-            `Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList ${argsString}, "${url}"`,
+            `Start-Process "C:\\ChromeForTesting\\chrome-win64\\chrome.exe" -ArgumentList ${argsString}, "${url}"`,
             30000
           );
         } else {
@@ -1743,11 +1763,12 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         chromeArgs.push('--disable-fre', '--no-default-browser-check', '--no-first-run', '--no-experiments', '--disable-infobars', '--disable-features=ChromeLabs', `--user-data-dir=${userDataDir}`);
         
         // Add user extension and dashcam-chrome extension
-        if (this.os === 'linux') {
+        const dashcamChromePath = await this._getDashcamChromeExtensionPath();
+        if (dashcamChromePath) {
           // Load both user extension and dashcam-chrome for web log capture
-          chromeArgs.push(`--load-extension=${extensionPath},/usr/lib/node_modules/dashcam-chrome/build`);
-        } else if (this.os === 'windows') {
-          // On Windows, just load the user extension (dashcam-chrome not available)
+          chromeArgs.push(`--load-extension=${extensionPath},${dashcamChromePath}`);
+        } else {
+          // If dashcam-chrome unavailable, just load user extension
           chromeArgs.push(`--load-extension=${extensionPath}`);
         }
 
@@ -1756,7 +1777,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           const argsString = chromeArgs.map(arg => `"${arg}"`).join(', ');
           await this.exec(
             shell,
-            `Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList ${argsString}`,
+            `Start-Process "C:\\ChromeForTesting\\chrome-win64\\chrome.exe" -ArgumentList ${argsString}`,
             30000
           );
         } else {
@@ -2073,6 +2094,24 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         await this.focusApplication('Electron');
       },
     };
+
+    // Wrap all provision methods with reconnect check using Proxy
+    return new Proxy(provisionMethods, {
+      get(target, prop) {
+        const method = target[prop];
+        if (typeof method === 'function') {
+          return async (...args) => {
+            // Skip provisioning if reconnecting to existing sandbox
+            if (self.reconnect) {
+              console.log(`[provision.${prop}] Skipping provisioning (reconnect mode)`);
+              return;
+            }
+            return method(...args);
+          };
+        }
+        return method;
+      }
+    });
   }
 
   /**

package/test/testdriver/ai.test.mjs

@@ -8,7 +8,7 @@ import { TestDriver } from "../../lib/vitest/hooks.mjs";
 
 describe("AI Test", () => {
   it("should use ai to search for testdriver on Google", async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true });
+    const testdriver = TestDriver(context);
     
     // provision.chrome() automatically calls ready() and starts dashcam
     await testdriver.provision.chrome({

package/test/testdriver/assert.test.mjs

@@ -8,7 +8,7 @@ import { TestDriver } from "../../lib/vitest/hooks.mjs";
 
 describe("Assert Test", () => {
   it("should assert the testdriver login page shows", async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: true, headless: false });
+    const testdriver = TestDriver(context, {ip: process.env.TD_IP});
     
     // provision.chrome() automatically calls ready() and starts dashcam
     await testdriver.provision.chrome({
@@ -23,7 +23,7 @@ describe("Assert Test", () => {
     expect(result).toBeTruthy();
   });
   // it("should assert the testdriver login page shows 2", async (context) => {
-  //   const testdriver = TestDriver(context, { newSandbox: true });
+  //   const testdriver = TestDriver(context);
     
   //   // provision.chrome() automatically calls ready() and starts dashcam
   //   await testdriver.provision.chrome({

package/test/testdriver/chrome-extension.test.mjs

@@ -10,39 +10,52 @@
 import { describe, expect, it } from "vitest";
 import { TestDriver } from "../../lib/vitest/hooks.mjs";
 
-const isLinux = (process.env.TD_OS || "linux") === "linux";
+describe("Chrome Extension Test", () => {
+  it("should load hello-world Chrome extension from local path", async (context) => {
 
+    console.log('connecting to', process.env.TD_IP)
 
-describe("Chrome Extension Test", () => {
-    it.skipIf(!isLinux)("should load hello-world Chrome extension from local path", async (context) => {
-    const testdriver = TestDriver(context, { headless: false, newSandbox: true });
+    const testdriver = TestDriver(context, { ip: process.env.TD_IP });
     
     // Wait for connection to be ready before running exec
     await testdriver.ready();
     
+    // Determine OS-specific paths and commands
+    const shell = testdriver.os === 'windows' ? 'pwsh' : 'sh';
+    const extensionsDir = testdriver.os === 'windows' 
+      ? 'C:\\Users\\testdriver\\Downloads\\chrome-extensions-samples'
+      : '/tmp/chrome-extensions-samples';
+    const extensionPath = testdriver.os === 'windows'
+      ? `${extensionsDir}\\functional-samples\\tutorial.hello-world`
+      : `${extensionsDir}/functional-samples/tutorial.hello-world`;
+    
     // Clone the Chrome extensions samples repo
-    await testdriver.exec(
-      'sh',
-      'git clone --depth 1 https://github.com/GoogleChrome/chrome-extensions-samples.git /tmp/chrome-extensions-samples',
-      60000,
-      true
-    );
+    const cloneCmd = testdriver.os === 'windows'
+      ? `git clone --depth 1 https://github.com/GoogleChrome/chrome-extensions-samples.git "${extensionsDir}"`
+      : `git clone --depth 1 https://github.com/GoogleChrome/chrome-extensions-samples.git ${extensionsDir}`;
+    
+    await testdriver.exec(shell, cloneCmd, 60000, true);
 
     // Launch Chrome with the hello-world extension loaded
     await testdriver.provision.chromeExtension({
-      extensionPath: '/tmp/chrome-extensions-samples/functional-samples/tutorial.hello-world',
-      url: 'https://testdriver.ai'
+      extensionPath: extensionPath
     });
 
+    // Navigate to testdriver.ai (extensions don't load on New Tab)
+    const addressBar = await testdriver.find("Chrome address bar");
+    await addressBar.click();
+    await testdriver.type("testdriver.ai");
+    await testdriver.pressKeys(["enter"]);
+
+    // Wait for page to load
+    const pageResult = await testdriver.assert("I can see testdriver.ai");
+    expect(pageResult).toBeTruthy();
+
     // The hello-world extension adds a puzzle piece icon to the toolbar
     // When clicked, it shows a popup with "Hello Extensions"
-    
-    // First, let's verify Chrome loaded and we can see the page
-    const pageResult = await testdriver.assert("chrome is running");
-    expect(pageResult).toBeTruthy();
 
     // Click on the extensions button (puzzle piece icon) in Chrome toolbar
-    const extensionsButton = await testdriver.find("The puzzle-shaped icon in the Chrome toolbar.");
+    const extensionsButton = await testdriver.find("The extensions button in the Chrome toolbar");
     await extensionsButton.click();
 
     // Look for the hello world extension in the extensions menu
@@ -54,8 +67,8 @@ describe("Chrome Extension Test", () => {
     expect(popupResult).toBeTruthy();
   });
 
-    it.skipIf(!isLinux)("should load Loom from Chrome Web Store by extensionId", async (context) => {
-    const testdriver = TestDriver(context, { headless: false, newSandbox: true});
+  it("should load Loom from Chrome Web Store by extensionId", async (context) => {
+    const testdriver = TestDriver(context);
 
     // Launch Chrome with Loom loaded by its Chrome Web Store ID
     // Loom ID: liecbddmkiiihnedobmlmillhodjkdmb
@@ -63,6 +76,16 @@ describe("Chrome Extension Test", () => {
       extensionId: 'liecbddmkiiihnedobmlmillhodjkdmb'
     });
 
+    // Navigate to testdriver.ai (extensions don't load on New Tab)
+    const addressBar = await testdriver.find("Chrome address bar");
+    await addressBar.click();
+    await testdriver.type("testdriver.ai");
+    await testdriver.pressKeys(["enter"]);
+
+    // Wait for page to load
+    const pageResult = await testdriver.assert("I can see testdriver.ai");
+    expect(pageResult).toBeTruthy();
+
     // Click on the extensions button (puzzle piece icon) in Chrome toolbar
     const extensionsButton = await testdriver.find("The puzzle-shaped icon in the Chrome toolbar.");
     await extensionsButton.click();

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

@@ -8,7 +8,7 @@ import { TestDriver } from "../../lib/vitest/hooks.mjs";
 
 /**
  * Perform login flow for SauceLabs demo app
- * @param {TestDriver} client - TestDriver client
+ * @param {import('../../sdk.js').default} client - TestDriver client instance
  * @param {string} username - Username (default: 'standard_user')
  */
 async function performLogin(client, username = "standard_user") {
@@ -27,11 +27,11 @@ async function performLogin(client, username = "standard_user") {
 
 describe("Hover Image Test", () => {
   it("should click on shopping cart icon and verify empty cart", async (context) => {
-    const testdriver = TestDriver(context, { headless: true });
+    const testdriver = TestDriver(context, { ip: process.env.TD_IP });
     
     // provision.chrome() automatically calls ready() and starts dashcam
     await testdriver.provision.chrome({
-      url: 'http://testdriver-sandbox.vercel.app/login',
+      url: 'http://testdriver-sandbox.vercel.app/login'
     });
 
     // Perform login first

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, ip: '3.138.116.105'});
+    const testdriver = TestDriver(context, { 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/test/testdriver/installer.test.mjs

@@ -12,7 +12,7 @@ describe("Provision Installer", () => {
   it.skipIf(!isLinux)(
     "should download and install a .deb package on Linux",
     async (context) => {
-      const testdriver = TestDriver(context, { newSandbox: true });
+      const testdriver = TestDriver(context);
       
       // Install bat (a cat clone with syntax highlighting) using provision.installer
       const filePath = await testdriver.provision.installer({
@@ -30,7 +30,7 @@ describe("Provision Installer", () => {
   it.skipIf(!isLinux)(
     "should download a shell script and verify it exists",
     async (context) => {
-      const testdriver = TestDriver(context, { newSandbox: true });
+      const testdriver = TestDriver(context);
       
       // Download a shell script (nvm installer)
       const filePath = await testdriver.provision.installer({

package/test/testdriver/launch-vscode-linux.test.mjs

@@ -7,7 +7,7 @@ describe("Launch VS Code on Linux", () => {
   it.skipIf(!isLinux)(
     "should launch VS Code on Debian/Ubuntu",
     async (context) => {
-      const testdriver = TestDriver(context, { newSandbox: true });
+      const testdriver = TestDriver(context);
       
       // provision.vscode() automatically calls ready() and starts dashcam
       await testdriver.provision.vscode();
@@ -24,7 +24,7 @@ describe("Launch VS Code on Linux", () => {
   it.skipIf(!isLinux)(
     "should install and use a VS Code extension",
     async (context) => {
-      const testdriver = TestDriver(context, { newSandbox: true });
+      const testdriver = TestDriver(context);
       
       // Launch VS Code with the Prettier extension installed
       await testdriver.provision.vscode({

package/test/testdriver/scroll-keyboard.test.mjs

@@ -30,7 +30,7 @@ describe("Scroll Keyboard Test", () => {
     await testdriver.scroll("down", { amount: 1000 });
 
     // Assert the page is scrolled down
-    const result = await testdriver.assert("the page is scrolled down, the hamster dance h1 text heading is not visible on the webpage");
+    const result = await testdriver.assert("The text 'The Hamster Dance' is not visible on the webpage content. It's ok if it's visible in the tab title.");
 
     expect(result).toBeTruthy();
   });

package/test/testdriver/scroll.test.mjs

@@ -35,7 +35,7 @@ describe("Scroll Test", () => {
     await testdriver.scroll("down", { amount: 1000 });
 
     // Assert page is scrolled
-    const result = await testdriver.assert("the page is scrolled down, the hamster dance h1 text heading is not visible on the webpage");
+    const result = await testdriver.assert("The text 'The Hamster Dance' is not visible on the webpage content. It's ok if it's visible in the tab title.");
     expect(result).toBeTruthy();
   });
 });