testdriverai 7.8.0-test.8 → 7.8.0

package/docs/v7/screenshots.mdx

@@ -0,0 +1,186 @@
+---
+title: "Screenshots"
+sidebarTitle: "Screenshots"
+description: "Capture and manage screenshots during test execution"
+icon: "camera"
+mode: "wide"
+---
+
+## Overview
+
+TestDriver can capture screenshots manually at any point during a test, or automatically before and after every command. Screenshots are saved to a structured directory for easy debugging.
+
+## Manual Screenshots
+
+Use `testdriver.screenshot()` to capture the current screen:
+
+```javascript
+const path = await testdriver.screenshot();
+console.log('Saved to:', path);
+// .testdriver/screenshots/my-test/screenshot-1719849312345.png
+```
+
+### Options
+
+```javascript
+await testdriver.screenshot(filename?)
+```
+
+<ParamField path="filename" type="string">
+  Custom filename for the screenshot. `.png` is appended automatically if missing. If omitted, defaults to `screenshot-<timestamp>.png`.
+</ParamField>
+
+**Returns:** `Promise<string>` — the absolute file path of the saved screenshot.
+
+```javascript
+// Default filename
+await testdriver.screenshot();
+// → .testdriver/screenshots/my-test/screenshot-1719849312345.png
+
+// Custom filename
+await testdriver.screenshot('login-page');
+// → .testdriver/screenshots/my-test/login-page.png
+
+// With .png extension
+await testdriver.screenshot('dashboard-loaded.png');
+// → .testdriver/screenshots/my-test/dashboard-loaded.png
+```
+
+## Auto Screenshots
+
+Enable automatic screenshots before and after every command:
+
+```javascript
+const testdriver = new TestDriver({
+  autoScreenshots: true,
+});
+```
+
+<ParamField path="autoScreenshots" type="boolean" default={false}>
+  When `true`, captures a screenshot before and after every SDK command (`click`, `type`, `find`, `scroll`, `hover`, `pressKeys`, `assert`, `exec`, etc.). On error, an error-phase screenshot replaces the after-phase screenshot.
+</ParamField>
+
+### Filename Format
+
+Auto-screenshots follow this naming convention:
+
+```
+<seq>-<action>-<phase>-L<line>-<description>.png
+```
+
+| Part | Description | Example |
+|---|---|---|
+| `seq` | 3-digit zero-padded sequence number | `001` |
+| `action` | Command name | `click`, `type`, `find` |
+| `phase` | `before`, `after`, or `error` | `before` |
+| `L<line>` | Source line number from your test file | `L42` |
+| `description` | Sanitized from command arguments (max 30 chars) | `submit-button` |
+
+**Examples:**
+```
+001-find-before-L15-login-button.png
+002-find-after-L15-login-button.png
+003-click-before-L16-login-button.png
+004-click-after-L16-login-button.png
+005-type-before-L18-username-field.png
+006-type-error-L18-username-field.png
+```
+
+### Phases
+
+| Phase | When | Description |
+|---|---|---|
+| `before` | Before command executes | Captures the screen state before the action |
+| `after` | After successful command | Captures the result of the action |
+| `error` | After failed command | Captures the screen at the point of failure (replaces `after`) |
+
+## Screenshot Directory
+
+Screenshots are saved to:
+
+```
+<cwd>/.testdriver/screenshots/<testFileName>/
+```
+
+Where `<testFileName>` is the test file name without its extension. For example, a test at `tests/login.test.mjs` saves screenshots to `.testdriver/screenshots/login.test/`.
+
+### Directory Cleanup
+
+The screenshot directory for each test file is **automatically cleaned** at the start of a test run. This happens once per process per test file to prevent concurrent tests from the same file from interfering with each other.
+
+## Debug Screenshots
+
+Elements have a `saveDebugScreenshot()` method for debugging element detection:
+
+```javascript
+const el = await testdriver.find('submit button');
+
+// Save the screenshot that was used to detect this element
+const debugPath = await el.saveDebugScreenshot();
+console.log('Debug screenshot:', debugPath);
+// → ./debug-screenshot-1719849312345.png
+
+// Custom path
+await el.saveDebugScreenshot('./my-debug.png');
+```
+
+This saves the screenshot that was captured during the `find()` call, which can be useful for understanding what the AI "saw" when locating the element.
+
+## Complete Example
+
+```javascript
+import { describe, it, beforeAll, afterAll } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Screenshot Example', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    testdriver = new TestDriver({
+      autoScreenshots: true,   // capture every step
+    });
+    await testdriver.ready();
+    await testdriver.provision.chrome({ url: 'https://example.com' });
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('captures the login flow', async () => {
+    // Auto-screenshots capture before/after each command
+
+    // Manual screenshot for a specific moment
+    await testdriver.screenshot('initial-page-load');
+
+    const username = await testdriver.find('username input');
+    await username.click();
+    await testdriver.type('testuser@example.com');
+
+    await testdriver.screenshot('after-username-entry');
+
+    const password = await testdriver.find('password input');
+    await password.click();
+    await testdriver.type('password123');
+
+    await testdriver.find('login button').click();
+
+    await testdriver.screenshot('after-login-click');
+  });
+});
+```
+
+After running, your screenshot directory will contain:
+```
+.testdriver/screenshots/login-flow.test/
+├── initial-page-load.png
+├── 001-find-before-L18-username-input.png
+├── 002-find-after-L18-username-input.png
+├── 003-click-before-L19-username-input.png
+├── 004-click-after-L19-username-input.png
+├── 005-type-before-L20-testuser-example-com.png
+├── 006-type-after-L20-testuser-example-com.png
+├── after-username-entry.png
+├── 007-find-before-L24-password-input.png
+├── ...
+```

