testdriverai 7.1.3 → 7.2.0

package/docs/v7/overview/readme.mdx

@@ -75,7 +75,7 @@ v7/
   - Basic assertions
   - Negative assertions (invert parameter)
   - Async assertions
-- `remember()` - Extract information from screen
+- `extract()` - Extract information from screen
 - Testing patterns:
   - Polling assertions
   - Multi-step validation

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

@@ -143,7 +143,10 @@ class InitCommand extends BaseCommand {
         },
         keywords: ["testdriver", "testing", "e2e"],
         author: "",
-        license: "ISC"
+        license: "ISC",
+        engines: {
+          node: ">=20.19.0"
+        }
       };
 
       fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
@@ -159,6 +162,7 @@ class InitCommand extends BaseCommand {
   async createVitestExample() {
     const testDir = path.join(process.cwd(), "tests");
     const testFile = path.join(testDir, "example.test.js");
+    const loginSnippetFile = path.join(testDir, "login.js");
     const configFile = path.join(process.cwd(), "vitest.config.js");
 
     // Create test directory if it doesn't exist
@@ -167,23 +171,73 @@ class InitCommand extends BaseCommand {
       console.log(chalk.gray(`  Created directory: ${testDir}`));
     }
 
-    // Create example Vitest test
+    // Create login snippet file
+    const loginSnippetContent = `/**
+ * Login snippet - reusable login function
+ * 
+ * This demonstrates how to create reusable test snippets that can be
+ * imported and used across multiple test files.
+ */
+export async function login(testdriver) {
+
+  // The password is displayed on screen, have TestDriver extract it
+  const password = await testdriver.extract('the password');
+
+  // Find the username field
+  const usernameField = await testdriver.find(
+    'Username, label above the username input field on the login form'
+  );
+  await usernameField.click();
+
+  // Type username
+  await testdriver.type('standard_user');
+
+  // Enter password form earlier 
+  // Marked as secret so it's not logged or stored
+  await testdriver.pressKeys(['tab']);
+  await testdriver.type(password, { secret: true });
+
+  // Submit the form
+  await testdriver.find('submit button on the login form').click();
+}
+`;
+
+    fs.writeFileSync(loginSnippetFile, loginSnippetContent);
+    console.log(chalk.green(`  Created login snippet: ${loginSnippetFile}`));
+
+    // Create example Vitest test that uses the login snippet
     const vitestContent = `import { test, expect } from 'vitest';
-import { chrome } from 'testdriverai/presets';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+import { login } from './login.js';
+
+test('should login and add item to cart', async (context) => {
+
+  // Create TestDriver instance - automatically connects to sandbox
+  const testdriver = TestDriver(context);
+
+  // Launch chrome and navigate to demo app
+  await testdriver.provision.chrome({ url: 'http://testdriver-sandbox.vercel.app/login' });
+
+  // Use the login snippet to handle authentication
+  // This demonstrates how to reuse test logic across multiple tests
+  await login(testdriver);
 
-test('should navigate to example.com and find elements', async (context) => {
-  // The chrome preset handles connection, browser launch, and cleanup automatically
-  const { testdriver } = await chrome(context, {
-    url: 'https://example.com'
-    // apiKey automatically read from process.env.TD_API_KEY via .env file
-  });
+  // Add item to cart
+  const addToCartButton = await testdriver.find(
+    'add to cart button under TestDriver Hat'
+  );
+  await addToCartButton.click();
 
-  // Find and verify elements
-  const heading = await testdriver.find('heading that says Example Domain');
-  expect(heading.found()).toBe(true);
+  // Open cart
+  const cartButton = await testdriver.find(
+    'cart button in the top right corner'
+  );
+  await cartButton.click();
 
-  const link = await testdriver.find('More information link');
-  expect(link.found()).toBe(true);
+  // Verify item in cart
+  const result = await testdriver.assert('TestDriver Hat is in the cart');
+  expect(result).toBeTruthy();
+  
 });
 `;
 
@@ -194,16 +248,20 @@ test('should navigate to example.com and find elements', async (context) => {
     if (!fs.existsSync(configFile)) {
       const configContent = `import { defineConfig } from 'vitest/config';
 import TestDriver from 'testdriverai/vitest';
-import dotenv from 'dotenv';
+import { config } from 'dotenv';
 
 // Load environment variables from .env file
-dotenv.config();
+config();
 
 export default defineConfig({
-  plugins: [TestDriver()],
   test: {
     testTimeout: 300000,
     hookTimeout: 300000,
+    reporters: [
+      'default',
+      TestDriver(),
+    ],
+    setupFiles: ['testdriverai/vitest/setup'],
   },
 });
 `;
@@ -290,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()
@@ -337,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;