testdriverai 7.1.4 → 7.2.0

package/docs/v7/getting-started/{running-and-debugging.mdx → debugging-tests.mdx}

@@ -1,97 +1,10 @@
 ---
-title: "Running & Debugging Tests"
-description: "Run tests with Vitest and debug failures with Dashcam replays"
-icon: "play"
+title: "Debugging Tests"
+description: "Debug test failures with Dashcam replays, logs, and error analysis"
+icon: "bug"
 ---
 
-Learn how to run TestDriver tests efficiently and debug failures using video replays, logs, and error analysis.
-
-## Running Tests
-
-TestDriver works with Vitest's powerful test runner:
-
-<Tabs>
-  <Tab title="Run All Tests">
-    ```bash
-    # Run all tests once
-    npx vitest run
-
-    # Run in watch mode
-    npx vitest
-
-    # Run with coverage
-    npx vitest run --coverage
-    ```
-  </Tab>
-
-  <Tab title="Run Specific Tests">
-    ```bash
-    # Run specific file
-    npx vitest run login.test.js
-
-    # Run multiple files
-    npx vitest run login.test.js checkout.test.js
-
-    # Run tests matching pattern
-    npx vitest run --grep "login"
-
-    # Run tests in specific folder
-    npx vitest run tests/e2e/
-    ```
-  </Tab>
-
-  <Tab title="Watch Mode">
-    ```bash
-    # Watch mode - reruns on file changes
-    npx vitest
-
-    # Watch only changed tests
-    npx vitest --changed
-
-    # Watch specific file
-    npx vitest login.test.js
-    ```
-  </Tab>
-
-  <Tab title="Parallel Execution">
-    ```bash
-    # Control concurrency
-    npx vitest run --maxConcurrency=5
-
-    # Run with specific thread count
-    npx vitest run --threads --minThreads=2 --maxThreads=8
-    ```
-  </Tab>
-</Tabs>
-
-## Test Output
-
-Understanding test output:
-
-```bash
-$ npx vitest run
-
- ✓ login.test.js (3) 23.4s
-   ✓ user can login with valid credentials 12.3s
-   ✓ shows error for invalid email 5.6s
-   ✓ shows error for wrong password 5.5s
-
- ✓ checkout.test.js (2) 34.7s
-   ✓ user can complete checkout 28.9s
-   ✓ validates credit card format 5.8s
-
-Test Files  2 passed (2)
-     Tests  5 passed (5)
-  Duration  58.12s
-
-📹 Dashcam Replays:
-  - https://console.testdriver.ai/dashcam/abc123
-  - https://console.testdriver.ai/dashcam/def456
-```
-
-<Tip>
-  Click the Dashcam URLs to watch video replays of your tests!
-</Tip>
+Learn how to debug TestDriver test failures using video replays, logs, and rich error information.
 
 ## Debugging with Dashcam
 
