testdriverai 7.1.4 → 7.2.0

package/docs/v7/overview/what-is-testdriver.mdx

@@ -2,6 +2,7 @@
 title: "What is TestDriver?"
 description: "AI-powered end-to-end testing for web, desktop, and mobile applications"
 icon: "circle-info"
+mode: "wide"
 ---
 
 TestDriver is an AI-native testing platform that lets you write tests in natural language. It uses computer vision and AI to understand your application like a human would, eliminating brittle selectors and making tests easy to write and maintain.
@@ -10,7 +11,7 @@ TestDriver is an AI-native testing platform that lets you write tests in natural
 
 Traditional E2E testing tools require:
 
-<CardGroup cols={2}>
+<CardGroup cols={1}>
   <Card title="Brittle Selectors" icon="triangle-exclamation">
     ```javascript
     // ❌ Breaks when DOM changes
@@ -18,19 +19,6 @@ Traditional E2E testing tools require:
     ```
   </Card>
 
-  <Card title="Complex Setup" icon="wrench">
-    ```javascript
-    // ❌ Manual lifecycle management
-    await browser.launch()
-    await page.goto(url)
-    try {
-      // Test code
-    } finally {
-      await browser.close()
-    }
-    ```
-  </Card>
-
   <Card title="Flaky Tests" icon="shuffle">
     ```javascript
     // ❌ Arbitrary waits

package/docs/v7/presets/chrome-extension.mdx

@@ -7,50 +7,97 @@ icon: "puzzle-piece"
 
 ## Overview
 
-Test Chrome extensions by loading them into Chrome for Testing. This preset uses the `launchChromeExtension()` helper to launch Chrome with a specific extension loaded by its Chrome Web Store ID.
+Test Chrome extensions by loading them into Chrome for Testing. Use `testdriver.provision.chromeExtension()` to launch Chrome with either:
+- A **local unpacked extension** via `extensionPath`
+- A **Chrome Web Store extension** via `extensionId`
+
+The dashcam-chrome extension is automatically included on Linux for web log capture.
 
 ## Quick Start
 
+### Using a Local Extension Path
+
 ```javascript
