testdriverai 7.8.0-test.7 → 7.8.0-test.71

package/docs/v7/redraw.mdx

@@ -0,0 +1,216 @@
+---
+title: "Redraw"
+sidebarTitle: "Redraw"
+description: "Wait for the screen to stabilize after interactions"
+icon: "rotate"
+mode: "wide"
+---
+
+## Overview
+
+The redraw system waits for the screen to stabilize after an interaction before continuing. It detects when animations, page loads, and network requests have settled, preventing actions from being performed on a changing screen.
+
+<Note>
+  **Redraw is disabled by default since v7.3.** Enable it explicitly if your tests interact with applications that have significant animations or loading states.
+</Note>
+
+## How It Works
+
+Redraw uses a **two-phase detection** approach:
+
+1. **Change Detection** — Compare the current frame to the initial screenshot taken right after the action. If the pixel diff exceeds 0.1%, the screen has changed.
+2. **Stability Detection** — Compare consecutive frames using z-score analysis. When the diff between frames drops below 0.1% or the z-score is negative (current diff is below average), the screen has settled.
+
+The screen is considered **settled** when both phases complete: the screen changed from the initial state AND consecutive frames are now stable.
+
+```mermaid
+flowchart TD
+    A[Action performed] --> B{Phase 1: Change Detection\ndiffFromInitial > 0.1%?}
+    B -- "Yes (screen changed)" --> C{Phase 2: Stability\nz-score < 0 or\ndiffPercent < 0.1%?}
+    C -- "Yes (frames stable)" --> D[Screen settled ✓]
+    B -- "No (waiting...)" --> B
+    C -- "No (waiting...)" --> C
+```
+
+### Polling
+
+The system polls at **500ms intervals**, comparing screenshot frames. This reduces WebSocket traffic while still providing responsive detection.
+
+### Pixel Comparison
+
+Uses [pixelmatch](https://github.com/mapbox/pixelmatch) for per-pixel comparison with a threshold of `0.1` for pixel sensitivity. A frame diff above **0.1% of total pixels** indicates the screen has changed.
+
+### Z-Score Analysis
+
+Screen stability uses statistical analysis of the last **10 measurements**:
+
+1. Calculate the mean and standard deviation of consecutive frame diffs
+2. Compute the z-score: `(currentDiff - mean) / stddev`
+3. Screen is stable when `diffPercent < 0.1%` or `z-score < 0` (current diff is below the average)
+
+This approach adapts to the specific animation patterns of your application rather than using a fixed threshold.
+
+## Per-Command Timeouts
+
+Each command type has a specific redraw timeout:
+
+| Command | Timeout | Reason |
+|---------|---------|--------|
+| `click` | 5000ms | Page navigations, modal openings |
+| `hover` (within click) | 5000ms | Same as click |
+| `hover` (standalone) | 2500ms | Tooltip animations |
+| `scroll` | 5000ms | Lazy-loaded content |
+| `type` | 5000ms | Autocomplete, validation |
+| `pressKeys` | 5000ms | Keyboard shortcuts may trigger changes |
+| `focusApplication` | 1000ms | Window focus animations |
+
+If the timeout is reached before the screen settles, the command continues anyway. The timeout event is available via the `redraw:complete` event.
+
+## Configuration
+
+### Constructor Options
+
+```javascript
+const testdriver = new TestDriver({
+  // Shorthand: enable/disable
+  redraw: true,    // enable with defaults
+  redraw: false,   // disable (default since v7.3)
+
+  // Full configuration
+  redraw: {
+    enabled: true,
+    screenRedraw: true,       // enable screen pixel diff detection
+    networkMonitor: false,    // enable network settling detection
+  },
+});
+```
+
+<ParamField path="redraw" type="RedrawConfig | boolean" default={false}>
+  Redraw configuration. Pass `true`/`false` for shorthand, or an object for fine-grained control.
+
+  <Expandable title="properties">
+    <ParamField path="enabled" type="boolean" default={false}>
+      Enable or disable the redraw system. Default changed to `false` in v7.3.
+    </ParamField>
+    
+    <ParamField path="screenRedraw" type="boolean" default={true}>
+      Enable pixel-diff-based screen change detection. If both `screenRedraw` and `networkMonitor` are `false`, redraw auto-disables.
+    </ParamField>
+    
+    <ParamField path="networkMonitor" type="boolean" default={false}>
+      Enable network traffic monitoring for settling detection. Monitors WebSocket traffic on the sandbox to detect when network activity subsides.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+### Per-Command Override
+
+Override redraw settings for individual commands:
+
+```javascript
+// Enable redraw for a specific click
+await testdriver.find('load more').click({
+  redraw: { enabled: true },
+});
+
+// Disable redraw for a fast interaction
+await testdriver.find('checkbox').click({
+  redraw: false,
+});
+```
+
+## Network Settling
+
+When `networkMonitor` is enabled, the system also monitors sandbox network traffic:
+
+- Polls for `totalBytesReceived` and `totalBytesSent` from the sandbox
+- Keeps the last **60 measurements**
+- Calculates z-scores for both RX and TX byte rates
+- Network is **settled** when both RX and TX z-scores are negative (traffic is below average)
+- Has a **10-second timeout** for network polling
+- Non-critical: network errors are logged but never throw
+
+The final settling condition requires **both** screen AND network to be settled (when both are enabled).
+
+## Events
+
+The redraw system emits events through the SDK emitter. See [Events](/v7/events) for the full event reference.
+
+| Event | Description |
+|---|---|
+| `redraw:status` | Emitted on each poll with current screen diff, network stats, and timeout info |
+| `redraw:complete` | Emitted when redraw resolves (settled or timed out) |
+
+```javascript
+testdriver.emitter.on('redraw:status', (status) => {
+  console.log(`Screen: ${status.redraw.text}`);
+  console.log(`Network: ${status.network.text}`);
+  console.log(`Timeout: ${status.timeout.text}`);
+});
+
+testdriver.emitter.on('redraw:complete', (result) => {
+  if (result.isTimeout) {
+    console.warn(`Redraw timed out after ${result.timeElapsed}ms`);
+  } else {
+    console.log(`Screen settled in ${result.timeElapsed}ms`);
+  }
+});
+```
+
+## When to Use Redraw
+
+**Enable redraw when:**
+- Testing single-page applications (SPAs) with route transitions
+- Interacting with pages that lazy-load content on scroll
+- Clicking buttons that trigger animations or modals
+- Testing apps with significant network-driven UI updates
+
+**Keep redraw disabled when:**
+- Tests are already stable without it
+- You want faster test execution
+- Your application has minimal animations
+- You're using explicit waits or assertions instead
+
+## Types
+
+```typescript
+interface RedrawConfig {
+  enabled?: boolean;              // Default: false (since v7.3)
+  screenRedraw?: boolean;         // Default: true
+  networkMonitor?: boolean;       // Default: false
+}
+
+interface RedrawStatusEvent {
+  redraw: {
+    enabled: boolean;
+    settled: boolean;
+    hasChangedFromInitial: boolean;
+    consecutiveFramesStable: number;
+    diffFromInitial: number;
+    diffFromLast: number;
+    text: string;
+  };
+  network: {
+    enabled: boolean;
+    settled: boolean;
+    rxBytes: number;
+    txBytes: number;
+    text: string;
+  };
+  timeout: {
+    isTimeout: boolean;
+    elapsed: number;
+    max: number;
+    text: string;
+  };
+}
+
+interface RedrawCompleteEvent {
+  screenSettled: boolean;
+  hasChangedFromInitial: boolean;
+  consecutiveFramesStable: number;
+  networkSettled: boolean;
+  isTimeout: boolean;
+  timeElapsed: number;
+}
+```

package/docs/v7/running-tests.mdx

@@ -133,7 +133,7 @@ export default defineConfig({
 <Card
   title="View Plans & Pricing"
   icon="credit-card"
-  href="/v7/cloud"
+  href="/v7/hosted"
 >
   Compare plans and find the right level of parallelization for your team.
 </Card>

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>