package/docs/v7/self-hosted.mdx

@@ -1,24 +1,50 @@
 ---
-title: "Self-Hosted"
+title: "Self-Hosted (Enterprise)"
 sidebarTitle: "Self-Hosted"
-description: "Unlimited test execution, complete privacy, and the ability to customize everything — all for a predictable flat license fee."
+description: "Our enterprise solution with unlimited test execution, assisted setup, and dedicated support."
 icon: "server"
+mode: "wide"
 ---
 
-Self-hosted pricing is based on **parallel test capacity**: the number of tests you can run simultaneously on **your infrastructure**. 
-
-With self-hosting, you get:.
-
-- **Flat license fee** per parallel test slot
-- **Unlimited test execution** — run as many tests as you want
-- **No device-second metering** — predictable monthly costs
-- **Use your own AI keys** — control data usage with your own OpenAI, Anthropic, or other AI provider keys
-- **Custom hardware & software** — choose instance types, resolution, install specific software, and configure networking as needed
-- **Debug & Customize** — RDP into test machines, install custom software, modify the AMI, and debug issues directly. No black boxes.
-
-## Get Started
-
-Ready to self-host? Follow our comprehensive AWS setup guide:
+Self-hosted is our enterprise solution for teams that need unlimited test execution, infrastructure control, and dedicated support. Pricing is based on **parallel test capacity** with a flat license fee — no per-second billing.
+
+<CardGroup cols={2}>
+  <Card title="Unlimited Execution" icon="infinity">
+    Run as many tests as you want with no device-second metering. Predictable monthly costs.
+  </Card>
+  <Card title="Assisted Setup & Support" icon="headset">
+    Our team helps you deploy, configure, and optimize your infrastructure. Dedicated engineering support included.
+  </Card>
+  <Card title="Full Control" icon="gear">
+    Use your own AI keys, custom hardware, specific software, and network configurations. RDP into test machines for debugging.
+  </Card>
+  <Card title="Security & Compliance" icon="shield-check">
+    Keep data in your environment. Air-gapped deployment available for regulated industries.
+  </Card>
+</CardGroup>
+
+## Deployment Options
+
+Choose the level of control you need:
+
+| Component | Standard | Air-Gapped |
+|-----------|----------|------------|
+| **Test Sandboxes** | Your AWS | Your infrastructure (any cloud or on-prem) |
+| **Dashboard** | TestDriver hosted | Your infrastructure |
+| **API** | TestDriver hosted | Your infrastructure |
+| **AI Processing** | Your API keys | Your infrastructure |
+| **Data Storage** | Your AWS account | 100% your infrastructure |
+| **Network** | Internet access required | Fully air-gapped |
+| **Cloud Providers** | AWS | AWS, Azure, GCP, on-prem |
+
+### Standard Deployment
+
+Run test sandboxes on your AWS infrastructure while using TestDriver's hosted dashboard and API:
+
+- **Quick setup** via CloudFormation — deploy in hours
+- **Dashboard access** at [console.testdriver.ai](https://console.testdriver.ai)
+- **Your AI keys** — control costs with your own OpenAI, Anthropic, or other provider
+- **Custom AMIs** — install specific software, configure networking
 
 <Card
   title="AWS Setup Guide"
@@ -28,39 +54,96 @@ Ready to self-host? Follow our comprehensive AWS setup guide:
   Step-by-step instructions for deploying TestDriver on your AWS infrastructure using CloudFormation.
 </Card>
 
+### Air-Gapped Deployment
+
+Deploy the entire TestDriver stack in your environment for complete isolation:
+
+- **Full stack** — dashboard, API, and test infrastructure all in your environment
+- **No external dependencies** — data never leaves your network perimeter
+- **Any infrastructure** — AWS, Azure, GCP, or on-premises
+- **Regulated industries** — government, defense, healthcare, finance
+
+## Custom VM Images
+
+Build test environments with your applications, dependencies, and user data pre-installed. You get full access to:
+
+- **Golden VM** — our pre-configured base image with TestDriver agent, drivers, and optimizations
+- **Packer scripts** — build custom AMIs with your applications, user data, and configurations
+- **Faster test startup** — skip installation steps by baking dependencies into your image
+- **Consistent environments** — every test runs on an identical, reproducible machine
+
+<AccordionGroup>
+  <Accordion title="What can you customize?">
+    - Install applications (browsers, desktop apps, dev tools)
+    - Configure user accounts and credentials
+    - Set up network proxies and certificates
+    - Install fonts, language packs, and locales
+    - Pre-seed databases or test fixtures
+    - Configure Windows/Linux settings
+  </Accordion>
+  
+  <Accordion title="How it works">
+    1. We provide our golden VM base image and Packer scripts
+    2. You customize the scripts to install your software and configuration
+    3. Run Packer to build your custom AMI
+    4. Configure TestDriver to use your custom AMI for test sandboxes
+    5. Tests spin up with everything pre-installed — no setup time wasted
+  </Accordion>
+</AccordionGroup>
+
+## Implementation Process
+
+<Steps>
+  <Step title="Discovery Call">
+    Discuss your requirements, security constraints, and integration needs with our team.
+  </Step>
+  
+  <Step title="Architecture Review">
+    Our engineers design a deployment architecture that meets your security and compliance requirements.
+  </Step>
+  
+  <Step title="Deployment">
+    We work with your team to deploy TestDriver, including assisted setup and configuration.
+  </Step>
+  
+  <Step title="Integration">
+    Connect TestDriver to your CI/CD pipelines, internal tools, and workflows.
+  </Step>
+  
+  <Step title="Training & Handoff">
+    Comprehensive training for your team on operating and maintaining the deployment.
+  </Step>
+</Steps>
+
+## What's Included
 
-## Who Should Self-Host?
-
-Self-hosting is ideal for teams that:
-
-- **Run high test volumes** — Flat pricing becomes more economical at scale
-- **Want infrastructure control** — Custom hardware, specific software dependencies, or network configurations
-- **Prefer predictable costs** — Budget with confidence using flat monthly fees
-
-
-## How It Works
-
-With self-hosting, you run test sandboxes on your own AWS infrastructure. TestDriver still provides:
-
-- **Dashboard** — View test results, analytics, and reports at [console.testdriver.ai](https://console.testdriver.ai)
-- **API** — Orchestration and AI-powered test execution
-- **License Management** — Your parallel test capacity
-
-You provide:
-
-- **AWS Infrastructure** — EC2 instances running in your account
-- **AI API Keys** — Use your own OpenAI, Anthropic, or other AI provider keys
-- **Custom Configuration** — Hardware specs, networking, installed software
+- **Flat license fee** per parallel test slot
+- **Unlimited test execution** — no device-second charges
+- **Assisted setup** — our team helps you deploy and configure
+- **Dedicated support** — direct access to our engineering team
+- **Custom contract terms** — volume-based pricing, custom SLAs
+- **Professional services** — implementation assistance and training
 
-## Comparison vs Cloud
+## Comparison: Hosted vs Self-Hosted
 
-| Feature | Cloud | Self-Hosted |
-|---------|-------|-------------|
-| **Setup Time** | Minutes | Hours |
+| Feature | Hosted | Self-Hosted |
+|---------|--------|-------------|
+| **Setup Time** | Minutes | Hours (assisted) |
 | **Pricing Model** | Device-seconds | Flat license fee |
-| **Infrastructure Management** | TestDriver | You |
-| **Device Location** | TestDriver cloud | Your AWS account |
+| **Infrastructure** | TestDriver | Your AWS or any cloud |
 | **AI API Keys** | TestDriver's | Your own |
 | **Custom Software** | Limited | Full control |
 | **Hardware Selection** | Standard | Your choice |
 | **Debugging Access** | Replays only | Full RDP access |
+| **Support** | Community/Standard | Dedicated engineering |
+| **Air-Gapped Option** | No | Yes |
+
+## Get Started
+
+<Card
+  title="Schedule a Consultation"
+  icon="calendar"
+  href="https://testdriver.ai/demo"
+>
+  Discuss your requirements with our team and get a custom proposal for your self-hosted deployment.
+</Card>

package/interfaces/logger.js

@@ -24,18 +24,6 @@ class CustomTransport extends Transport {
         return;
       }
 
-      if (!this.sandbox) {
-        this.sandbox = require("../agent/lib/sandbox");
-      }
-
-      if (this.sandbox && this.sandbox.instanceSocketConnected) {
-        this.sandbox.send({
-          type: "output",
-          output: Buffer.from(message).toString("base64"),
-        }).catch((e) => {
-          console.error("Error sending log:", e);
-        });
-      }
     } catch (e) {
       console.error("Error in CustomTransport log method:", e);
     }

package/interfaces/vitest-plugin.mjs

@@ -840,6 +840,9 @@ class TestDriverReporter {
     logger.debug("API key present:", !!pluginState.apiKey);
     logger.debug("API root:", pluginState.apiRoot);
 
+    // Environment info is printed by the SDK when each test initializes,
+    // so we skip the duplicate banner here in the reporter.
+
     // Check if we should enable the reporter
     if (!pluginState.apiKey) {
       logger.warn("No API key provided, skipping test recording");

package/lib/core/Dashcam.js

@@ -147,20 +147,13 @@ class Dashcam {
    * @private
    */
   async _getDashcamPath() {
-    const shell = this._getShell();
 
     if (this.client.os === "windows") {
       return "C:\\Program Files\\nodejs\\dashcam.cmd";
+    } else {
+      return "/usr/bin/dashcam";
     }
 
-    const npmPrefix = await this.client.exec(
-      shell,
-      "npm prefix -g",
-      40000,
-      process.env.TD_DEBUG == "true" ? false : true,
-    );
-
-    return npmPrefix.trim() + "/bin/dashcam";
   }
 
   /**
@@ -289,13 +282,17 @@ class Dashcam {
     const apiRoot = this._getApiRoot();
 
     if (this.client.os === "windows") {
-      const addLogOutput = await this.client.exec(
-        shell,
-        `$env:TD_API_ROOT="${apiRoot}"; & "${dashcamPath}" logs --add --type=web --pattern="${pattern}" --name="${name}"`,
-        120000,
-        process.env.TD_DEBUG == "true" ? false : true,
-      );
-      this._log("debug", "Add web log tracking output:", addLogOutput);
+      try {
+        const addLogOutput = await this.client.exec(
+          shell,
+          `$env:TD_API_ROOT="${apiRoot}"; & "${dashcamPath}" logs --add --type=web --pattern="${pattern}" --name="${name}"`,
+          120000,
+          process.env.TD_DEBUG == "true" ? false : true,
+        );
+        this._log("debug", "Add web log tracking output:", addLogOutput);
+      } catch (err) {
+        this._log("warn", "Add web log tracking failed:", err.message);
+      }
     } else {
       const addLogOutput = await this.client.exec(
         shell,

package/lib/environments.json

@@ -0,0 +1,18 @@
+{
+  "dev": {
+    "apiRoot": "https://api-dev.testdriver.ai",
+    "consoleUrl": "https://console-dev.testdriver.ai"
+  },
+  "test": {
+    "apiRoot": "https://api-test.testdriver.ai",
+    "consoleUrl": "https://console-test.testdriver.ai"
+  },
+  "canary": {
+    "apiRoot": "https://api-canary.testdriver.ai",
+    "consoleUrl": "https://console-canary.testdriver.ai"
+  },
+  "stable": {
+    "apiRoot": "https://api.testdriver.ai",
+    "consoleUrl": "https://console.testdriver.ai"
+  }
+}

package/lib/resolve-channel.js

@@ -9,12 +9,13 @@
  */
 
 const semver = require("semver");
+const environments = require("./environments.json");
 
 const CHANNELS = {
   dev: "http://localhost:1337",
-  test: "https://api-test.testdriver.ai",
-  canary: "https://api-canary.testdriver.ai",
-  latest: "https://api.testdriver.ai",
+  test: environments.test.apiRoot,
+  canary: environments.canary.apiRoot,
+  latest: environments.stable.apiRoot,
 };
 
 function resolveActiveChannel() {

package/{examples → manual}/drag-and-drop.test.mjs

@@ -46,7 +46,7 @@ describe("Drag and Drop Test", () => {
 
       const recycleBin = await testdriver.find(
         "Recycle Bin, recycle bin icon in the top left corner of the desktop",
-      );
+      ).hover();
       await recycleBin.mouseUp();
 
       // Assert "New Text Document" icon is not on the Desktop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.8.0-test.8",
+  "version": "7.8.0",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",
@@ -37,8 +37,8 @@
     "start": "node bin/testdriverai.js",
     "dev": "DEV=true node bin/testdriverai.js",
     "debug": "DEV=true VERBOSE=true node bin/testdriverai.js",
-    "docs": "npm run docs:skills && cd docs && npx mint@latest dev",
-    "docs:dev": "cd docs && npx mint dev",
+    "docs": "npm run docs:skills && cd docs && npx mint@latest dev --port 3002",
+    "docs:dev": "cd docs && npx mint dev --port 3002",
     "docs:build": "npm run docs:skills && cd docs && npx mint@latest build",
     "docs:links": "node docs/_scripts/link-replacer.js",
     "docs:skills": "node docs/_scripts/generate-skills.js",

package/sdk.js

@@ -2749,6 +2749,9 @@ CAPTCHA_SOLVER_EOF`,
       }
     }
 
+    // Log environment info immediately so it's visible even if auth fails
+    this._logEnvironmentInfo();
+
     // Authenticate first if not already authenticated
     if (!this.authenticated) {
       await this.auth();
@@ -2865,9 +2868,6 @@ CAPTCHA_SOLVER_EOF`,
       sandboxId: this.instance?.instanceId,
     });
 
-    // Log environment info (non-blocking, skip on stable)
-    this._logEnvironmentInfo();
-
     return this.instance;
   }
 

package/vitest.config.mjs

@@ -1,7 +1,9 @@
 import TestDriver from "testdriverai/vitest";
 import { defineConfig } from "vitest/config";
-import { readFileSync, existsSync } from "fs";
-import { resolve } from "path";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const { resolveEnv, getEnvironmentNames } = require("../shared/resolve-env");
 
 // Always include AWS setup - it will be a no-op unless TD_OS=windows
 // Note: dotenv is loaded automatically by the TestDriver SDK
@@ -25,45 +27,31 @@ const sharedTestConfig = {
   include: ["examples/**/*.test.mjs"],
 };
 
-// ── Parse a simple KEY=VALUE .env file ──────────────────────────────
-function parseEnvFile(filePath) {
-  if (!existsSync(filePath)) return {};
-  const env = {};
-  for (const line of readFileSync(filePath, "utf-8").split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const idx = trimmed.indexOf("=");
-    if (idx === -1) continue;
-    env[trimmed.slice(0, idx)] = trimmed.slice(idx + 1);
-  }
-  return env;
-}
-
-// ── Load base .env + per-environment overlay ────────────────────────
-const monoRoot = resolve(import.meta.dirname, "..");
-const baseEnv = parseEnvFile(resolve(monoRoot, ".env"));
-
-const environments = ["dev", "test", "canary", "stable"];
+// ── Resolve env vars via shared/resolve-env.js ──────────────────────
+// Uses: environments.json (URLs) + envs/{env}.env (overlay) + fixtures (API keys)
+// TD_PLAN selects which plan's API key to use (default: enterprise)
+const plan = process.env.TD_PLAN || "enterprise";
+const defaultEnv = process.env.TD_ENV || "dev";
+const environments = getEnvironmentNames();
 
-function envForProject(envName) {
-  const overlay = parseEnvFile(resolve(monoRoot, "envs", `${envName}.env`));
-  return { ...baseEnv, ...overlay };
-}
+// Apply default env to the main process so the reporter/plugin picks it up
+// (vitest's test.env only propagates to worker processes, not the main process)
+const defaultResolved = resolveEnv(defaultEnv, plan);
+Object.assign(process.env, defaultResolved);
 
-// ── If TD_ENV is set (e.g. from CLI), only run that environment ─────
-// Usage: TD_ENV=dev vitest run
-//        TD_ENV=canary vitest run examples/assert.test.mjs
-//        vitest run --project dev
-//        vitest run --project canary --project stable
+// ── Usage ───────────────────────────────────────────────────────────
+// TD_PLAN=enterprise vitest run --project dev
+// TD_PLAN=free vitest run --project test examples/assert.test.mjs
+// vitest run --project canary --project stable
 export default defineConfig({
   test: {
     ...sharedTestConfig,
-    env: envForProject(process.env.TD_ENV || "dev"),
+    env: defaultResolved,
     projects: environments.map((envName) => ({
       extends: true,
       test: {
         name: envName,
-        env: envForProject(envName),
+        env: resolveEnv(envName, plan),
       },
     })),
   },