testdriverai 7.2.9 → 7.2.11

package/docs/v7/cloud.mdx

@@ -0,0 +1,120 @@
+---
+title: "Cloud Plan"
+sidebarTitle: "Cloud"
+description: "The fastest way to get started with TestDriver. Just set your API key and start testing."
+icon: "cloud"
+---
+
+Cloud pricing is based on **device-seconds**: the amount of time your tests run on **our infrastructure**.
+
+- **Zero Setup** — Start testing immediately. No DevOps required.
+- **Free Tier** — Get started with a limited preview at no cost.
+- **Pay As You Go** — Only pay for the device-seconds you use.
+
+## Get Started
+Cloud is the default when you follow the Quickstart guide. 
+<Card
+  title="Try the Quickstart"  
+  icon="play"
+  href="/v7/quickstart"
+>
+  Set your API key and start testing in minutes.
+</Card>
+
+## Parallel Testing Limits
+
+Your account has a set number of **license slots** that determine how many devices can run simultaneously. You can view your available slots in the [TestDriver Dashboard](https://console.testdriver.ai).
+
+<Info>
+  **When is a slot in use?** A license slot is occupied when a test client is connected. As soon as your device is destroyed the slot becomes available immediately.
+</Info>
+
+## Avoiding Slot Conflicts
+
+To prevent tests from failing due to exceeding your license slot limit, we recommend two key configurations:
+
+<AccordionGroup>
+  <Accordion title="Set Maximum Concurrency in Vitest">
+    Limit concurrent tests to match your available license slots:
+
+    ```javascript vitest.config.mjs
+    import { defineConfig } from 'vitest/config';
+    import { TestDriver } from 'testdriverai/vitest';
+
+    export default defineConfig({
+      test: {
+        testTimeout: 900000,
+        hookTimeout: 900000,
+        maxConcurrency: 5, // Set to your license slot limit
+        reporters: ['default', TestDriver()],
+        setupFiles: ['testdriverai/vitest/setup'],
+      },
+    });
+    ```
+
+    <Tip>
+      Check your slot count at [console.testdriver.ai](https://console.testdriver.ai) and set `maxConcurrency` to that number or lower.
+    </Tip>
+  </Accordion>
+
+  <Accordion title="Use GitHub Concurrency Keys">
+    Prevent multiple workflow runs from competing for the same slots by using [GitHub's concurrency controls](https://docs.github.com/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs):
+
+    ```yaml .github/workflows/test.yml
+    name: Tests
+
+    on:
+      push:
+        branches: [main]
+      pull_request:
+
+    # Prevent concurrent runs from competing for license slots
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+
+    jobs:
+      test:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+          
+          - name: Setup Node.js
+            uses: actions/setup-node@v4
+            with:
+              node-version: '20'
+          
+          - name: Install dependencies
+            run: npm install
+          
+          - name: Run tests
+            run: npx vitest run
+            env:
+              TD_API_KEY: ${{ secrets.TD_API_KEY }}
+    ```
+
+    The `concurrency` block ensures:
+    - Only one workflow run per branch runs at a time
+    - New pushes cancel in-progress runs on the same branch
+    - Different branches/PRs can run in parallel (up to your slot limit)
+  </Accordion>
+</AccordionGroup>
+
+## When to Consider Self-Hosted
+
+Cloud is perfect for getting started and for teams that want zero infrastructure management. However, you might consider [Self-Hosted](/v7/self-hosted) if you:
+
+- Want to escape per-second billing with a flat license fee
+- Require greater concurrency than offered in Cloud plans
+- Need full control over your infrastructure and privacy
+- Want to use your own AI API keys
+- Require custom hardware configurations
+- Have high test volumes that make self-hosting more economical
+
+<Card
+  title="Explore Self-Hosted"
+  icon="server"
+  href="/v7/self-hosted"
+>
+  Learn about self-hosting for unlimited test execution at a flat rate.
+</Card>

package/docs/v7/customizing-devices.mdx

@@ -0,0 +1,129 @@
+---
+title: "Customizing Devices"
+description: "Configure TestDriver sandbox options and environment settings"
+icon: "computer"
+---
+
+## TestDriver Options
+
+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`.
+
+```javascript
+const testdriver = TestDriver(context, {
+  os: "windows",  // Run on Windows sandbox
+});
+```
+
+#### Using Environment Variables
+
+You can make the operating system configurable via environment variables. This requires adding code to read from `process.env` in your test:
+
+```javascript
+const testdriver = TestDriver(context, {
+  os: process.env.TD_OS || "linux",  // Read from env, default to Linux
+});
+```
+
+Then pass the variable when running tests:
+
+```bash
+# Run tests on Windows
+TD_OS=windows npx vitest run
+
+# Run tests on Linux (default)
+TD_OS=linux npx vitest run
+```
+
+This pattern is useful for running the same test suite across multiple operating systems in CI/CD:
+
+```yaml
+# Example GitHub Actions matrix
+strategy:
+  matrix:
+    os: [linux, windows]
+steps:
+  - run: TD_OS=${{ matrix.os }} npx vitest run
+```
+
+## Keepalive
+
+By default, sandboxes terminate immediately when the test finishes. Set this value to keep the sandbox alive for reconnection.
+
+The `keepAlive` param enables you to keep the sandbox running after the test completes for debugging or reconnection.  This will allow you to use the debugger to inspect the state of the device after the test has finished.
+
+```javascript
+const testdriver = TestDriver(context, {
+  keepAlive: 300000,  // Keep sandbox alive for 5 minutes after test
+});
+```
+
+### Reconnecting to Existing Sandbox
+
+Speed up test development by reconnecting to an existing sandbox instead of starting fresh each time. This lets you iterate quickly on failing steps without re-running the entire test from the beginning.
+
+Split your test into two files: one for known-good steps that set up the desired state, and another for work-in-progress steps you want to debug.
+
+```javascript known-good.test.mjs
+const testdriver = TestDriver(context, {
+  newSandbox: true,
+  headless: false,
+  keepAlive: 60000,  // Keep sandbox alive for 60 seconds after test
+});
+```
+
+```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
+});
+```
+
+Then, you can run both tests in sequence:
+
+```bash
+npx vitest run -t known-good.test.mjs -t work-in-progress.test.mjs
+```
+
+And as you make changes to `work-in-progress.test.mjs`, you can re-run just that file to quickly iterate on the failing steps.
+
+```bash
+npx vitest run work-in-progress.test.mjs
+```
+
+<Warning>
+  Reconnect only works if run within the `keepAlive` window of the previous test.
+</Warning>

package/docs/v7/{api/dashcam.mdx → dashcam.mdx}

@@ -417,81 +417,3 @@ On Linux/Mac, Dashcam uses shell commands:
 // Unix-specific paths
 await dashcam.addFileLog('/tmp/testdriver.log', 'TestDriver Log');
 ```
-
-## Troubleshooting
-
-### No Replay URL Returned
-
-If `stop()` returns `null`:
-
-1. Check that recording was started with `start()`
-2. Verify authentication succeeded
-3. Ensure dashcam CLI is installed in the environment
-4. Check console output for error messages
-
-### Recording Not Starting
-
-If recording doesn't start:
-
-1. Verify API key is correct
-2. Check `auth()` completed successfully
-3. Ensure dashcam CLI is installed globally
-4. Check `isRecording()` to verify state
-
-### Logs Not Appearing
-
-If logs aren't visible in replay:
-
-1. Add logs before calling `start()`
-2. Verify log file paths are correct
-3. Ensure log files exist and are accessible
-4. Check file permissions
-
-## Best Practices
-
-<AccordionGroup>
-  <Accordion title="Always authenticate before starting">
-    ```javascript
-    await dashcam.auth();
-    await dashcam.start();
-    ```
-  </Accordion>
-  
-  <Accordion title="Add logs before starting recording">
-    ```javascript
-    await dashcam.addFileLog('/tmp/app.log', 'App Log');
-    await dashcam.start();
-    ```
-  </Accordion>
-  
-  <Accordion title="Always stop recording">
-    Use try/finally to ensure recording stops:
-    
-    ```javascript
-    try {
-      await dashcam.start();
-      // Test code
-    } finally {
-      await dashcam.stop();
-    }
-    ```
-  </Accordion>
-  
-  <Accordion title="Check for replay URL">
-    ```javascript
-    const url = await dashcam.stop();
-    if (url) {
-      console.log('Replay:', url);
-    } else {
-      console.warn('No replay URL available');
-    }
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## See Also
-
-- [Chrome Preset](/v7/presets/chrome) - Automatic Dashcam setup for web apps
-- [VS Code Extensions](/v7/presets/vscode) - Dashcam with VS Code testing
-- [Desktop Apps](/v7/presets/electron) - Dashcam with Electron apps
-- [Lifecycle Helpers](/v7/guides/lifecycle) - Prerun/postrun with Dashcam

package/docs/v7/{api/doubleClick.mdx → double-click.mdx}

@@ -95,8 +95,8 @@ expect(selectedText).toBe('TestDriver');
 
 ## Related Methods
 
-- [`click()`](/v7/api/click) - Single click on an element
-- [`rightClick()`](/v7/api/rightClick) - Right-click to open context menu
-- [`mouseDown()`](/v7/api/mouseDown) - Press mouse button without releasing
-- [`mouseUp()`](/v7/api/mouseUp) - Release mouse button
-- [`hover()`](/v7/api/hover) - Move mouse over element without clicking
+- [`click()`](/v7/click) - Single click on an element
+- [`rightClick()`](/v7/right-click) - Right-click to open context menu
+- [`mouseDown()`](/v7/mouse-down) - Press mouse button without releasing
+- [`mouseUp()`](/v7/mouse-up) - Release mouse button
+- [`hover()`](/v7/hover) - Move mouse over element without clicking

package/docs/v7/{api/elements.mdx → elements.mdx}

@@ -496,47 +496,6 @@ const elementData = JSON.stringify(element);
   Use JSON serialization when you need to log element data or when debugging why an element wasn't found. The serialized output excludes large binary data (screenshots) and circular references.
 </Tip>
 
-## Polling for Elements
-
-Use polling to wait for elements that may not be immediately visible:
-
-```javascript
-// Poll until element appears
-let loginButton;
-const maxAttempts = 30;
-
-for (let i = 0; i < maxAttempts; i++) {
-  loginButton = await testdriver.find('login button');
-  if (loginButton.found()) break;
-  await new Promise(resolve => setTimeout(resolve, 1000));
-}
-
-if (loginButton.found()) {
-  await loginButton.click();
-} else {
-  throw new Error('Login button never appeared');
-}
-```
-
-**Helper function for polling:**
-```javascript
-async function waitForElement(testdriver, description, timeout = 30000) {
-  const startTime = Date.now();
-  
-  while (Date.now() - startTime < timeout) {
-    const element = await testdriver.find(description);
-    if (element.found()) return element;
-    await new Promise(resolve => setTimeout(resolve, 1000));
-  }
-  
-  throw new Error(`Element "${description}" not found after ${timeout}ms`);
-}
-
-// Usage
-const button = await waitForElement(testdriver, 'submit button', 10000);
-await button.click();
-```
-
 ## Examples
 
 ### Basic Element Interaction
@@ -627,19 +586,7 @@ if (notification.found()) {
     await element.click();
     ```
   </Accordion>
-  
-  <Accordion title="Use polling for dynamic content">
-    Don't assume elements are immediately visible:
-    
-    ```javascript
-    let element;
-    for (let i = 0; i < 30; i++) {
-      element = await testdriver.find('loading complete message');
-      if (element.found()) break;
-      await new Promise(resolve => setTimeout(resolve, 1000));
-    }
-    ```
-  </Accordion>
+
   
   <Accordion title="Reuse element references when possible">
     If you need to interact with the same element multiple times, reuse the reference:

package/docs/v7/enterprise.mdx

@@ -0,0 +1,116 @@
+---
+title: "Enterprise"
+sidebarTitle: "Enterprise"
+description: "Air-gapped security and full customization for demanding environments"
+icon: "building"
+---
+
+
+## Why Enterprise?
+
+<CardGroup cols={2}>
+  <Card title="Air-Gapped Security" icon="shield-check">
+    Deploy everything in your environment. No data leaves your network. Complete isolation from external services.
+  </Card>
+  <Card title="Full Customization" icon="gear">
+    Custom integrations, dedicated infrastructure, and tailored solutions for your unique requirements.
+  </Card>
+  <Card title="Self-Hosted Dashboard & API" icon="server">
+    Run the entire TestDriver stack — dashboard, API, and test infrastructure — within your own environment.
+  </Card>
+  <Card title="Dedicated Support" icon="headset">
+    Direct access to our engineering team for implementation, customization, and ongoing support.
+  </Card>
+</CardGroup>
+
+## Who Needs Enterprise?
+
+Enterprise is designed for organizations that:
+
+- **Require air-gapped deployments** — Regulated industries, government, defense, or strict compliance requirements
+- **Cannot use external APIs** — Data must never leave your network perimeter
+- **Need custom integrations** — Unique CI/CD systems, internal tools, or specialized workflows
+- **Want dedicated support** — Direct engineering support for complex implementations
+
+## What's Included
+
+### Fully Self-Hosted Stack
+
+Unlike [Self-Hosted](/v7/self-hosted) (which uses TestDriver's hosted dashboard and API), Enterprise deploys everything in your environment:
+
+| Component | Self-Hosted | Enterprise |
+|-----------|-------------|------------|
+| Test Sandboxes | Your infrastructure | Your infrastructure |
+| Dashboard | TestDriver hosted | Your infrastructure |
+| API | TestDriver hosted | Your infrastructure |
+| AI Processing | Your API keys | Your infrastructure |
+| Data Storage | Your AWS account | Your infrastructure |
+
+### Custom Contract Terms
+
+- Volume-based pricing
+- Custom SLAs
+- Dedicated support channels
+- Professional services for implementation
+- Training for your team
+
+## 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 within your environment, including dashboard, API, and test infrastructure.
+  </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>
+
+## Security & Compliance
+
+Enterprise deployments support:
+
+- **SOC 2** compliance requirements
+- **HIPAA** for healthcare applications
+- **FedRAMP** for government deployments
+- **PCI DSS** for payment processing
+- **Custom compliance frameworks** as needed
+
+<Note>
+  All data remains within your network perimeter. TestDriver has no access to your test results, application data, or infrastructure.
+</Note>
+
+## Comparison: Self-Hosted vs Enterprise
+
+| Feature | Self-Hosted | Enterprise |
+|---------|-------------|------------|
+| **Test Infrastructure** | Your AWS | Your infrastructure (any) |
+| **Dashboard** | TestDriver cloud | Your infrastructure |
+| **API** | TestDriver cloud | Your infrastructure |
+| **Data Location** | Your AWS + TestDriver | 100% your infrastructure |
+| **Network Requirements** | Internet access | Can be fully air-gapped |
+| **Cloud Providers** | AWS only | Any (AWS, Azure, GCP, on-prem) |
+| **Support** | Standard | Dedicated engineering |
+| **Contract** | Standard licensing | Custom terms |
+
+## Get Started
+
+<Card
+  title="Schedule a Consultation"
+  icon="calendar"
+  href="https://calendly.com/d/cq23-qyn-3v6/testdriver-ai-demo"
+>
+  Discuss your requirements with our team and get a custom proposal for your Enterprise deployment.
+</Card>

package/docs/v7/examples.mdx

@@ -0,0 +1,5 @@
+---
+title: "Examples"
+url: "https://github.com/testdriverai/testdriverai/tree/main/test/testdriver"
+icon: 'code'
+---

package/docs/v7/{api/exec.mdx → exec.mdx}

@@ -341,6 +341,6 @@ describe('Code Execution', () => {
 
 ## Related Methods
 
-- [`focusApplication()`](/v7/api/focusApplication) - Focus apps before exec
-- [`find()`](/v7/api/find) - Locate elements (alternative to DOM manipulation)
-- [`type()`](/v7/api/type) - Type text (alternative to JS form filling)
+- [`focusApplication()`](/v7/focus-application) - Focus apps before exec
+- [`find()`](/v7/find) - Locate elements (alternative to DOM manipulation)
+- [`type()`](/v7/type) - Type text (alternative to JS form filling)

package/docs/v7/{api/find.mdx → find.mdx}

@@ -101,7 +101,7 @@ The returned `Element` object provides:
 - `width`, `height` - Element dimensions
 - `boundingBox` - Complete bounding box
 
-See [Elements Reference](/v7/api/elements) for complete details.
+See [Elements Reference](/v7/elements) for complete details.
 
 ### JSON Serialization
 
@@ -188,27 +188,23 @@ This is useful for:
 
 ## Polling for Dynamic Elements
 
-For elements that may not be immediately visible:
+For elements that may not be immediately visible, use the `timeout` option to automatically poll:
 
 ```javascript
-// Poll until element appears
-let loginButton;
-const maxAttempts = 30;
-
-for (let i = 0; i < maxAttempts; i++) {
-  loginButton = await testdriver.find('login button');
-  if (loginButton.found()) break;
-  await new Promise(r => setTimeout(r, 1000));
-}
+// Poll for element (retries every 5 seconds until found or timeout)
+const element = await testdriver.find('login button', { timeout: 30000 });
+await element.click();
+```
 
-if (!loginButton.found()) {
-  throw new Error('Login button never appeared');
-}
+The `timeout` option:
+- Retries finding the element every 5 seconds
+- Stops when the element is found or the timeout expires
+- Logs progress during polling
+- Returns the element (check `element.found()` if not throwing on failure)
 
-await loginButton.click();
-```
+### Manual Polling (Alternative)
 
-### Helper Function
+If you need custom polling logic:
 
 ```javascript
 async function waitForElement(testdriver, description, timeout = 30000) {
@@ -348,10 +344,10 @@ describe('Element Finding', () => {
 
 ## Related Methods
 
-- [`click()`](/v7/api/click) - Click on found elements
-- [`hover()`](/v7/api/hover) - Hover over elements
-- [`assert()`](/v7/api/assert) - Verify element states
-- [Elements Reference](/v7/api/elements) - Complete Element API
+- [`click()`](/v7/click) - Click on found elements
+- [`hover()`](/v7/hover) - Hover over elements
+- [`assert()`](/v7/assert) - Verify element states
+- [Elements Reference](/v7/elements) - Complete Element API
 
 ---
 

package/docs/v7/{api/focusApplication.mdx → focus-application.mdx}

@@ -289,6 +289,6 @@ describe('Multi-Application Workflow', () => {
 
 ## Related Methods
 
-- [`exec()`](/v7/api/exec) - Launch applications with PowerShell
-- [`pressKeys()`](/v7/api/pressKeys) - Use Alt+Tab to switch windows
-- [`find()`](/v7/api/find) - Locate elements in the focused window
+- [`exec()`](/v7/exec) - Launch applications with PowerShell
+- [`pressKeys()`](/v7/press-keys) - Use Alt+Tab to switch windows
+- [`find()`](/v7/find) - Locate elements in the focused window

package/docs/v7/generating-tests.mdx

@@ -0,0 +1,36 @@
+---
+title: "Generating Tests"
+description: "Use AI coding agents and exploration mode to generate TestDriver tests"
+icon: "wand-magic-sparkles"
+---
+
+## Instructions for Coding Agents
+
+We recommend starting with [our quickstart](./quickstart) then supplying your coding agent with our agents.md file.
+
+<Card title="Agents.md" icon="link" arrow="true" horizontal href="https://github.com/testdriverai/testdriverai/blob/main/agents.md?plain=1">
+  Copy the current version of agents.md to provide your coding agent with up-to-date instructions on how to generate TestDriver tests.
+</Card>
+
+Then, you can prompt your coding agent to generate tests. Here is an example prompt:
+
+```md
+Make me a TestDriver test that does the following steps:
+
+Navigate to practicetestautomation.com
+Type username student into Username field
+Type password Password123 into Password field
+Push Submit button
+Verify new page contains expected text 'logged in'
+```
+
+## AI Exploration Mode
+
+Within a test, the `ai()` method lets TestDriver autonomously figure out how to accomplish a task. It's useful for dynamic or unpredictable UIs where explicit actions may be difficult to define.
+
+```javascript
+// Handle dynamic or unpredictable UI
+await testdriver.ai('dismiss any popups or modals that appear');
+```
+
+<Info>Explicit commands are preferred for production tests, as they are cheaper, faster, and more reliable.</Info>

package/docs/v7/{api/hover.mdx → hover.mdx}

@@ -274,6 +274,6 @@ describe('Hover Interactions', () => {
 
 ## Related Methods
 
-- [`find()`](/v7/api/find) - Locate elements to hover
-- [`click()`](/v7/api/click) - Click after hovering
-- [`mouseDown()`](/v7/api/click) - Start drag operations
+- [`find()`](/v7/find) - Locate elements to hover
+- [`click()`](/v7/click) - Click after hovering
+- [`mouseDown()`](/v7/click) - Start drag operations