@@ -389,33 +302,6 @@ test('check network', async (context) => {
 });
 ```
 
-## Performance Profiling
-
-Identify slow tests:
-
-```bash
-# Run with reporter showing timing
-npx vitest run --reporter=verbose
-
-# Output shows duration per test:
-✓ slow-test.test.js > user can checkout (34.7s)
-  → find('product') (2.1s)
-  → click() (0.4s)
-  → find('add to cart') (1.8s)
-  → click() (0.3s)
-  → find('checkout') (28.9s) ← SLOW!
-  → click() (0.5s)
-```
-
-Optimize slow operations:
-
-1. **Enable caching** - First run is slow, subsequent runs are fast
-2. **Use parallel execution** - Run tests concurrently
-3. **Check network delays** - Look for slow API calls in Dashcam
-4. **Optimize selectors** - More specific = faster matching
-
-[Performance optimization guide](/v7/guides/performance)
-
 ## Debugging in CI/CD
 
 When tests fail in CI:
@@ -459,39 +345,23 @@ When tests fail in CI:
   </Step>
 </Steps>
 
-## Vitest UI
-
-Use Vitest UI for interactive debugging:
-
-```bash
-# Start Vitest UI
-npx vitest --ui
-```
-
-Open http://localhost:51204 to see:
-- Test file tree
-- Test status and duration
-- Console output
-- Re-run individual tests
-- Filter and search tests
-
 ## Next Steps
 
 <CardGroup cols={2}>
   <Card
-    title="Setting Up in CI"
-    icon="arrows-spin"
-    href="/v7/getting-started/setting-up-in-ci"
+    title="Running Tests"
+    icon="play"
+    href="/v7/getting-started/running-tests"
   >
-    Run tests in CI/CD pipelines
+    Learn how to run tests efficiently
   </Card>
 
   <Card
-    title="Debugging Guide"
-    icon="bug"
-    href="/v7/guides/debugging"
+    title="Setting Up in CI"
+    icon="arrows-spin"
+    href="/v7/getting-started/setting-up-in-ci"
   >
-    Advanced debugging techniques
+    Run tests in CI/CD pipelines
   </Card>
 
   <Card

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

@@ -1,337 +1,54 @@
 ---
 title: "Quick Start"
 sidebarTitle: "Quickstart"
-description: "Get started with the TestDriver JavaScript SDK in 2 minutes."
+description: "Get started with the TestDriver JavaScript SDK in 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.
+TestDriver makes it easy to write automated computer-use tests for web browsers, desktop apps, and more. In this quickstart, you'll write and run your first TestDriver test using Vitest in just a few minutes.
 
-<Note>
-  **New!** Use `testdriverai init` to scaffold a complete project with one command. This will:
-  - Create package.json with test scripts
-  - Set up Vitest configuration
-  - Create example tests
-  - Add GitHub Actions workflow
-  - Install dependencies automatically
-  - Prompt for your API key (saved to .env)
+<Steps>
+  <Step title="Create a TestDriver Account">
 
-  ```bash
-  npm install -g testdriverai
-  testdriverai init
-  ```
+    You will need a TestDriver account to get an API key.
 
-  Then jump to [Step 3](#run-your-test) to run your tests!
-</Note>
+    <Card
+      title="Sign Up for TestDriver"
+      icon="user-plus"
+      href="https://app.testdriver.ai/team"
+      arrow
+      horizontal
+    >
+      Start for free. No credit-card required!
+    </Card>
 
-<Steps>
+  </Step>
   <Step title="Install TestDriver">
 
-    Install the TestDriver SDK and Vitest test runner:
+    Use `npx` to quickly set up an example project:
 
     ```bash
