testdriverai 7.11.264-test → 7.11.265-test

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

@@ -1,481 +0,0 @@
----
-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="false">
-      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="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="verify" type="boolean" default="false">
-      Global default for AI verification of located elements. When `true`, every `find()` runs a second AI check to confirm the returned coordinates actually match the requested element (catching hallucinated or incorrect positions), at the cost of extra latency. Can be overridden per call via `find(description, { verify: true | false })`.
-    </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>
-    
-    <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>
-  </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>