@testdriverai/agent 7.8.0-canary.10

package/docs/v7/_drafts/configuration.mdx

@@ -0,0 +1,378 @@
+---
+title: "Options"
+description: "Configure TestDriver SDK for your testing environment"
+icon: "gear"
+---
+
+## Overview
+
+TestDriver can be configured through constructor options, environment variables, and Vitest configuration.
+
+## Environment Variables
+
+Set these in your `.env` file:
+
+```bash
+# Required
+TD_API_KEY=your_api_key_here
+
+# Optional
+TD_API_ROOT=https://api.testdriver.ai
+TD_DEFAULT_OS=linux
+TD_DEFAULT_RESOLUTION=1920x1080
+TD_NO_PROMPT_CACHE=false
+TD_NO_SELECTOR_CACHE=false
+```
+
+## Client Configuration
+
+### Basic Options
+
+```javascript
+import TestDriver from 'testdriverai';
+
+const client = await TestDriver.create({
+  apiKey: process.env.TD_API_KEY,
+  os: 'linux',              // 'linux' | 'windows' | 'mac'
+  resolution: '1920x1080',  // Any standard resolution
+  verbosity: 1,             // 0 (silent) | 1 (normal) | 2 (debug)
+});
+```
+
+### All Options
+
+```javascript
+const client = await TestDriver.create({
+  // Authentication
+  apiKey: process.env.TD_API_KEY,
+  
+  // Sandbox Configuration
+  os: 'linux',
+  resolution: '1920x1080',
+  sandboxId: null,
+  
+  // API Configuration
+  apiRoot: 'https://api.testdriver.ai',
+  
+  // Logging
+  verbosity: 1,
+  logging: true,
+  
+  // Analytics
+  analytics: true,
+  
+  // Cache Configuration
+  cacheDefaults: {
+    threshold: 0.05,  // 95% similarity
+    enabled: true
+  }
+});
+```
+
+## Vitest Configuration
+
+Create or update `vitest.config.mjs`:
+
+```javascript
+import { defineConfig } from 'vitest/config';
+import testDriverPlugin from 'testdriverai/interfaces/vitest-plugin.mjs';
+import { config } from 'dotenv';
+
+config(); // Load .env file
+
+export default defineConfig({
+  plugins: [
+    testDriverPlugin({
+      apiKey: process.env.TD_API_KEY,
+      apiRoot: process.env.TD_API_ROOT,
+    }),
+  ],
+  
+  test: {
+    // Test file patterns
+    include: ['**/*.test.{js,mjs,ts}'],
+    
+    // Timeout settings
+    testTimeout: 300000,      // 5 minutes per test
+    hookTimeout: 300000,      // 5 minutes for setup/teardown
+    teardownTimeout: 120000,  // 2 minutes for teardown
+    
+    // Parallel execution
+    pool: 'forks',
+    poolOptions: {
+      forks: {
+        singleFork: false,
+        maxForks: 5,
+        minForks: 1,
+      },
+    },
+    
+    // Enable parallel execution
+    sequence: {
+      concurrent: true,
+      shuffle: false,
+    },
+    
+    fileParallelism: true,
+    maxConcurrency: 5,
+    
+    // Reporters
+    reporters: ['verbose'],
+  },
+});
+```
+
+## Preset Configuration
+
+### Chrome Preset
+
+```javascript
+import { chrome } from 'testdriverai/presets';
+
+const { testdriver, dashcam } = await chrome(context, {
+  url: 'https://example.com',
+  dashcam: true,
+  os: 'linux',
+  resolution: '1920x1080',
+  
+  // Chrome-specific options
+  incognito: false,
+});
+```
+
+### VS Code Preset
+
+```javascript
+import { vscode } from 'testdriverai/presets';
+
+const { testdriver, dashcam } = await vscode(context, {
+  workspace: '/path/to/workspace',
+  extensions: ['ms-python.python'],
+  settings: {
+    'editor.fontSize': 14
+  },
+  dashcam: true,
+});
+```
+
+### Electron Preset
+
+```javascript
+import { electron } from 'testdriverai/presets';
+
+const { testdriver, dashcam } = await electron(context, {
+  appPath: './dist/my-app',
+  args: ['--enable-logging'],
+  dashcam: true,
+});
+```
+
+## Operating System Settings
+
+### Linux
+
+```javascript
+{
+  os: 'linux',
+  resolution: '1920x1080',
+  // Linux-specific environment
+  environment: {
+    DISPLAY: ':0',
+    HOME: '/home/user'
+  }
+}
+```
+
+### Windows
+
+```javascript
+{
+  os: 'windows',
+  resolution: '1366x768',
+  // Windows-specific paths use backslashes
+}
+```
+
+### macOS
+
+```javascript
+{
+  os: 'mac',
+  resolution: '1920x1080',
+  // macOS-specific settings
+}
+```
+
+## Cache Configuration
+
+### Prompt Cache
+
+Configure AI prompt caching:
+
+```javascript
+// Disable prompt cache globally
+process.env.TD_NO_PROMPT_CACHE = 'true';
+
+// Per call
+await testdriver.ai('click button', false); // bypass cache
+```
+
+### Selector Cache
+
+Configure element location caching:
+
+```javascript
+// Disable selector cache globally
+process.env.TD_NO_SELECTOR_CACHE = 'true';
+
+// Per call with custom threshold
+await testdriver.find('button', { threshold: 0.01 }); // 99% similarity
+await testdriver.find('button', { threshold: 0.10 }); // 90% similarity
+await testdriver.find('button', { threshold: -1 });   // disable cache
+```
+
+## Dashcam Configuration
+
+```javascript
+import Dashcam from 'testdriverai/lib/core/Dashcam.js';
+
+const dashcam = new Dashcam(client, {
+  apiKey: process.env.TD_API_KEY,
+  autoStart: false,
+  logs: [
+    {
+      name: 'Application Log',
+      type: 'file',
+      path: '/tmp/app.log'
+    }
+  ]
+});
+```
+
+## Timeout Configuration
+
+### Test Timeouts
+
+```javascript
+// In vitest.config.mjs
+export default defineConfig({
+  test: {
+    testTimeout: 600000,  // 10 minutes
+    hookTimeout: 600000,  // 10 minutes
+  }
+});
+```
+
+### Command Timeouts
+
+```javascript
+// exec() timeout
+await client.exec('sh', 'long-running-command', 120000); // 2 minutes
+
+// Find timeout (polling)
+for (let i = 0; i < 60; i++) {
+  const element = await client.find('button');
+  if (element.found()) break;
+  await new Promise(r => setTimeout(r, 1000));
+}
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Use environment variables for secrets">
+    ```javascript
+    // ✅ Good
+    apiKey: process.env.TD_API_KEY
+    
+    // ❌ Bad
+    apiKey: 'td_1234567890abcdef'
+    ```
+  </Accordion>
+  
+  <Accordion title="Set appropriate timeouts">
+    ```javascript
+    // For slow operations
+    testTimeout: 600000,  // 10 minutes
+    
+    // For fast operations
+    testTimeout: 60000,   // 1 minute
+    ```
+  </Accordion>
+  
+  <Accordion title="Configure caching for your needs">
+    ```javascript
+    // Strict caching for stable UIs
+    threshold: 0.01  // 99% similarity
+    
+    // Lenient caching for dynamic UIs
+    threshold: 0.10  // 90% similarity
+    ```
+  </Accordion>
+  
+  <Accordion title="Use appropriate concurrency">
+    ```javascript
+    // High-end machine
+    maxConcurrency: 10
+    
+    // Low-end machine or resource-intensive tests
+    maxConcurrency: 2
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Example Configurations
+
+### CI/CD Configuration
+
+```javascript
+export default defineConfig({
+  test: {
+    testTimeout: 300000,
+    maxConcurrency: 3,  // Lower for CI
+    reporters: ['junit', 'json'],
+  },
+});
+```
+
+### Local Development
+
+```javascript
+export default defineConfig({
+  test: {
+    testTimeout: 600000,
+    maxConcurrency: 5,
+    reporters: ['verbose'],
+  },
+});
+```
+
+### Debug Mode
+
+```javascript
+const client = await TestDriver.create({
+  apiKey: process.env.TD_API_KEY,
+  verbosity: 2,  // Debug logging
+  logging: true,
+});
+```
+
+## See Also
+
+<CardGroup cols={2}>
+  <Card title="Installation" icon="download" href="/v7/getting-started/installation">
+    Install TestDriver SDK
+  </Card>
+  
+  <Card title="Quick Start" icon="rocket" href="/v7/getting-started/quickstart">
+    Build your first test
+  </Card>
+  
+  <Card title="Caching" icon="bolt" href="/v7/guides/caching-ai">
+    Configure caching
+  </Card>
+  
+  <Card title="Client API" icon="plug" href="/v7/api/client">
+    Full client reference
+  </Card>
+</CardGroup>

