testdriverai 6.2.2 → 7.1.0

package/docs/v7/getting-started/configuration.mdx

@@ -0,0 +1,380 @@
+---
+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://testdriver-api.onrender.com
+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',
+  newSandbox: true,
+  sandboxId: null,
+  
+  // API Configuration
+  apiRoot: 'https://testdriver-api.onrender.com',
+  
+  // 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
+  headless: false,
+  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/src/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/getting-started/quickstart.mdx

@@ -0,0 +1,332 @@
+---
+title: "Quick Start"
+sidebarTitle: "Quickstart"
+description: "Get started with the TestDriver JavaScript SDK in 2 minutes."
+icon: "rocket"
+mode: "wide"
+---
+
+TestDriver v7 lets you write AI-powered tests in JavaScript/TypeScript with full IDE support, type safety, and automatic lifecycle management.
+
+<Steps>
+  <Step title="Install TestDriver">
+      
+    Install the TestDriver SDK and Vitest test runner:
+    
+    ```bash
+    npm install --save-dev testdriverai vitest
+    ```
+
+  </Step>
+  
+  <Step title="Write Your First Test">
+      
+    Create `test.test.js` and add your API key from [app.testdriver.ai](https://app.testdriver.ai):
+
+    <Tabs>
+      <Tab title="Fast">
+        ```javascript test.test.js
+        import { test } from 'vitest';
+        import { chrome } from 'testdriverai/presets';
+
+        test('my first test', async (context) => {
+          const { testdriver } = await chrome(context, {
+            url: 'https://example.com',
+            apiKey: 'tdai-1234567890abcdef' // Your API key from app.testdriver.ai
+          });
+          
+          await testdriver.find('More information link').click();
+          await testdriver.assert('IANA page is visible');
+        });
+        ```
+        
+        <Warning>
+          Don't commit API keys to version control!
+        </Warning>
+      </Tab>
+      
+      <Tab title="Secure with .env (Recommended)">
+        Create `.env`:
+        
+        ```bash .env
+        TD_API_KEY=tdai-1234567890abcdef
+        ```
+        
+        Then create `test.test.js`:
+        
+        ```javascript test.test.js
+        import { test } from 'vitest';
+        import { chrome } from 'testdriverai/presets';
+
+        test('my first test', async (context) => {
+          const { testdriver } = await chrome(context, {
+            url: 'https://example.com'
+            // apiKey automatically read from process.env.TD_API_KEY
+          });
+          
+          await testdriver.find('More information link').click();
+          await testdriver.assert('IANA page is visible');
+        });
+        ```
+        
+        <Tip>
+          Add `.env` to your `.gitignore` file!
+        </Tip>
+      </Tab>
+    </Tabs>
+
+  </Step>
+  
+  <Step title="Run Your Test">
+    
+    ```bash
+    npx vitest run
+    ```
+    
+    That's it! 🎉
+    
+    <Tip>
+      The `chrome()` preset automatically handles authentication, browser launch, and cleanup.
+    </Tip>
+
+  </Step>
+</Steps>
+
+## What Just Happened?
+
+The `chrome()` preset automatically:
+1. ✅ Connected to a TestDriver sandbox
+2. ✅ Launched Chrome browser
+3. ✅ Navigated to your URL
+4. ✅ Started recording with Dashcam
+5. ✅ Cleaned up everything when done
+
+No manual setup or teardown needed!
+
+## More Examples
+
+### Login Flow
+
+```javascript login.test.js
+import { test, expect } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('user can login', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://myapp.com/login'
+  });
+  
+  await testdriver.find('email input').type('user@example.com');
+  await testdriver.find('password input').type('password123');
+  await testdriver.find('Login button').click();
+  
+  const result = await testdriver.assert('Dashboard is visible');
+  expect(result).toBeTruthy();
+});
+```
+
+### VS Code Extension
+
+```javascript extension.test.js
+import { test } from 'vitest';
+import { vscode } from 'testdriverai/presets';
+
+test('create python file', async (context) => {
+  const { vscode } = await vscode(context, {
+    workspace: '/tmp/project',
+    extensions: ['ms-python.python']
+  });
+  
+  await vscode.pressKeys(['cmd', 'shift', 'p']);
+  await vscode.type('Python: Create New File');
+  await vscode.pressKeys(['enter']);
+  
+  await vscode.assert('Untitled Python file is open');
+});
+```
+
+### Electron App
+
+```javascript electron.test.js
+import { test } from 'vitest';
+import { electron } from 'testdriverai/presets';
+
+test('electron app menu', async (context) => {
+  const { app } = await electron(context, {
+    appPath: './dist/my-app'
+  });
+  
+  await app.find('File menu').click();
+  await app.find('New Document').click();
+  
+  await app.assert('New document window opens');
+});
+```
+
+## Three Levels of Control
+
+Choose your complexity level:
+
+<CardGroup cols={3}>
+  <Card title="Presets (Easiest)" icon="rocket" href="/v7/progressive-apis/PROVISION">
+    **One-line setup**
+    ```javascript
+    const { testdriver } = await chrome(context, { url });
+    ```
+  </Card>
+  
+  <Card title="Hooks (Flexible)" icon="link" href="/v7/progressive-apis/HOOKS">
+    **More control**
+    ```javascript
+    const client = useTestDriver(context);
+    const dashcam = useDashcam(context, client);
+    ```
+  </Card>
+  
+  <Card title="Core (Full Control)" icon="code" href="/v7/progressive-apis/CORE">
+    **Manual everything**
+    ```javascript
+    const client = new TestDriver(apiKey);
+    await client.connect();
+    ```
+  </Card>
+</CardGroup>
+
+## Video Replays
+
+Tests automatically record with Dashcam for easy debugging:
+
+```javascript
+test('with replay', async (context) => {
+  const { testdriver, dashcam } = await chrome(context, {
+    url: 'https://example.com'
+  });
+  
+  await testdriver.find('button').click();
+  
+  // After test, check the replay
+  console.log('Watch replay:', dashcam.url);
+});
+```
+
+View all replays at [app.testdriver.ai](https://app.testdriver.ai)
+
+## Optional Configuration
+
+For better developer experience, create `vitest.config.mjs`:
+
+```javascript vitest.config.mjs
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    testTimeout: 120000,  // 2 minutes per test
+    hookTimeout: 120000,  // 2 minutes for setup
+  },
+});
+```
+
+## Common Commands
+
+```bash
+# Run all tests
+npx vitest run
+
+# Run all tests in watch mode
+npx vitest
+
+# Run specific file
+npx vitest run login.test.js
+
+# Run in watch mode
+npx vitest --watch
+
+# Run tests matching pattern
+npx vitest run --grep "login"
+```
+
+## Troubleshooting
+
+### Test times out
+
+Increase the timeout in your config:
+
+```javascript vitest.config.mjs
+export default defineConfig({
+  test: {
+    testTimeout: 180000, // 3 minutes
+  },
+});
+```
+
+### API key not found
+
+Either pass it directly to the preset:
+
+```javascript
+const { testdriver } = await chrome(context, {
+  url: 'https://example.com',
+  apiKey: 'tdai-your-api-key-here'
+});
+```
+
+Or create a `.env` file in your project root:
+
+```bash .env
+TD_API_KEY=tdai-your-api-key-here
+```
+
+### Import errors
+
+Make sure you installed testdriverai:
+
+```bash
+npm install --save-dev testdriverai
+```
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card
+    title="Complete Vitest Guide"
+    icon="flask-vial"
+    href="/v7/guides/vitest"
+  >
+    Everything about TestDriver + Vitest integration
+  </Card>
+  
+  <Card
+    title="All Presets"
+    icon="rocket"
+    href="/v7/progressive-apis/PROVISION"
+  >
+    Chrome, VS Code, Electron, and more
+  </Card>
+  
+  <Card
+    title="API Reference"
+    icon="book"
+    href="/v7/api/client"
+  >
+    All available methods and options
+  </Card>
+  
+  <Card
+    title="Progressive APIs"
+    icon="gauge-high"
+    href="/v7/progressive-apis/PROGRESSIVE_DISCLOSURE"
+  >
+    Choose your complexity level
+  </Card>
+</CardGroup>
+
+## Why TestDriver v7?
+
+The v7 SDK offers advantages over YAML-based testing:
+
+- ✅ **Type Safety** - Full TypeScript support with IntelliSense
+- ✅ **Programmatic Control** - Use variables, loops, and functions
+- ✅ **Better Debugging** - Stack traces point to your actual code
+- ✅ **Automatic Lifecycle** - Presets handle setup and cleanup
+- ✅ **Framework Integration** - Works with Vitest, Jest, Mocha, etc.
+- ✅ **Video Replays** - Automatic Dashcam recording included