testdriverai 7.0.0 → 7.1.1

package/docs/v7/_drafts/vitest.mdx

@@ -0,0 +1,535 @@
+---
+title: "Using TestDriver with Vitest"
+sidebarTitle: "Vitest Integration"
+description: "Complete guide to integrating TestDriver with Vitest"
+icon: "flask-vial"
+---
+
+## Overview
+
+TestDriver integrates seamlessly with Vitest, providing three levels of API complexity to match your needs. From simple preset functions to full manual control, choose the approach that works best for your project.
+
+## Quick Start
+
+### 1. Install TestDriver
+
+```bash
+npm install --save-dev testdriverai
+```
+
+### 2. Create Vitest Config
+
+```javascript vitest.config.mjs
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    // Optional: Configure test timeout
+    testTimeout: 120000,
+    hookTimeout: 120000,
+  },
+});
+```
+
+### 3. Write Your First Test
+
+```javascript example.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'
+  });
+  
+  await testdriver.find('More information link').click();
+  await testdriver.assert('IANA information page is visible');
+});
+```
+
+### 4. Run Your Tests
+
+```bash
+npx vitest
+```
+
+That's it! TestDriver automatically handles all setup and teardown.
+
+## Three Levels of Integration
+
+<CardGroup cols={3}>
+  <Card title="Provision API" icon="rocket" href="/v7/progressive-apis/PROVISION">
+    **Easiest** - One-line setup
+    ```javascript
+    const { testdriver } = await provision('chrome', { url }, context);
+    ```
+  </Card>
+  
+  <Card title="Hooks API" icon="link" href="/v7/progressive-apis/HOOKS">
+    **Flexible** - More control
+    ```javascript
+    const client = useTestDriver(context);
+    const dashcam = useDashcam(context, client);
+    ```
+  </Card>
+  
+  <Card title="Core Classes" icon="code" href="/v7/progressive-apis/CORE">
+    **Full Control** - Manual everything
+    ```javascript
+    const client = new TestDriver(apiKey);
+    await client.connect();
+    ```
+  </Card>
+</CardGroup>
+
+## Complete Examples
+
+### Web Application Testing
+
+```javascript login.test.js
+import { describe, test, expect } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+describe('User Login', () => {
+  test('successful login flow', async (context) => {
+    const { testdriver, dashcam } = await chrome(context, {
+      url: 'https://myapp.com/login',
+      maximized: true
+    });
+    
+    // Fill login form
+    await testdriver.find('email input').type('user@example.com');
+    await testdriver.find('password input').type('password123');
+    await testdriver.find('Login button').click();
+    
+    // Verify dashboard loads
+    const result = await testdriver.assert('Welcome message is visible');
+    expect(result).toBeTruthy();
+    
+    // Dashcam automatically saves replay URL
+    console.log('Replay:', dashcam.url);
+  });
+  
+  test('invalid credentials error', async (context) => {
+    const { testdriver } = await chrome(context, {
+      url: 'https://myapp.com/login'
+    });
+    
+    await testdriver.find('email input').type('wrong@example.com');
+    await testdriver.find('password input').type('wrongpass');
+    await testdriver.find('Login button').click();
+    
+    await testdriver.assert('Invalid credentials error appears');
+  });
+});
+```
+
+### VS Code Extension Testing
+
+```javascript extension.test.js
+import { test } from 'vitest';
+import { vscode } from 'testdriverai/presets';
+
+test('create new python file', async (context) => {
+  const { vscode } = await vscode(context, {
+    workspace: '/tmp/test-project',
+    extensions: ['ms-python.python']
+  });
+  
+  // Open command palette
+  await vscode.pressKeys(['cmd', 'shift', 'p']);
+  
+  // Create new Python file
+  await vscode.type('Python: Create New File');
+  await vscode.pressKeys(['enter']);
+  
+  // Verify file created
+  await vscode.assert('Untitled Python file is open');
+});
+```
+
+### Electron App Testing
+
+```javascript electron-app.test.js
+import { test } from 'vitest';
+import { electron } from 'testdriverai/presets';
+
+test('file menu operations', async (context) => {
+  const { app } = await electron(context, {
+    appPath: './dist/my-app',
+    args: ['--enable-logging']
+  });
+  
+  await app.find('File menu').click();
+  await app.find('New Document').click();
+  
+  await app.assert('New document window opens');
+});
+```
+
+### Using Multiple Presets
+
+```javascript multi-app.test.js
+import { test } from 'vitest';
+import { chrome, vscode } from 'testdriverai/presets';
+
+test('test chrome and vscode together', async (context) => {
+  // Both share the same Vitest context for cleanup
+  const browser = await chrome(context, {
+    url: 'https://example.com'
+  });
+  
+  const editor = await vscode(context, {
+    workspace: '/tmp/project'
+  });
+  
+  // Use both in the same test
+  await browser.testdriver.find('link').click();
+  await editor.vscode.find('File').click();
+});
+```
+
+## Test Lifecycle
+
+TestDriver automatically manages the entire test lifecycle:
+
+```javascript
+test('lifecycle example', async (context) => {
+  // 1. Setup happens automatically when you call preset
+  const { testdriver, dashcam } = await chrome(context, { url });
+  
+  // 2. Your test code runs
+  await testdriver.find('button').click();
+  
+  // 3. Teardown happens automatically after test completes
+  // - Dashcam stops and saves replay URL
+  // - TestDriver disconnects from sandbox
+  // - All resources are cleaned up
+});
+```
+
+### Automatic Cleanup
+
+Even if your test fails or throws an error, cleanup still happens:
+
+```javascript
+test('error handling', async (context) => {
+  const { testdriver } = await chrome(context, { url });
+  
+  try {
+    await testdriver.find('non-existent element').click();
+  } catch (error) {
+    // Cleanup STILL happens automatically via Vitest hooks
+    console.error('Test failed:', error);
+    throw error;
+  }
+  // No need for finally block or manual cleanup
+});
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash .env
+TD_API_KEY=your-api-key-here
+TD_API_ROOT=https://testdriver-api.onrender.com
+```
+
+TestDriver automatically reads these when initializing.
+
+### Vitest Config Options
+
+```javascript vitest.config.mjs
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    // Recommended: Increase timeouts for UI testing
+    testTimeout: 120000, // 2 minutes per test
+    hookTimeout: 120000, // 2 minutes for setup/teardown
+    
+    // Optional: Run tests sequentially for resource-intensive tests
+    threads: false,
+    
+    // Optional: Limit concurrent tests
+    maxConcurrency: 3,
+    
+    // Optional: Enable file watching
+    watch: false,
+  },
+});
+```
+
+### Per-Test Configuration
+
+Override defaults for specific tests:
+
+```javascript
+test('long running test', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://slow-app.com',
+    dashcam: false, // Disable recording for faster execution
+    maximized: false,
+  });
+  
+  // Your test code
+}, { timeout: 180000 }); // 3-minute timeout for this test only
+```
+
+## Running Tests
+
+### Basic Commands
+
+```bash
+# Run all tests
+npx vitest
+
+# Run specific file
+npx vitest login.test.js
+
+# Run in watch mode
+npx vitest --watch
+
+# Run with coverage
+npx vitest --coverage
+
+# Run tests matching pattern
+npx vitest --grep "login"
+```
+
+### CI/CD Integration
+
+```yaml .github/workflows/test.yml
+name: TestDriver Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      
+      - name: Install dependencies
+        run: npm install
+      
+      - name: Run tests
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+        run: npx vitest --run
+```
+
+## Advanced Patterns
+
+### Shared Setup with beforeEach
+
+```javascript
+import { describe, test, beforeEach } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+describe('Dashboard Tests', () => {
+  let testdriver;
+  
+  beforeEach(async (context) => {
+    // Setup runs before each test
+    const result = await chrome(context, {
+      url: 'https://myapp.com'
+    });
+    testdriver = result.testdriver;
+    
+    // Shared login
+    await testdriver.find('email').type('user@example.com');
+    await testdriver.find('password').type('password');
+    await testdriver.find('Login').click();
+  });
+  
+  test('view profile', async () => {
+    await testdriver.find('Profile link').click();
+    await testdriver.assert('Profile page loads');
+  });
+  
+  test('view settings', async () => {
+    await testdriver.find('Settings link').click();
+    await testdriver.assert('Settings page loads');
+  });
+});
+```
+
+### Parameterized Tests
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+const testCases = [
+  { browser: 'chrome', os: 'linux' },
+  { browser: 'chrome', os: 'windows' },
+  { browser: 'chrome', os: 'mac' },
+];
+
+testCases.forEach(({ browser, os }) => {
+  test(`login on ${os}`, async (context) => {
+    const { testdriver } = await chrome(context, {
+      url: 'https://myapp.com',
+      os
+    });
+    
+    await testdriver.find('Login').click();
+    await testdriver.assert('Login successful');
+  });
+});
+```
+
+### Custom Helpers
+
+```javascript helpers.js
+import { chrome } from 'testdriverai/presets';
+
+export async function loginAsUser(context, email, password) {
+  const { testdriver } = await chrome(context, {
+    url: 'https://myapp.com/login'
+  });
+  
+  await testdriver.find('email input').type(email);
+  await testdriver.find('password input').type(password);
+  await testdriver.find('Login button').click();
+  
+  return testdriver;
+}
+```
+
+```javascript test.js
+import { test } from 'vitest';
+import { loginAsUser } from './helpers.js';
+
+test('logged in user can view dashboard', async (context) => {
+  const testdriver = await loginAsUser(context, 'user@example.com', 'pass123');
+  
+  await testdriver.find('Dashboard link').click();
+  await testdriver.assert('Dashboard is visible');
+});
+```
+
+## Best Practices
+
+### 1. Use Descriptive Test Names
+
+```javascript
+// ✅ Good
+test('user can login with valid credentials and view dashboard', async (context) => {
+
+// ❌ Bad
+test('test1', async (context) => {
+```
+
+### 2. Enable Dashcam for Debugging
+
+```javascript
+test('complex interaction', async (context) => {
+  const { testdriver, dashcam } = await chrome(context, {
+    url: 'https://myapp.com',
+    dashcam: true // Always enable for debugging
+  });
+  
+  // If test fails, check dashcam.url for replay
+});
+```
+
+### 3. Use Assertions Liberally
+
+```javascript
+test('multi-step flow', async (context) => {
+  const { testdriver } = await chrome(context, { url });
+  
+  await testdriver.find('Step 1').click();
+  await testdriver.assert('Step 1 completed'); // Verify each step
+  
+  await testdriver.find('Step 2').click();
+  await testdriver.assert('Step 2 completed');
+});
+```
+
+### 4. Keep Tests Focused
+
+```javascript
+// ✅ Good - One test per scenario
+test('user can login', async (context) => { /* ... */ });
+test('user can logout', async (context) => { /* ... */ });
+
+// ❌ Bad - Testing too many things
+test('user can login and logout and change settings and...', async (context) => { /* ... */ });
+```
+
+### 5. Use Environment Variables for Secrets
+
+```javascript
+// ✅ Good
+await testdriver.find('password').type(process.env.TEST_PASSWORD);
+
+// ❌ Bad
+await testdriver.find('password').type('hardcoded-password');
+```
+
+## Troubleshooting
+
+### Tests Timeout
+
+Increase timeout in vitest.config.mjs:
+
+```javascript
+export default defineConfig({
+  test: {
+    testTimeout: 180000, // 3 minutes
+  },
+});
+```
+
+### Cleanup Not Working
+
+Make sure you're passing the `context` parameter:
+
+```javascript
+// ✅ Correct
+test('my test', async (context) => {
+  await chrome(context, { url });
+});
+
+// ❌ Wrong - cleanup won't work
+test('my test', async () => {
+  await chrome({}, { url });
+});
+```
+
+### Dashcam URL Not Available
+
+Ensure Dashcam is enabled and check for errors:
+
+```javascript
+const { testdriver, dashcam } = await chrome(context, {
+  url: 'https://example.com',
+  dashcam: true
+});
+
+if (dashcam) {
+  console.log('Replay URL:', dashcam.url);
+} else {
+  console.error('Dashcam not initialized');
+}
+```
+
+## See Also
+
+- [Provision API](/v7/progressive-apis/PROVISION) - One-line setup for common apps
+- [Hooks API](/v7/progressive-apis/HOOKS) - Flexible lifecycle control
+- [Chrome Preset](/v7/presets/chrome) - Browser testing
+- [VS Code Preset](/v7/presets/vscode) - Extension testing
+- [Electron Preset](/v7/presets/electron) - Desktop app testing
+- [Vitest Plugin](/v7/guides/vitest-plugin) - Test recording and reporting

package/docs/v7/api/{ai.mdx → act.mdx}

@@ -1,18 +1,18 @@
 ---
-title: "ai()"
-sidebarTitle: "ai"
+title: "act()"
+sidebarTitle: "act"
 description: "Execute natural language tasks using AI"
 icon: "wand-magic-sparkles"
 ---
 
 ## Overview
 
-The `ai()` method allows you to execute complex tasks using natural language descriptions. TestDriver's AI will figure out the steps needed to accomplish the task.
+The `act()` method allows you to execute complex tasks using natural language descriptions. TestDriver's AI will figure out the steps needed to accomplish the task.
 
 ## Syntax
 
 ```javascript
-await testdriver.ai(task, options)
+await testdriver.act(task, options)
 ```
 
 ## Parameters
@@ -41,20 +41,20 @@ await testdriver.ai(task, options)
 
 ```javascript
 // Simple task execution
-await testdriver.ai('Click the submit button');
+await testdriver.act('Click the submit button');
 
 // Complex multi-step task
-await testdriver.ai('Fill out the contact form and submit it');
+await testdriver.act('Fill out the contact form and submit it');
 
 // Navigation task
-await testdriver.ai('Go to the settings page and enable notifications');
+await testdriver.act('Go to the settings page and enable notifications');
 ```
 
 ### With Validation
 
 ```javascript
 // AI will verify the task completed successfully
-const result = await testdriver.ai('Complete the checkout process', { 
+const result = await testdriver.act('Complete the checkout process', { 
   validateAndLoop: true 
 });
 
@@ -65,10 +65,10 @@ console.log('Task result:', result);
 
 ```javascript
 // The AI will break down complex tasks
-await testdriver.ai('Search for "laptop", add the first result to cart, and proceed to checkout');
+await testdriver.act('Search for "laptop", add the first result to cart, and proceed to checkout');
 
 // UI exploration
-await testdriver.ai('Find and click all menu items to explore the application');
+await testdriver.act('Find and click all menu items to explore the application');
 ```
 
 ## Use Cases
@@ -78,8 +78,8 @@ await testdriver.ai('Find and click all menu items to explore the application');
     Use AI to explore unfamiliar applications:
     
     ```javascript
-    await testdriver.ai('Explore the main navigation menu');
-    await testdriver.ai('Try to find the user profile settings');
+    await testdriver.act('Explore the main navigation menu');
+    await testdriver.act('Try to find the user profile settings');
     ```
   </Accordion>
   
@@ -87,8 +87,8 @@ await testdriver.ai('Find and click all menu items to explore the application');
     Let AI handle multi-step processes:
     
     ```javascript
-    await testdriver.ai('Complete the multi-step registration form');
-    await testdriver.ai('Configure all the advanced settings to default values');
+    await testdriver.act('Complete the multi-step registration form');
+    await testdriver.act('Configure all the advanced settings to default values');
     ```
   </Accordion>
   
@@ -96,8 +96,8 @@ await testdriver.ai('Find and click all menu items to explore the application');
     When exact element locations aren't critical:
     
     ```javascript
-    await testdriver.ai('Close any popup dialogs');
-    await testdriver.ai('Accept the cookie consent if it appears');
+    await testdriver.act('Close any popup dialogs');
+    await testdriver.act('Accept the cookie consent if it appears');
     ```
   </Accordion>
 </AccordionGroup>
@@ -109,13 +109,13 @@ await testdriver.ai('Find and click all menu items to explore the application');
   
   ```javascript
   // ✅ Good
-  await testdriver.ai('Add the first product to the shopping cart');
+  await testdriver.act('Add the first product to the shopping cart');
   
   // ❌ Too vague
-  await testdriver.ai('do something');
+  await testdriver.act('do something');
   
   // ❌ Too specific (defeats the purpose)
-  await testdriver.ai('click at coordinates 500, 300');
+  await testdriver.act('click at coordinates 500, 300');
   ```
 </Check>
 
@@ -124,7 +124,7 @@ await testdriver.ai('Find and click all menu items to explore the application');
   
   ```javascript
   // Use AI for setup
-  await testdriver.ai('Navigate to the login page');
+  await testdriver.act('Navigate to the login page');
   
   // Use explicit methods for critical steps
   const usernameField = await testdriver.find('username input');
@@ -141,7 +141,7 @@ await testdriver.ai('Find and click all menu items to explore the application');
 
 ## When to Use AI vs Explicit Methods
 
-### Use `ai()` when:
+### Use `act()` when:
 - Exploring unfamiliar applications
 - Handling optional UI elements (popups, cookies, etc.)
 - Prototyping tests quickly
@@ -177,8 +177,8 @@ describe('E-commerce Flow with AI', () => {
     await testdriver.focusApplication('Google Chrome');
     
     // Use AI for navigation and exploration
-    await testdriver.ai('Browse to the electronics section');
-    await testdriver.ai('Find and add a laptop to the cart');
+    await testdriver.act('Browse to the electronics section');
+    await testdriver.act('Find and add a laptop to the cart');
     
     // Use explicit methods for critical steps
     const cartIcon = await testdriver.find('shopping cart icon');
@@ -188,7 +188,7 @@ describe('E-commerce Flow with AI', () => {
     console.log('Cart total:', total);
     
     // Use AI for checkout flow
-    await testdriver.ai('Proceed to checkout and fill in shipping details', {
+    await testdriver.act('Proceed to checkout and fill in shipping details', {
       validateAndLoop: true
     });
     

package/docs/v7/api/client.mdx

@@ -18,7 +18,7 @@ const testdriver = new TestDriver(apiKey, options)
 ### Parameters
 
 <ParamField path="apiKey" type="string" required>
-  Your TestDriver API key from the [dashboard](https://app.testdriver.ai/team)
+  Your TestDriver API key from the [dashboard](https://console.testdriver.ai/team)
 </ParamField>
 
 <ParamField path="options" type="object">