-import { test } from 'vitest';
-import TestDriver from 'testdriverai';
-import { 
-  runPrerunChromeExtension, 
-  runPostrun 
-} from 'testdriverai/testdriver/acceptance-sdk/setup/lifecycleHelpers.mjs';
-
-test('test chrome extension', async () => {
-  const client = await TestDriver.create({
-    apiKey: process.env.TD_API_KEY,
-    os: "linux",
-    verbosity: 1,
+import { describe, it, expect } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+describe('Chrome Extension Test', () => {
+  it('should load and test a Chrome extension', async (context) => {
+    const testdriver = TestDriver(context, { headless: true });
+    
+    // Wait for connection
+    await testdriver.ready();
+    
+    // Clone an extension repo
+    await testdriver.exec(
+      'sh',
+      'git clone --depth 1 https://github.com/GoogleChrome/chrome-extensions-samples.git /tmp/chrome-extensions-samples',
+      60000,
+      true
+    );
+
+    // Launch Chrome with the extension loaded
+    await testdriver.provision.chromeExtension({
+      extensionPath: '/tmp/chrome-extensions-samples/functional-samples/tutorial.hello-world',
+      url: 'https://example.com'
+    });
+
+    // Your test code here
+    const result = await testdriver.assert("the page is visible");
+    expect(result).toBeTruthy();
   });
+});
+```
 
-  // Launch Chrome with extension loaded
-  // Extension ID from Chrome Web Store
-  await runPrerunChromeExtension(client, "cjpalhdlnbpafiamejdnhcphjbkeiagm");
+### Using a Chrome Web Store Extension ID
 
-  // Your test code here
-  await client.focusApplication("Google Chrome");
-  
-  // ... test extension functionality
+```javascript
+import { describe, it, expect } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+describe('Chrome Extension Test', () => {
+  it('should load uBlock Origin and verify it works', async (context) => {
+    const testdriver = TestDriver(context, { headless: true });
+
+    // Launch Chrome with uBlock Origin loaded by its Chrome Web Store ID
+    await testdriver.provision.chromeExtension({
+      extensionId: 'cjpalhdlnbpafiamejdnhcphjbkeiagm', // uBlock Origin
+      url: 'https://example.com'
+    });
 
-  await runPostrun(client);
-  await client.cleanup();
+    // Your test code here
+    const result = await testdriver.assert("the page is visible");
+    expect(result).toBeTruthy();
+  });
 });
 ```
 
+## API Reference
+
+### `testdriver.provision.chromeExtension(options)`
+
+Launches Chrome for Testing with a custom extension loaded.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `extensionPath` | `string` | - | Local filesystem path to the unpacked extension directory |
+| `extensionId` | `string` | - | Chrome Web Store extension ID (e.g., `cjpalhdlnbpafiamejdnhcphjbkeiagm`) |
+| `url` | `string` | `'http://testdriver-sandbox.vercel.app/'` | URL to navigate to after launch |
+| `maximized` | `boolean` | `true` | Start Chrome maximized |
+
+**Note:** Either `extensionPath` or `extensionId` is required. On Linux, the dashcam-chrome extension is automatically loaded alongside your extension for web log capture.
+
 ## Finding Extension IDs
 
 Extension IDs can be found in the Chrome Web Store URL:
 
 ```
 https://chrome.google.com/webstore/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm
-                                                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-                                                      This is the extension ID
+                                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                                                       This is the extension ID
 ```
 
-## Popular Extensions
+### Popular Extensions
 
 | Extension | ID |
 |-----------|---|
@@ -59,73 +106,67 @@ https://chrome.google.com/webstore/detail/ublock-origin/cjpalhdlnbpafiamejdnhcph
 | Redux DevTools | `lmhkpmbekcpmknklioeibfkpmmfibljd` |
 | Bitwarden | `nngceckbapebfimnlniiiahkandclblb` |
 
-## Loading Multiple Extensions
+## Using Your Own Extension
 
-Load multiple extensions by separating IDs with commas:
+To test your own extension, you can either:
 
+1. **Clone from a repository:**
 ```javascript
-await launchChromeExtension(
-  client, 
-  "cjpalhdlnbpafiamejdnhcphjbkeiagm,nngceckbapebfimnlniiiahkandclblb"
-);
+await testdriver.ready();
+await testdriver.exec('sh', 'git clone https://github.com/your/extension.git /tmp/my-extension', 60000, true);
+await testdriver.provision.chromeExtension({
+  extensionPath: '/tmp/my-extension',
+  url: 'https://example.com'
+});
 ```
 
+2. **Upload your extension files** (if supported by your test setup)
+
+3. **Use a pre-built extension** in a known location
+
 ## Complete Example
 
 ```javascript
-import { describe, it, beforeAll, afterAll } from 'vitest';
-import TestDriver from 'testdriverai';
-import { 
-  runPrerunChromeExtension, 
-  runPostrun 
-} from 'testdriverai/testdriver/acceptance-sdk/setup/lifecycleHelpers.mjs';
-
-describe('Chrome Extension Testing', () => {
-  let client;
-  let dashcamUrl;
-
-  beforeAll(async () => {
-    client = await TestDriver.create({
-      apiKey: process.env.TD_API_KEY,
-      os: "linux",
-      verbosity: 1,
+import { describe, it, expect } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+describe('Chrome Extension - Hello World', () => {
+  it('should load extension and verify popup', async (context) => {
+    const testdriver = TestDriver(context, { 
+      headless: true, 
+      newSandbox: true, 
+      cacheKey: 'chrome-extension-test' 
     });
+    
+    // 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
+    );
 
-    // Load uBlock Origin extension
-    await runPrerunChromeExtension(client, "cjpalhdlnbpafiamejdnhcphjbkeiagm");
-  });
-
-  afterAll(async () => {
-    if (client) {
-      dashcamUrl = await runPostrun(client);
-      await client.cleanup();
-    }
-  });
-
-  it('should verify extension is loaded', async () => {
-    await client.focusApplication("Google Chrome");
+    // 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'
+    });
 
-    // Navigate to a page
-    const element = await client.find("TestDriver.ai Sandbox");
-    expect(element.found()).toBe(true);
+    // Verify the page loaded
+    const pageResult = await testdriver.assert("the testdriver.ai website is visible");
+    expect(pageResult).toBeTruthy();
 
-    // Test extension-specific functionality
-    // For example, checking if ads are blocked with uBlock
-  });
+    // Click on the extensions button in Chrome toolbar
+    const extensionsButton = await testdriver.find("Extensions button, puzzle piece icon in Chrome toolbar");
+    await extensionsButton.click();
 
-  it('should access extension popup', async () => {
-    await client.focusApplication("Google Chrome");
-    
-    // Open extension management
-    await client.exec(
-      "sh",
-      `xdotool key --clearmodifiers ctrl+shift+e`,
-      5000,
-      true
-    );
+    // Find and click the hello world extension
+    const helloExtension = await testdriver.find("Hello World extension in the extensions dropdown");
+    await helloExtension.click();
 
-    // Wait for extensions page
-    await new Promise((resolve) => setTimeout(resolve, 2000));
+    // Verify the extension popup shows
+    const popupResult = await testdriver.assert("a popup shows with the text 'Hello Extensions'");
+    expect(popupResult).toBeTruthy();
   });
 });
 ```
@@ -139,19 +180,9 @@ Chrome for Testing is pre-installed in the E2B sandbox environment at:
 /usr/local/bin/chrome-for-testing (symlink)
 ```
 
-## Direct API Usage
-
-Use the lower-level API for more control:
-
-```javascript
-import { launchChromeExtension } from 'testdriverai/testdriver/acceptance-sdk/setup/lifecycleHelpers.mjs';
-
-// Launch with specific extension and URL
-await launchChromeExtension(
-  client,
-  "cjpalhdlnbpafiamejdnhcphjbkeiagm",
-  "https://example.com"
-);
+The dashcam-chrome extension is pre-installed at:
+```
+/usr/lib/node_modules/dashcam-chrome/build
 ```
 
 ## Testing Extension Features
@@ -159,44 +190,39 @@ await launchChromeExtension(
 ### Test Extension Popup
 
 ```javascript
-it('opens extension popup', async () => {
-  // Click extension icon (varies by extension)
-  await client.click('extension icon in toolbar');
+it('opens extension popup', async (context) => {
+  const testdriver = TestDriver(context, { headless: true });
   
-  // Interact with popup
-  const popup = await client.find('extension popup window');
-  expect(popup.found()).toBe(true);
-});
-```
-
-### Test Extension Settings
-
-```javascript
-it('configures extension settings', async () => {
-  // Right-click extension icon
-  await client.rightClick('extension icon');
+  // Setup extension...
+  await testdriver.provision.chromeExtension({
+    extensionPath: '/path/to/extension',
+    url: 'https://example.com'
+  });
   
-  // Click options
-  await client.click('Options');
+  // Click extension icon in toolbar
+  const extensionIcon = await testdriver.find('extension icon in toolbar');
+  await extensionIcon.click();
   
-  // Configure settings
-  await client.click('Enable feature X');
-  await client.click('Save');
+  // Interact with popup
+  const result = await testdriver.assert('extension popup is visible');
+  expect(result).toBeTruthy();
 });
 ```
 
 ### Test Content Scripts
 
 ```javascript
-it('verifies content script injection', async () => {
-  // Navigate to a page
-  await client.exec('sh', 'xdotool key ctrl+l', 5000, true);
-  await client.type('https://example.com');
-  await client.pressKeys('Enter');
+it('verifies content script injection', async (context) => {
+  const testdriver = TestDriver(context, { headless: true });
+  
+  await testdriver.provision.chromeExtension({
+    extensionPath: '/path/to/extension',
+    url: 'https://example.com'
+  });
   
   // Check for extension-injected elements
-  const injected = await client.find('element added by extension');
-  expect(injected.found()).toBe(true);
+  const result = await testdriver.assert('element added by extension is visible');
+  expect(result).toBeTruthy();
 });
 ```
 
@@ -204,9 +230,9 @@ it('verifies content script injection', async () => {
 
 ### Extension Not Loading
 
-1. Verify the extension ID is correct
+1. Verify the extension path exists and contains a valid `manifest.json`
 2. Check Chrome for Testing is installed in the sandbox
-3. Ensure extension is compatible with Chrome for Testing version
+3. Ensure extension is compatible with Chrome for Testing version (Manifest V3 recommended)
 
 ### Extension Permissions
 
@@ -219,5 +245,4 @@ Some extensions may require additional permissions or setup. You may need to:
 ## See Also
 
 - [Web Apps (Chrome)](/v7/presets/chrome) - Regular Chrome browser testing
-- [Desktop Apps (Electron)](/v7/presets/electron) - Electron app testing
-- [Lifecycle Helpers](/v7/guides/lifecycle) - Prerun/postrun functions
+- [Desktop Apps (Electron)](/v7/presets/electron) - Electron app testing- [Lifecycle Helpers](/v7/guides/lifecycle) - Prerun/postrun functions

package/interfaces/cli/commands/init.js

@@ -348,7 +348,7 @@ jobs:
     - name: Run TestDriver.ai tests
       env:
         TD_API_KEY: \${{ secrets.TD_API_KEY }}
-      run: npm test
+      run: npx vitest run
 
     - name: Upload test results
       if: always()
@@ -395,11 +395,11 @@ jobs:
   printNextSteps() {
     console.log(chalk.cyan("Next steps:\n"));
     console.log("  1. Run your tests:");
-    console.log(chalk.gray("     npm test\n"));
+    console.log(chalk.gray("     npx vitest run\n"));
     console.log("  2. For CI/CD, add TD_API_KEY to your GitHub repository secrets");
     console.log(chalk.gray("     Settings → Secrets → Actions → New repository secret\n"));
     console.log(
-      chalk.cyan("Learn more at https://docs.testdriver.ai/getting-started\n"),
+      chalk.cyan("Learn more at https://docs.testdriver.ai/v7/getting-started/\n"),
     );
   }
 }

package/interfaces/cli/lib/base.js

@@ -73,12 +73,13 @@ class BaseCommand extends Command {
     };
 
     let isConnected = false;
+    const debugMode = process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
 
-    // Use pattern matching for log events, but skip log:Debug
+    // Use pattern matching for log events, but skip log:Debug unless debug mode is enabled
     this.agent.emitter.on("log:*", (message) => {
       const event = this.agent.emitter.event;
 
-      if (event === events.log.debug) return;
+      if (event === events.log.debug && !debugMode) return;
 
       if (event === events.log.narration && isConnected) return;
       console.log(message);

package/interfaces/logger.js

@@ -21,8 +21,6 @@ class CustomTransport extends Transport {
         this.sandbox = require("../agent/lib/sandbox");
       }
 
-      console.log("CustomTransport log message:", message);
-
       if (this.sandbox && this.sandbox.instanceSocketConnected) {
         if (typeof message === "object") {
           console.log(chalk.cyan("protecting against base64 error"));

package/interfaces/shared-test-state.mjs

@@ -22,11 +22,6 @@ const sharedState = {
  * Set the test run information
  */
 export function setTestRunInfo(info) {
-  console.log("[SharedState] Setting test run info:", {
-    testRunId: info.testRunId,
-    hasToken: !!info.token,
-    hasTestRun: !!info.testRun,
-  });
 
   if (info.testRun) sharedState.testRun = info.testRun;
   if (info.testRunId) sharedState.testRunId = info.testRunId;