-    npm install --save-dev testdriverai vitest
+    npx testdriverai@beta init
     ```
 
-  </Step>
-  
-  <Step title="Write Your First Test">
-      
-    Create `test.test.js` and add your API key from [console.testdriver.ai](https://console.testdriver.ai):
-
-    <Tabs>
-      <Tab title="Fast">
-        ```javascript test.test.js
-        import { test } from 'vitest';
-        import { TestDriver } from 'testdriverai/vitest/hooks';
-
-        test('my first test', async (context) => {
-          const testdriver = TestDriver(context, {
-            headless: true,
-            apiKey: 'tdai-1234567890abcdef' // Your API key from console.testdriver.ai
-          });
-          
-          await testdriver.provision.chrome({ url: 'https://example.com' });
-          
-          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 { TestDriver } from 'testdriverai/vitest/hooks';
-
-        test('my first test', async (context) => {
-          const testdriver = TestDriver(context, { headless: true });
-          // apiKey automatically read from process.env.TD_API_KEY
-          
-          await testdriver.provision.chrome({ url: 'https://example.com' });
-          
-          await testdriver.find('More information link').click();
-          await testdriver.assert('IANA page is visible');
-        });
-        ```
-        
-        <Tip>
-          Add `.env` to your `.gitignore` file!
-        </Tip>
-      </Tab>
-    </Tabs>
+    This will walk you through creating a new project folder, installing dependencies, and setting up your API key.
 
   </Step>
   
   <Step title="Run Your Test">
+
+    TestDriver uses Vitest as the test runner. To run your test, use:
     
     ```bash
     npx vitest run
     ```
-    
-    That's it! 🎉
-    
-    <Tip>
-      The `chrome()` preset automatically handles authentication, browser launch, and cleanup.
-    </Tip>
+
+    This will spawn a sandbox, launch Chrome, navigate to the specified URL, and run your test commands.
 
   </Step>
 </Steps>
 
-## What Just Happened?
-
-The TestDriver hook with `provision.chrome()` 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!
-
-## Chainable API
-
-TestDriver uses a chainable promise API for elegant test writing:
-
-```javascript
-// ✅ Chainable - find and interact in one line
-await testdriver.find('submit button').click();
-await testdriver.find('menu item').hover();
-await testdriver.find('checkbox').doubleClick();
-
-// ✅ Also works - traditional two-step
-const button = await testdriver.find('submit button');
-await button.click();
-```
-
-**Available chainable methods:**
-- `.click()` - Click the element
-- `.hover()` - Hover over the element  
-- `.doubleClick()` - Double-click the element
-- `.rightClick()` - Right-click the element
-- `.mouseDown()` - Press mouse button down
-- `.mouseUp()` - Release mouse button
-- `.type(text)` - Type text (for input elements)
-
-<Tip>
-  Use chainable syntax for cleaner, more readable test code!
-</Tip>
-
-## 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'
-  });
-  
-  // Use chainable syntax for cleaner code
-  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 [console.testdriver.ai](https://console.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}>

package/docs/v7/getting-started/running-tests.mdx

@@ -0,0 +1,173 @@
+---
+title: "Running Tests"
+description: "Run TestDriver tests with Vitest test runner"
+icon: "play"
+---
+
+Learn how to run TestDriver tests efficiently with Vitest's powerful test runner.
+
+## Running Tests
+
+TestDriver works with Vitest's powerful test runner:
+
+<Tabs>
+  <Tab title="Run All Tests">
+    ```bash
+    # Run all tests once
+    npx vitest run
+
+    # Run in watch mode
+    npx vitest
+
+    # Run with coverage
+    npx vitest run --coverage
+    ```
+  </Tab>
+
+  <Tab title="Run Specific Tests">
+    ```bash
+    # Run specific file
+    npx vitest run login.test.js
+
+    # Run multiple files
+    npx vitest run login.test.js checkout.test.js
+
+    # Run tests matching pattern
+    npx vitest run --grep "login"
+
+    # Run tests in specific folder
+    npx vitest run tests/e2e/
+    ```
+  </Tab>
+
+  <Tab title="Watch Mode">
+    ```bash
+    # Watch mode - reruns on file changes
+    npx vitest
+
+    # Watch only changed tests
+    npx vitest --changed
+
+    # Watch specific file
+    npx vitest login.test.js
+    ```
+  </Tab>
+
+  <Tab title="Parallel Execution">
+    ```bash
+    # Control concurrency
+    npx vitest run --maxConcurrency=5
+
+    # Run with specific thread count
+    npx vitest run --threads --minThreads=2 --maxThreads=8
+    ```
+  </Tab>
+</Tabs>
+
+## Test Output
+
+Understanding test output:
+
+```bash
+$ npx vitest run
+
+ ✓ login.test.js (3) 23.4s
+   ✓ user can login with valid credentials 12.3s
+   ✓ shows error for invalid email 5.6s
+   ✓ shows error for wrong password 5.5s
+
+ ✓ checkout.test.js (2) 34.7s
+   ✓ user can complete checkout 28.9s
+   ✓ validates credit card format 5.8s
+
+Test Files  2 passed (2)
+     Tests  5 passed (5)
+  Duration  58.12s
+
+📹 Dashcam Replays:
+  - https://console.testdriver.ai/dashcam/abc123
+  - https://console.testdriver.ai/dashcam/def456
+```
+
+<Tip>
+  Click the Dashcam URLs to watch video replays of your tests!
+</Tip>
+
+## Performance Profiling
+
+Identify slow tests:
+
+```bash
+# Run with reporter showing timing
+npx vitest run --reporter=verbose
+
+# Output shows duration per test:
+✓ slow-test.test.js > user can checkout (34.7s)
+  → find('product') (2.1s)
+  → click() (0.4s)
+  → find('add to cart') (1.8s)
+  → click() (0.3s)
+  → find('checkout') (28.9s) ← SLOW!
+  → click() (0.5s)
+```
+
+Optimize slow operations:
+
+1. **Enable caching** - First run is slow, subsequent runs are fast
+2. **Use parallel execution** - Run tests concurrently
+3. **Check network delays** - Look for slow API calls in Dashcam
+4. **Optimize selectors** - More specific = faster matching
+
+[Performance optimization guide](/v7/guides/performance)
+
+## Vitest UI
+
+Use Vitest UI for interactive debugging:
+
+```bash
+# Start Vitest UI
+npx vitest --ui
+```
+
+Open http://localhost:51204 to see:
+- Test file tree
+- Test status and duration
+- Console output
+- Re-run individual tests
+- Filter and search tests
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card
+    title="Debugging Tests"
+    icon="bug"
+    href="/v7/getting-started/debugging-tests"
+  >
+    Debug test failures with Dashcam replays
+  </Card>
+
+  <Card
+    title="Setting Up in CI"
+    icon="arrows-spin"
+    href="/v7/getting-started/setting-up-in-ci"
+  >
+    Run tests in CI/CD pipelines
+  </Card>
+
+  <Card
+    title="Observable Features"
+    icon="microscope"
+    href="/v7/features/observable"
+  >
+    Complete observability guide
+  </Card>
+
+  <Card
+    title="Performance Guide"
+    icon="gauge-high"
+    href="/v7/guides/performance"
+  >
+    Optimize test performance
+  </Card>
+</CardGroup>