testdriverai 6.2.2 → 7.1.0

package/docs/v6/overview/comparison.mdx

@@ -0,0 +1,101 @@
+---
+title: Comparison
+sidebarTitle: "Comparison"
+description: "TestDriver vs Playwright vs Selenium"
+icon: boxing-glove
+---
+
+## Application support
+
+TestDriver operates a full desktop environment, so it can run any application.
+
+<div className="comparison-table">
+  | Application | TestDriver | Playwright | Selenium |
+  |:-----------------:|:---------:|:-----------:|:--------:|
+  | Web Apps          | ✅        | ✅           | ✅       |
+  | Mobile Apps       | ✅        | ✅           | ✅       |
+  | VS Code Plugins   | ✅        |              |         |
+  | Desktop Apps      | ✅        |              |         |
+  | Chrome Extensions | ✅        |              |         |
+</div>
+
+## Testing features
+
+TestDriver is AI first.
+
+<div className="comparison-table">
+  | Feature              | TestDriver | Playwright | Selenium |
+  |:--------------------:|:----------:|:----------:|:--------:|
+  | Test Generation      | ✅         |            |          |
+  | Adaptive Testing     | ✅         |            |          |
+  | Visual Assertions    | ✅         |            |          |
+  | Self Healing         | ✅         |            |          |
+  | Application Switching| ✅         |            |          |
+  | GitHub Actions       | ✅         | ✅         |          |
+  | Team Dashboard       | ✅         |            |          |
+  | Team Collaboration   | ✅         |            |          |
+</div>
+
+## Test coverage
+
+TestDriver has more coverage than selector-based frameworks.
+
+<div className="comparison-table">
+| Feature            | TestDriver | Playwright | Selenium |
+|:------------------:|:----------:|:----------:|:--------:|
+| Browser Viewport   | ✅            | ✅       | ✅       |
+| Browser App        | ✅            |          |         |
+| Operating System   | ✅            |          |         |
+| PDFs               | ✅            |          |         |
+| File System        | ✅            |          |         |
+| Push Notifications | ✅            |          |         |
+| Image Content      | ✅            |          |         |
+| Video Content      | ✅            |          |         |
+| `<iframe>`         | ✅            |          |         |
+| `<canvas>`         | ✅            |          |         |
+| `<video>`          | ✅            |          |         |
+</div>
+
+## Debugging features
+
+Debugging features are powered by [Dashcam.io](https://dashcam.io).
+
+<div className="comparison-table">
+  | Feature              | TestDriver | Playwright | Selenium |
+  |:--------------------:|:----------:|:----------:|:--------:|
+  | AI Summary           | ✅         |            |          |
+  | Video Replay         | ✅         | ✅         |          |
+  | Browser Logs         | ✅         | ✅         |          |
+  | Desktop Logs         | ✅         |            |          |
+  | Network Requests     | ✅         | ✅         |          |
+  | Team Dashboard       | ✅         |            |          |
+  | Team Collaboration   | ✅         |            |          |
+</div>
+
+## Web browser support
+
+TestDriver is browser agnostic and supports any version of any browser.
+
+<div className="comparison-table">
+  | Feature  | TestDriver | Playwright | Selenium |
+  |:--------:|:----------:|:----------:|:--------:|
+  | Chrome   | ✅         | ✅         | ✅       |
+  | Firefox  | ✅         | ✅         | ✅       |
+  | Webkit   | ✅         | ✅         | ✅       |
+  | IE       | ✅         |            | ✅       |
+  | Edge     | ✅         | ✅         | ✅       |
+  | Opera    | ✅         |            | ✅       |
+  | Safari   | ✅         |            | ✅       |
+</div>
+
+## Operating system support
+
+TestDriver currently supports all the three major operating systems!
+
+<div className="comparison-table">
+  | Feature  | TestDriver | Playwright | Selenium |
+  |:--------:|:----------:|:----------:|:--------:|
+  | Windows  | ✅         | ✅         | ✅        |
+  | Mac      | ✅         | ✅         | ✅        |
+  | Linux    | ✅         | ✅         | ✅        |
+</div>

package/docs/v7/README.md

@@ -0,0 +1,135 @@
+# TestDriver v7 SDK Documentation
+
+This directory contains the documentation for TestDriver v7, which introduces the JavaScript SDK as the primary interface for writing tests.
+
+## Structure
+
+```
+v7/
+├── getting-started/
+│   └── quickstart.mdx          # Quick start guide for the SDK
+├── api/
+│   ├── client.mdx              # TestDriver client initialization and connection
+│   ├── elements.mdx            # Element finding and interaction
+│   ├── sandbox.mdx             # Sandbox management and script execution
+│   ├── interactions.mdx        # Keyboard, mouse, and scrolling
+│   └── assertions.mdx          # AI-powered assertions and testing
+└── guides/
+    └── migration.mdx           # Migration guide from YAML to SDK
+```
+
+## Documentation Coverage
+
+### Getting Started
+- **Quickstart**: Complete setup and first test example using the `assert.test.mjs` pattern
+  - Installation
+  - Authentication
+  - Basic test structure with Vitest
+  - Sandbox connection
+
+### API Reference
+
+#### Client (`/v7/api/client.mdx`)
+- Constructor and initialization
+- `auth()` - Authentication
+- `connect()` - Sandbox connection with all options
+- `disconnect()` - Cleanup
+- Instance management (`getInstance()`, `getSessionId()`)
+- Logging and events (`setLogging()`, `getEmitter()`)
+
+#### Elements (`/v7/api/elements.mdx`)
+- `find()` - AI-powered element location
+- Element class methods:
+  - `found()` - Check if located
+  - `click()`, `hover()`, `doubleClick()`, `rightClick()`
+  - `mouseDown()`, `mouseUp()` - For drag operations
+- Element properties:
+  - Coordinates (`x`, `y`, `centerX`, `centerY`)
+  - Visual data (`screenshot`, `width`, `height`, `boundingBox`)
+  - Content (`text`, `label`, `confidence`)
+- Polling patterns for dynamic elements
+
+#### Sandbox (`/v7/api/sandbox.mdx`)
+- `exec()` - Execute code in sandbox
+  - JavaScript execution (browser context)
+  - PowerShell execution (Windows commands)
+- `focusApplication()` - Window management
+- Common operations:
+  - Software installation
+  - File operations
+  - Environment variables
+  - Network operations
+  - Process management
+  - Browser automation
+
+#### Interactions (`/v7/api/interactions.mdx`)
+- `type()` - Text input
+- `pressKeys()` - Keyboard shortcuts and special keys
+- `click()` / `hover()` - Coordinate-based mouse actions
+- `scroll()` - Page scrolling
+- `scrollUntilText()` / `scrollUntilImage()` - Scroll until found
+- Keyboard key reference
+
+#### Assertions (`/v7/api/assertions.mdx`)
+- `assert()` - AI-powered assertions
+  - Basic assertions
+  - Negative assertions (invert parameter)
+  - Async assertions
+- `remember()` - Extract information from screen
+- Testing patterns:
+  - Polling assertions
+  - Multi-step validation
+  - Soft assertions
+- Best practices
+
+### Guides
+
+#### Migration (`/v7/guides/migration.mdx`)
+- Why migrate from YAML to SDK
+- Basic structure comparison
+- Complete command mapping:
+  - Element location
+  - Typing and keyboard
+  - Scrolling
+  - Assertions
+  - Code execution
+  - Application focus
+- Advanced patterns:
+  - Variables and data reuse
+  - Conditional logic
+  - Loops
+  - Data-driven tests
+- Lifecycle hooks comparison
+- Migration checklist
+- Common pitfalls
+- Complete example migration
+
+## Integration with docs.json
+
+The v7 documentation is integrated into `docs/docs.json` under the "Computer-Use SDK" tab with version "7.0.0 (SDK)", distinguishing it from the YAML-based "6.X.X (YAML)" documentation.
+
+## Examples Used
+
+The documentation uses examples from:
+- `testdriver/acceptance-sdk/assert.test.mjs` - Basic assertion test
+- `testdriver/acceptance-sdk/type.test.mjs` - Typing and form interaction
+- `testdriver/acceptance-sdk/focus-window.test.mjs` - Application focus
+- Other SDK test files for complete examples
+
+## Key Documentation Features
+
+1. **Practical Examples**: Every method includes working code examples
+2. **Best Practices**: Accordion sections with tips and patterns
+3. **Migration Support**: Complete YAML-to-SDK migration guide
+4. **Type Safety**: Parameter documentation with types
+5. **Real Test Patterns**: Examples based on actual test files
+6. **Comprehensive Coverage**: All major SDK features documented
+
+## Next Steps
+
+Consider adding:
+- `/v7/guides/best-practices.mdx` - Detailed best practices
+- `/v7/guides/examples.mdx` - Complete test suite examples
+- `/v7/guides/debugging.mdx` - Debugging techniques
+- `/v7/guides/ci-cd.mdx` - CI/CD integration guide
+- `/v7/api/keyboard-keys.mdx` - Complete keyboard key reference

package/docs/v7/api/ai.mdx

@@ -0,0 +1,205 @@
+---
+title: "ai()"
+sidebarTitle: "ai"
+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.
+
+## Syntax
+
+```javascript
+await testdriver.ai(task, options)
+```
+
+## Parameters
+
+<ParamField path="task" type="string" required>
+  Natural language description of what to do
+</ParamField>
+
+<ParamField path="options" type="object">
+  Execution options
+  
+  <Expandable title="properties">
+    <ParamField path="validateAndLoop" type="boolean" default="false">
+      Whether to validate completion and retry if incomplete
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Returns
+
+`Promise<string | void>` - Final AI response if `validateAndLoop` is true
+
+## Examples
+
+### Basic Usage
+
+```javascript
+// Simple task execution
+await testdriver.ai('Click the submit button');
+
+// Complex multi-step task
+await testdriver.ai('Fill out the contact form and submit it');
+
+// Navigation task
+await testdriver.ai('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', { 
+  validateAndLoop: true 
+});
+
+console.log('Task result:', result);
+```
+
+### Multi-Step Workflows
+
+```javascript
+// The AI will break down complex tasks
+await testdriver.ai('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');
+```
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Exploratory Testing">
+    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');
+    ```
+  </Accordion>
+  
+  <Accordion title="Complex Workflows">
+    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');
+    ```
+  </Accordion>
+  
+  <Accordion title="Flexible Interactions">
+    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');
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Best Practices
+
+<Check>
+  **Be specific but flexible**: Give enough context without over-constraining the AI
+  
+  ```javascript
+  // ✅ Good
+  await testdriver.ai('Add the first product to the shopping cart');
+  
+  // ❌ Too vague
+  await testdriver.ai('do something');
+  
+  // ❌ Too specific (defeats the purpose)
+  await testdriver.ai('click at coordinates 500, 300');
+  ```
+</Check>
+
+<Check>
+  **Use for exploration, not precision**: For critical assertions, use explicit methods
+  
+  ```javascript
+  // Use AI for setup
+  await testdriver.ai('Navigate to the login page');
+  
+  // Use explicit methods for critical steps
+  const usernameField = await testdriver.find('username input');
+  await usernameField.click();
+  await testdriver.type('testuser');
+  
+  await testdriver.assert('login page is displayed');
+  ```
+</Check>
+
+<Warning>
+  **AI tasks may be slower**: The AI needs to analyze the screen and plan actions. For performance-critical tests, use explicit methods.
+</Warning>
+
+## When to Use AI vs Explicit Methods
+
+### Use `ai()` when:
+- Exploring unfamiliar applications
+- Handling optional UI elements (popups, cookies, etc.)
+- Prototyping tests quickly
+- Tasks where exact steps may vary
+
+### Use explicit methods when:
+- Performance is critical
+- You need precise control
+- Making assertions
+- Debugging test failures
+- Repetitive, predictable actions
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('E-commerce Flow with AI', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    client = new TestDriver(process.env.TD_API_KEY);
+    await testdriver.auth();
+    await testdriver.connect({ newSandbox: true });
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('should complete shopping flow using AI assistance', async () => {
+    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');
+    
+    // Use explicit methods for critical steps
+    const cartIcon = await testdriver.find('shopping cart icon');
+    await cartIcon.click();
+    
+    const total = await testdriver.remember('the cart total amount');
+    console.log('Cart total:', total);
+    
+    // Use AI for checkout flow
+    await testdriver.ai('Proceed to checkout and fill in shipping details', {
+      validateAndLoop: true
+    });
+    
+    // Explicit assertion
+    await testdriver.assert('order confirmation page is displayed');
+  });
+});
+```
+
+## Related Methods
+
+- [`find()`](/v7/api/find) - Locate specific elements
+- [`assert()`](/v7/api/assert) - Make assertions
+- [`remember()`](/v7/api/remember) - Extract information