package/docs/v7/_drafts/contributing.mdx

@@ -0,0 +1,174 @@
+# Contributing
+
+## Setup `testdriverai` repo
+
+1. `gh repo clone testdriverai/testdriverai`
+1. `npm install` project dependencies
+1. `npm link`
+
+## Setting up a Test Project
+
+1. `cd $(mktemp -d)` to create a blank project
+1. `npm link testdriverai`
+1. `npx testdriverai init`
+
+   > Spawning GUI...
+   > Howdy! I'm TestDriver v4.2.29
+   > Working on **/private/var/folders/4w/\_l20wtfj41n2dx0xyhb8xd740000gn/T/tmp.PDxTlOLJBS/testdriver/testdriver.yml**
+   > ...
+
+1. `npx testdriverai testdriver/test.yml`
+
+## Architecture Diagram
+
+```mermaid
+graph TD
+    A[CLI Entry: npx testdriverai run test.yaml --heal --write] --> B[index.js]
+    B --> C{Check Args}
+    C -->|--renderer| D[Overlay Mode]
+    C -->|Other| E[agent.js]
+
+    E --> F[Parse Arguments]
+    F --> G[Load Configuration]
+    G --> H[Initialize SDK]
+    H --> I[Load YAML File]
+
+    I --> J{Command Type}
+    J -->|run| K[Execute Commands]
+    J -->|edit| L[Interactive Mode]
+    J -->|init| M[Setup Project]
+
+    K --> N[Parse YAML Commands]
+    N --> O[Execute Each Command]
+    O --> P[commands.js]
+
+    P --> Q{Command Type}
+    Q -->|hover-text| R[AI Vision API]
+    Q -->|type| S[Keyboard Input]
+    Q -->|click| T[Mouse Control]
+    Q -->|assert| U[Validation]
+    Q -->|exec| V[System Commands]
+
+    R --> W[Capture Screen]
+    W --> X[Send to Backend]
+    X --> Y[Get Coordinates]
+    Y --> Z[Execute Action]
+
+    L --> AA[Read User Input]
+    AA --> BB[Generate AI Response]
+    BB --> CC[Parse Markdown]
+    CC --> DD[Extract YAML]
+    DD --> EE[Add to File]
+
+    M --> FF[Create .env]
+    FF --> GG[Setup GitHub Actions]
+    GG --> HH[Download Workflows]
+
+    subgraph "Key Files"
+        II[index.js - Entry Point]
+        JJ[agent.js - Main Logic]
+        KK[lib/commands.js - Command Execution]
+        LL[lib/parser.js - YAML Parsing]
+        MM[lib/sdk.js - API Communication]
+        NN[lib/config.js - Configuration]
+        OO[lib/generator.js - YAML Generation]
+    end
+```
+
+## Network Diagram
+
+```mermaid
+sequenceDiagram
+    participant CLI as testdriverai CLI
+    participant Config as Config Manager
+    participant SDK as SDK Module
+    participant API as TestDriver API
+    participant Sandbox as VM Sandbox
+    participant YAML as YAML File
+
+    Note over CLI, YAML: Authentication Flow
+    CLI->>Config: Load TD_API_KEY from .env
+    Config->>SDK: Initialize with API key
+    SDK->>API: POST /auth/exchange-api-key
+    API->>SDK: Return Bearer Token
+    SDK->>SDK: Store token for future requests
+
+    Note over CLI, YAML: Session Management
+    CLI->>SDK: Start new session
+    SDK->>API: POST /api/v5/testdriver/session/start
+    API->>SDK: Return session ID
+    SDK->>YAML: Update session ID in file
+
+    Note over CLI, YAML: Command Execution Flow
+    CLI->>YAML: Load test commands
+    YAML->>CLI: Return parsed YAML
+
+    loop For each command
+        CLI->>SDK: Execute command (e.g., hover-text)
+        SDK->>CLI: Capture screen
+        CLI->>SDK: Send screenshot + prompt
+        SDK->>API: POST /api/v5/testdriver/hover/text
+        API->>SDK: Return coordinates + confidence
+        SDK->>CLI: Execute action (click, type, etc.)
+    end
+
+    Note over CLI, YAML: AI-Powered Command Generation
+    CLI->>CLI: User enters natural language prompt
+    CLI->>SDK: Send prompt + screenshot
+    SDK->>API: POST /api/v5/testdriver/generate
+    API->>SDK: Return markdown with YAML codeblocks
+    SDK->>CLI: Parse markdown response
+    CLI->>YAML: Extract and add new commands
+
+    Note over CLI, YAML: Sandbox Mode (Optional)
+    CLI->>Config: Check TD_VM setting
+    Config->>Sandbox: Initialize WebSocket connection
+    Sandbox->>API: WSS connection to api.testdriver.ai
+    API->>Sandbox: Authenticate with API key
+    Sandbox->>API: Create VM instance
+    API->>Sandbox: Return VM URL
+    Sandbox->>CLI: Stream VM display
+
+    Note over CLI, YAML: File Operations
+    CLI->>YAML: Save updated commands
+    YAML->>CLI: Write to testdriver/test.yaml
+    CLI->>CLI: Update version and session info
+
+    Note over CLI, YAML: Error Handling & Healing
+    CLI->>CLI: Command fails
+    CLI->>SDK: Send error + context
+    SDK->>API: POST error details
+    API->>SDK: Return suggested fix
+    SDK->>CLI: Apply auto-healing
+    CLI->>YAML: Update commands if needed
+```
+
+## Testing against local `api`
+
+When running [replayableio/api](https://github.com/replayableio/api/) locally, specify `TD_API_ROOT` in your `.env` file or shell:
+
+```sh
+TD_API_ROOT=http://localhost:1337 npx testdriverai
+```
+
+## Logging
+
+- `DEV` to log the config
+- `VERBOSE` to log `logger.debug` (Default: `logger.info` and above)
+
+```sh
+DEV=true VERBOSE=true npx testdriverai
+```
+
+## Debugging with Chrome Node Inspector
+
+> https://nodejs.org/en/learn/getting-started/debugging
+
+```sh
+npx --node-options=--inspect testdriverai init
+```
+
+## Event Principles
+
+- Events represent changes to the state of the system
+- Execution is functional and should not be mutated by events