@testdriverai/agent 7.8.0-canary.10

package/ai/skills/testdriver-client/SKILL.md

@@ -0,0 +1,477 @@
+---
+name: testdriver:client
+description: Initialize and configure the TestDriver SDK client
+---
+<!-- Generated from client.mdx. DO NOT EDIT. -->
+
+## Overview
+
+The `TestDriver` client is the main entry point for the SDK. It handles authentication, sandbox connection, and provides access to all testing methods.
+
+## Constructor
+
+```javascript
+const testdriver = new TestDriver(apiKey, options)
+```
+
+### Parameters
+
+<ParamField path="apiKey" type="string" required>
+  Your TestDriver API key from the [dashboard](https://console.testdriver.ai/team)
+</ParamField>
+
+<ParamField path="options" type="object">
+  Configuration options for the client
+  
+  <Expandable title="properties">
+    <ParamField path="os" type="string" default="linux">
+      Operating system for the sandbox: `'windows'` or `'linux'`
+    </ParamField>
+    
+    <ParamField path="resolution" type="string" default="1366x768">
+      Screen resolution for the sandbox (e.g., `'1920x1080'`, `'1366x768'`)
+    </ParamField>
+    
+    <ParamField path="apiRoot" type="string">
+      API endpoint URL (typically only changed for self-hosted deployments)
+    </ParamField>
+    
+    <ParamField path="analytics" type="boolean" default="true">
+      Enable or disable usage analytics
+    </ParamField>
+    
+    <ParamField path="logging" type="boolean" default="true">
+      Enable or disable console logging
+    </ParamField>
+    
+    <ParamField path="autoScreenshots" type="boolean" default="true">
+      Automatically capture screenshots before and after each command. Screenshots are saved to `.testdriver/screenshots/<test>/` with descriptive filenames that include the line number and action name. Format: `<seq>-<action>-<phase>-L<line>-<description>.png`
+    </ParamField>
+    
+    <ParamField path="newSandbox" type="boolean" default="true">
+      Force creation of a new sandbox instead of reusing an existing one
+    </ParamField>
+    
+    <ParamField path="reconnect" type="boolean" default="false">
+      Reconnect to the last used sandbox instead of creating a new one. When `true`, provision methods (`chrome`, `vscode`, `installer`, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists.
+    </ParamField>
+    
+    <ParamField path="keepAlive" type="number" default="60000">
+      Keep sandbox alive for the specified number of milliseconds after disconnect. Set to `0` to terminate immediately on disconnect. Useful for debugging or reconnecting to the same sandbox.
+    </ParamField>
+    
+    <ParamField path="preview" type="string" default="browser">
+      Preview mode for live test visualization:
+      - `"browser"` — Opens debugger in default browser (default)
+      - `"ide"` — Opens preview in IDE panel (VSCode, Cursor - requires TestDriver extension)
+      - `"none"` — Headless mode, no visual preview
+    </ParamField>
+    
+    <ParamField path="headless" type="boolean" default="false">
+      **Deprecated**: Use `preview: "none"` instead. Run in headless mode without opening the debugger.
+    </ParamField>
+    
+    <ParamField path="debugOnFailure" type="boolean" default="false">
+      Keep the sandbox alive when a test fails so you can reconnect and debug interactively. The sandbox ID is printed to the console.
+    </ParamField>
+    
+    <ParamField path="ip" type="string">
+      Direct IP address to connect to a running sandbox instance (for self-hosted deployments)
+    </ParamField>
+    
+    <ParamField path="sandboxAmi" type="string">
+      Custom AMI ID for the sandbox instance (AWS deployments, e.g., `'ami-1234'`)
+    </ParamField>
+    
+    <ParamField path="sandboxInstance" type="string">
+      EC2 instance type for the sandbox (AWS deployments, e.g., `'i3.metal'`)
+    </ParamField>
+    
+    <ParamField path="cache" type="boolean | object" default="true">
+      Enable or disable element caching, or provide advanced threshold configuration.
+      
+      <Expandable title="advanced config">
+        <ParamField path="enabled" type="boolean" default="true">
+          Enable or disable caching
+        </ParamField>
+        
+        <ParamField path="thresholds" type="object">
+          Fine-tune cache matching
+          
+          <Expandable title="properties">
+            <ParamField path="find" type="object">
+              Thresholds for `find()` operations
+              
+              <Expandable title="properties">
+                <ParamField path="screen" type="number" default="0.05">
+                  Pixel diff threshold for screen comparison (0-1). `0.05` = 5% diff allowed.
+                </ParamField>
+                
+                <ParamField path="element" type="number" default="0.8">
+                  OpenCV template match threshold for element matching (0-1). `0.8` = 80% correlation.
+                </ParamField>
+              </Expandable>
+            </ParamField>
+            
+            <ParamField path="assert" type="number" default="0.05">
+              Pixel diff threshold for `assert()` operations (0-1). `0.05` = 5% diff allowed.
+            </ParamField>
+          </Expandable>
+        </ParamField>
+      </Expandable>
+    </ParamField>
+    
+    <ParamField path="cacheKey" type="string">
+      Cache key for element finding operations. If provided, enables caching tied to this key.
+    </ParamField>
+    
+    <ParamField path="dashcam" type="boolean" default="true">
+      Enable or disable Dashcam video recording
+    </ParamField>
+    
+    <ParamField path="redraw" type="boolean | object" default="true">
+      Enable or disable screen-change (redraw) detection, or provide advanced configuration.
+      
+      <Expandable title="advanced config">
+        <ParamField path="enabled" type="boolean" default="true">
+          Enable or disable redraw detection
+        </ParamField>
+        
+        <ParamField path="thresholds" type="object">
+          Threshold configuration
+          
+          <Expandable title="properties">
+            <ParamField path="screen" type="number | false" default="0.05">
+              Pixel diff threshold (0-1). Set to `false` to disable screen redraw detection.
+            </ParamField>
+            
+            <ParamField path="network" type="boolean" default="false">
+              Enable or disable network activity monitoring
+            </ParamField>
+          </Expandable>
+        </ParamField>
+      </Expandable>
+    </ParamField>
+    
+    <ParamField path="environment" type="object">
+      Additional environment variables to pass to the sandbox
+    </ParamField>
+    
+    <ParamField path="ai" type="object">
+      Global AI sampling configuration. Controls how the AI model generates responses for `find()` verification and `assert()` calls. Can be overridden per call.
+      
+      <Expandable title="properties">
+        <ParamField path="temperature" type="number">
+          Controls randomness in AI responses. `0` = deterministic (best for verification), higher values = more creative. Default: `0` for find verification, model default for assert.
+        </ParamField>
+        
+        <ParamField path="top" type="object">
+          Nucleus and top-k sampling parameters
+          
+          <Expandable title="properties">
+            <ParamField path="p" type="number">
+              Top-P (nucleus sampling). Limits token choices to the smallest set whose cumulative probability exceeds P. Lower values = more focused responses. Range: 0-1.
+            </ParamField>
+            
+            <ParamField path="k" type="number">
+              Top-K sampling. Limits token choices to the top K most likely tokens. `1` = always pick the most likely token. `0` = disabled (consider all tokens).
+            </ParamField>
+          </Expandable>
+        </ParamField>
+      </Expandable>
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+### Example
+
+```javascript
+import TestDriver from 'testdriverai';
+
+// API key is automatically loaded from TD_API_KEY in .env
+const testdriver = new TestDriver({
+  os: 'windows',
+  resolution: '1920x1080',
+  logging: true,
+  analytics: true
+});
+
+// With AI config for stricter verification
+const testdriver = new TestDriver({
+  ai: { temperature: 0, top: { p: 0.9, k: 40 } }
+});
+
+// Or pass API key explicitly
+const testdriver = new TestDriver('your-api-key', {
+  os: 'windows'
+});
+```
+
+## Authentication
+
+### auth()
+
+Authenticate with the TestDriver API.
+
+```javascript
+await testdriver.auth()
+```
+
+**Returns:** `Promise<string>` - Authentication token
+
+**Example:**
+```javascript
+await testdriver.auth();
+```
+
+<Note>
+  You must call `auth()` before `connect()`. Most examples call both sequentially.
+</Note>
+
+## Connection Management
+
+### connect()
+
+Connect to a sandbox environment. This creates or reconnects to a virtual machine where your tests will run.
+
+```javascript
+await testdriver.connect(options)
+```
+
+#### Parameters
+
+<ParamField path="options" type="object">
+  Connection options
+  
+  <Expandable title="properties">
+    <ParamField path="newSandbox" type="boolean" default="false">
+      Force creation of a new sandbox instead of reusing an existing one
+    </ParamField>
+    
+    <ParamField path="sandboxId" type="string">
+      Existing sandbox ID to reconnect to
+    </ParamField>
+    
+    <ParamField path="ip" type="string">
+      Direct IP address to connect to (for self-hosted sandboxes)
+    </ParamField>
+    
+    <ParamField path="sandboxAmi" type="string">
+      AMI to use for the sandbox (AWS deployments)
+    </ParamField>
+    
+    <ParamField path="sandboxInstance" type="string">
+      Instance type for the sandbox (AWS deployments)
+    </ParamField>
+    
+    <ParamField path="preview" type="string" default="browser">
+      Preview mode for live test visualization:
+      - `"browser"` - Opens debugger in default browser (default)
+      - `"ide"` - Opens preview in IDE panel (VSCode, Cursor - requires TestDriver extension)
+      - `"none"` - Headless mode, no visual preview
+    </ParamField>
+    
+    <ParamField path="headless" type="boolean" default="false">
+      **Deprecated**: Use `preview: "none"` instead. Run in headless mode without opening the debugger.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+**Returns:** `Promise&lt;Object&gt;` - Sandbox instance details including `instanceId`, `ip`, `vncPort`, etc.
+
+#### Examples
+
+**Basic connection:**
+```javascript
+await testdriver.connect();
+```
+
+**Reconnect to existing sandbox:**
+```javascript
+const instance = await testdriver.connect({ 
+  sandboxId: 'existing-sandbox-id-123' 
+});
+```
+
+**Self-hosted sandbox:**
+```javascript
+await testdriver.connect({ 
+  ip: '192.168.1.100'
+});
+```
+
+### disconnect()
+
+Disconnect from the sandbox and clean up resources.
+
+```javascript
+await testdriver.disconnect()
+```
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```javascript
+afterAll(async () => {
+  await testdriver.disconnect();
+});
+```
+
+## Instance Information
+
+### getInstance()
+
+Get the current sandbox instance details.
+
+```javascript
+const instance = testdriver.getInstance()
+```
+
+**Returns:** `Object | null` - Sandbox instance information
+
+**Example:**
+```javascript
+const instance = testdriver.getInstance();
+console.log('Instance ID:', instance.instanceId);
+console.log('IP Address:', instance.ip);
+```
+
+### getSessionId()
+
+Get the current session ID for tracking and debugging.
+
+```javascript
+const sessionId = testdriver.getSessionId()
+```
+
+**Returns:** `string | null` - Session ID
+
+**Example:**
+```javascript
+const sessionId = testdriver.getSessionId();
+console.log('Session:', sessionId);
+```
+
+## Logging & Events
+
+### setLogging()
+
+Enable or disable console logging at runtime.
+
+```javascript
+testdriver.setLogging(enabled)
+```
+
+**Parameters:**
+- `enabled` (boolean) - Whether to enable logging
+
+**Example:**
+```javascript
+// Disable logging for cleanup operations
+testdriver.setLogging(false);
+await testdriver.disconnect();
+testdriver.setLogging(true);
+```
+
+### getEmitter()
+
+Get the event emitter for custom event handling.
+
+```javascript
+const emitter = testdriver.getEmitter()
+```
+
+**Returns:** `EventEmitter2` - Event emitter instance
+
+**Example:**
+```javascript
+const emitter = testdriver.getEmitter();
+
+emitter.on('command:start', (data) => {
+  console.log('Command started:', data);
+});
+
+emitter.on('command:success', (data) => {
+  console.log('Command succeeded:', data);
+});
+
+emitter.on('command:error', (error) => {
+  console.error('Command failed:', error);
+});
+```
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('My Test Suite', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    // Initialize client - API key loaded automatically from .env
+    testdriver = new TestDriver({
+      os: 'windows',
+      resolution: '1366x768',
+      logging: true
+    });
+    
+    // Set up event listeners
+    const emitter = testdriver.getEmitter();
+    emitter.on('log:info', (msg) => console.log('[INFO]', msg));
+    
+    // Authenticate and connect
+    await testdriver.auth();
+    const instance = await testdriver.connect();
+    
+    console.log('Connected to sandbox:', instance.instanceId);
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('runs a test', async () => {
+    // Your test code here
+  });
+});
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Reuse sandboxes across tests">
+    Use `beforeAll`/`afterAll` to create one sandbox per test suite rather than per test. This significantly reduces execution time.
+  </Accordion>
+  
+  <Accordion title="Handle connection errors gracefully">
+    Wrap `connect()` in a try-catch block to handle network issues or quota limits:
+    
+    ```javascript
+    try {
+      await testdriver.connect();
+    } catch (error) {
+      console.error('Failed to connect:', error.message);
+      throw error;
+    }
+    ```
+  </Accordion>
+  
+  <Accordion title="Always disconnect">
+    Use `afterAll` or try-finally blocks to ensure `disconnect()` is called even if tests fail. This prevents orphaned sandboxes.
+  </Accordion>
+  
+  <Accordion title="Use environment variables for API keys">
+    Never hardcode API keys. The SDK automatically loads `TD_API_KEY` from your `.env` file:
+    
+    ```bash .env
+    TD_API_KEY=your_api_key_here
+    ```
+    
+    ```javascript
+    // API key is loaded automatically - no need to pass it!
+    const testdriver = new TestDriver();
+    ```
+  </Accordion>
+</AccordionGroup>

package/ai/skills/testdriver-cloud/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: testdriver:cloud
+description: The fastest way to get started with TestDriver. Just set your API key and start testing.
+---
+<!-- Generated from cloud.mdx. DO NOT EDIT. -->
+
+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: 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>