testdriverai 7.2.3 → 7.2.10

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/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/enterprise.mdx

@@ -0,0 +1,135 @@
+---
+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>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card
+    title="Cloud"
+    icon="cloud"
+    href="/v7/cloud"
+  >
+    Zero-setup testing with device-seconds billing
+  </Card>
+  <Card
+    title="Self-Hosted"
+    icon="server"
+    href="/v7/self-hosted"
+  >
+    Flat-rate licensing with your AWS infrastructure
+  </Card>
+</CardGroup>

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,32 @@
+---
+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](https://github.com/testdriverai/testdriverai/agents.md) file.
+
+Then, you can prompt your coding agent to generate tests:
+
+```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

package/docs/v7/locating-elements.mdx

@@ -0,0 +1,71 @@
+---
+title: "Locating Elements"
+description: "Find UI elements using natural language descriptions"
+icon: "crosshairs"
+---
+
+## Locating Single Elements
+
+Use natural language to describe elements. Descriptions should be specific enough to locate the element, but not too-specific that they break with minor UI changes. For example:
+
+```javascript
+await testdriver.find('email input field');
+await testdriver.find('first product card in the grid');
+await testdriver.find('dropdown menu labeled "Country"');
+```
+
+<Info>TestDriver will cache found elements for improved performance on subsequent calls. Learn more about [element caching here](/v7/caching).</Info>
+
+## Debugging Found Elements
+
+After finding an element, you can inspect its properties for debugging:
+
+```javascript
+const button = await testdriver.find('submit button');
+console.log(button);
+```
+
+This outputs all element properties:
+
+```javascript
+{
+  description: 'submit button',
+  found: true,
+  x: 150,
+  y: 300,
+  coordinates: { x: 150, y: 300, centerX: 200, centerY: 320 },
+  threshold: 0.8,
+  confidence: 0.95,
+  similarity: 0.92,
+  selector: 'button[type="submit"]',
+  cache: {
+    hit: true,
+    strategy: 'pixel-diff',
+    createdAt: '2025-01-15T10:30:00Z',
+    diffPercent: 0.02,
+    imageUrl: 'https://...'
+  }
+}
+```
+
+## Working with Multiple Elements
+
+Find and interact with multiple elements:
+
+```javascript
+// Find all matching elements
+const products = await testdriver.findAll('product card');
+console.log(`Found ${products.length} products`);
+
+// Interact with each
+for (const product of products) {
+  const title = await product.find('title text');
+  console.log('Product:', title.text);
+
+  await product.find('add to cart button').click();
+}
+
+// Or find specific element
+const firstProduct = products[0];
+await firstProduct.click();
+```

package/docs/v7/making-assertions.mdx

@@ -0,0 +1,32 @@
+---
+title: "Making Assertions"
+description: "Verify application state with AI-powered assertions"
+icon: "check-double"
+---
+
+## Making Assertions
+
+Use AI-powered assertions to verify application state:
+
+```javascript
+// Verify visibility
+await testdriver.assert('login page is displayed');
+await testdriver.assert('submit button is visible');
+await testdriver.assert('loading spinner is not visible');
+
+// Verify content
+await testdriver.assert('page title is "Welcome"');
+await testdriver.assert('success message says "Account created"');
+await testdriver.assert('error message contains "Invalid email"');
+
+// Verify state
+await testdriver.assert('checkbox is checked');
+await testdriver.assert('dropdown shows "United States"');
+await testdriver.assert('button is disabled');
+
+// Verify visual appearance
+await testdriver.assert('submit button is blue');
+await testdriver.assert('form has red border');
+```
+
+<Info>Assertions are not cached and always re-evaluated to ensure accuracy.</Info>

package/docs/v7/{api/mouseDown.mdx → mouse-down.mdx}

@@ -147,15 +147,15 @@ test('resizes panel', async () => {
 
 ## Important Notes
 
-- Always pair `mouseDown()` with [`mouseUp()`](/v7/api/mouseUp) to complete the gesture
+- Always pair `mouseDown()` with [`mouseUp()`](/v7/mouse-up) to complete the gesture
 - The mouse button remains pressed until `mouseUp()` is called
-- Use [`hover()`](/v7/api/hover) to move the mouse while the button is pressed
+- Use [`hover()`](/v7/hover) to move the mouse while the button is pressed
 - For simple drag operations, consider using `ai()` with a natural language description like `"drag file to folder"`
 
 ## Related Methods
 
-- [`mouseUp()`](/v7/api/mouseUp) - Release the mouse button
-- [`hover()`](/v7/api/hover) - Move mouse to element
-- [`click()`](/v7/api/click) - Full click (mouseDown + mouseUp)
-- [`doubleClick()`](/v7/api/doubleClick) - Double-click on element
-- [`rightClick()`](/v7/api/rightClick) - Right-click for context menu
+- [`mouseUp()`](/v7/mouse-up) - Release the mouse button
+- [`hover()`](/v7/hover) - Move mouse to element
+- [`click()`](/v7/click) - Full click (mouseDown + mouseUp)
+- [`doubleClick()`](/v7/double-click) - Double-click on element
+- [`rightClick()`](/v7/right-click) - Right-click for context menu