testdriverai 6.2.2 → 7.1.0

package/docs/v7/api/click.mdx

@@ -0,0 +1,287 @@
+---
+title: "click()"
+sidebarTitle: "click"
+description: "Click at specific coordinates or on elements"
+icon: "mouse-pointer"
+---
+
+## Element Click
+
+When called on an Element object, clicks on the located element.
+
+### Syntax
+
+```javascript
+await element.click(action)
+```
+
+### Parameters
+
+<ParamField path="action" type="string" default="click">
+  Type of click action: `'click'`, `'double-click'`, `'right-click'`, `'hover'`, `'mouseDown'`, `'mouseUp'`
+</ParamField>
+
+### Returns
+
+`Promise<void>`
+
+### Examples
+
+```javascript
+// Regular click
+const button = await testdriver.find('submit button');
+await button.click();
+
+// Double-click
+const file = await testdriver.find('README.txt file');
+await file.click('double-click');
+
+// Right-click
+const item = await testdriver.find('menu item');
+await item.click('right-click');
+
+// Hover (same as element.hover())
+const tooltip = await testdriver.find('info icon');
+await button.click('hover');
+```
+
+## Coordinate Click
+
+Click at specific screen coordinates.
+
+### Syntax
+
+```javascript
+await testdriver.click(x, y, action)
+```
+
+### Parameters
+
+<ParamField path="x" type="number" required>
+  X coordinate
+</ParamField>
+
+<ParamField path="y" type="number" required>
+  Y coordinate
+</ParamField>
+
+<ParamField path="action" type="string" default="click">
+  Type of click: `'click'`, `'double-click'`, `'right-click'`, `'mouseDown'`, `'mouseUp'`
+</ParamField>
+
+### Returns
+
+`Promise<void>`
+
+### Examples
+
+```javascript
+// Click at coordinates
+await testdriver.click(500, 300);
+
+// Double-click at coordinates
+await testdriver.click(500, 300, 'double-click');
+
+// Right-click at coordinates
+await testdriver.click(500, 300, 'right-click');
+```
+
+## Click Actions
+
+### Regular Click
+
+Single left-click action.
+
+```javascript
+const button = await testdriver.find('Login button');
+await button.click();
+```
+
+### Double Click
+
+Double-click action, commonly used to open files or select text.
+
+```javascript
+const file = await testdriver.find('document.pdf');
+await file.click('double-click');
+
+// Or use the dedicated method
+await file.doubleClick();
+```
+
+### Right Click
+
+Right-click to open context menus.
+
+```javascript
+const folder = await testdriver.find('Documents folder');
+await folder.click('right-click');
+
+// Or use the dedicated method
+await folder.rightClick();
+```
+
+### Mouse Down / Mouse Up
+
+For drag operations or custom click behavior.
+
+```javascript
+const draggable = await testdriver.find('draggable item');
+await draggable.click('mouseDown');
+
+// Move to target
+const dropZone = await testdriver.find('drop zone');
+await dropZone.hover();
+await dropZone.click('mouseUp');
+
+// Or use dedicated methods
+await draggable.mouseDown();
+await dropZone.mouseUp();
+```
+
+## Best Practices
+
+<Check>
+  **Prefer element clicks over coordinate clicks**
+  
+  Element-based clicking is more reliable and resolution-independent:
+  
+  ```javascript
+  // ✅ Preferred
+  const button = await testdriver.find('submit button');
+  await button.click();
+  
+  // ❌ Avoid (fragile)
+  await testdriver.click(500, 300);
+  ```
+</Check>
+
+<Check>
+  **Verify element was found**
+  
+  ```javascript
+  const element = await testdriver.find('button');
+  if (!element.found()) {
+    throw new Error('Element not found');
+  }
+  await element.click();
+  ```
+</Check>
+
+<Warning>
+  **Element must be found before clicking**
+  
+  The `find()` method automatically locates elements, but clicking an element that wasn't found will throw an error:
+  
+  ```javascript
+  const element = await testdriver.find('button');
+  // This will throw if element wasn't found
+  await element.click();
+  ```
+</Warning>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Button Clicks">
+    ```javascript
+    const submitBtn = await testdriver.find('submit button');
+    await submitBtn.click();
+    
+    const cancelBtn = await testdriver.find('cancel button');
+    await cancelBtn.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Opening Files">
+    ```javascript
+    const file = await testdriver.find('report.pdf file icon');
+    await file.doubleClick();
+    ```
+  </Accordion>
+  
+  <Accordion title="Context Menus">
+    ```javascript
+    const item = await testdriver.find('file item');
+    await item.rightClick();
+    
+    // Select menu option
+    const deleteOption = await testdriver.find('Delete option');
+    await deleteOption.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Drag and Drop">
+    ```javascript
+    const source = await testdriver.find('source item');
+    await source.mouseDown();
+    
+    const target = await testdriver.find('target zone');
+    await target.hover();
+    await target.mouseUp();
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Click Interactions', () => {
+  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 perform various click actions', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Regular click
+    const loginBtn = await testdriver.find('login button');
+    await loginBtn.click();
+    
+    // Right-click for context menu
+    const profileIcon = await testdriver.find('profile icon');
+    await profileIcon.rightClick();
+    
+    const settingsOption = await testdriver.find('Settings menu option');
+    await settingsOption.click();
+    
+    // Double-click to edit
+    const nameField = await testdriver.find('name display field');
+    await nameField.doubleClick();
+    
+    // Verify state
+    await testdriver.assert('name field is now editable');
+  });
+
+  it('should perform drag and drop', async () => {
+    const item = await testdriver.find('draggable item');
+    await item.mouseDown();
+    
+    // Drag to new location
+    const dropTarget = await testdriver.find('drop area');
+    await dropTarget.hover();
+    await dropTarget.mouseUp();
+    
+    // Verify
+    await testdriver.assert('item is in the drop area');
+  });
+});
+```
+
+## Related Methods
+
+- [`find()`](/v7/api/find) - Locate elements to click
+- [`hover()`](/v7/api/hover) - Hover without clicking
+- [`doubleClick()`](/v7/api/doubleClick) - Dedicated double-click method
+- [`rightClick()`](/v7/api/rightClick) - Dedicated right-click method

package/docs/v7/api/client.mdx

@@ -0,0 +1,322 @@
+---
+title: "TestDriver Client"
+sidebarTitle: "Client"
+description: "Initialize and configure the TestDriver SDK client"
+icon: "plug"
+---
+
+## Overview
+
+The `TestDriver` client is the main entry point for the SDK. It handles authentication, sandbox connection, and provides access to all testing methods.
+
+## Constructor
+
+```javascript
+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)
+</ParamField>
+
+<ParamField path="options" type="object">
+  Configuration options for the client
+  
+  <Expandable title="properties">
+    <ParamField path="os" type="string" default="windows">
+      Operating system for the sandbox: `'windows'` or `'linux'`
+    </ParamField>
+    
+    <ParamField path="resolution" type="string" default="1366x768">
+      Screen resolution for the sandbox (e.g., `'1920x1080'`, `'1366x768'`)
+    </ParamField>
+    
+    <ParamField path="apiRoot" type="string" default="https://testdriver-api.onrender.com">
+      API endpoint URL (typically only changed for self-hosted deployments)
+    </ParamField>
+    
+    <ParamField path="analytics" type="boolean" default="true">
+      Enable or disable usage analytics
+    </ParamField>
+    
+    <ParamField path="logging" type="boolean" default="true">
+      Enable or disable console logging
+    </ParamField>
+    
+    <ParamField path="environment" type="object">
+      Additional environment variables to pass to the sandbox
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+### Example
+
+```javascript
+import TestDriver from 'testdriverai';
+
+const testdriver = new TestDriver(process.env.TD_API_KEY, {
+  os: 'windows',
+  resolution: '1920x1080',
+  logging: true,
+  analytics: true
+});
+```
+
+## Authentication
+
+### auth()
+
+Authenticate with the TestDriver API.
+
+```javascript
+await testdriver.auth()
+```
+
+**Returns:** `Promise<string>` - Authentication token
+
+**Example:**
+```javascript
+await testdriver.auth();
+```
+
+<Note>
+  You must call `auth()` before `connect()`. Most examples call both sequentially.
+</Note>
+
+## Connection Management
+
+### connect()
+
+Connect to a sandbox environment. This creates or reconnects to a virtual machine where your tests will run.
+
+```javascript
+await testdriver.connect(options)
+```
+
+#### Parameters
+
+<ParamField path="options" type="object">
+  Connection options
+  
+  <Expandable title="properties">
+    <ParamField path="newSandbox" type="boolean" default="false">
+      Force creation of a new sandbox instead of reusing an existing one
+    </ParamField>
+    
+    <ParamField path="sandboxId" type="string">
+      Existing sandbox ID to reconnect to
+    </ParamField>
+    
+    <ParamField path="ip" type="string">
+      Direct IP address to connect to (for self-hosted sandboxes)
+    </ParamField>
+    
+    <ParamField path="sandboxAmi" type="string">
+      AMI to use for the sandbox (AWS deployments)
+    </ParamField>
+    
+    <ParamField path="sandboxInstance" type="string">
+      Instance type for the sandbox (AWS deployments)
+    </ParamField>
+    
+    <ParamField path="headless" type="boolean" default="false">
+      Run in headless mode without opening the debugger
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+**Returns:** `Promise<Object>` - Sandbox instance details including `instanceId`, `ip`, `vncPort`, etc.
+
+#### Examples
+
+**Basic connection:**
+```javascript
+await testdriver.connect({ newSandbox: true });
+```
+
+**Reconnect to existing sandbox:**
+```javascript
+const instance = await testdriver.connect({ 
+  sandboxId: 'existing-sandbox-id-123' 
+});
+```
+
+**Self-hosted sandbox:**
+```javascript
+await testdriver.connect({ 
+  ip: '192.168.1.100'
+});
+```
+
+### disconnect()
+
+Disconnect from the sandbox and clean up resources.
+
+```javascript
+await testdriver.disconnect()
+```
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```javascript
+afterAll(async () => {
+  await testdriver.disconnect();
+});
+```
+
+## Instance Information
+
+### getInstance()
+
+Get the current sandbox instance details.
+
+```javascript
+const instance = testdriver.getInstance()
+```
+
+**Returns:** `Object | null` - Sandbox instance information
+
+**Example:**
+```javascript
+const instance = testdriver.getInstance();
+console.log('Instance ID:', instance.instanceId);
+console.log('IP Address:', instance.ip);
+```
+
+### getSessionId()
+
+Get the current session ID for tracking and debugging.
+
+```javascript
+const sessionId = testdriver.getSessionId()
+```
+
+**Returns:** `string | null` - Session ID
+
+**Example:**
+```javascript
+const sessionId = testdriver.getSessionId();
+console.log('Session:', sessionId);
+```
+
+## Logging & Events
+
+### setLogging()
+
+Enable or disable console logging at runtime.
+
+```javascript
+testdriver.setLogging(enabled)
+```
+
+**Parameters:**
+- `enabled` (boolean) - Whether to enable logging
+
+**Example:**
+```javascript
+// Disable logging for cleanup operations
+testdriver.setLogging(false);
+await testdriver.disconnect();
+testdriver.setLogging(true);
+```
+
+### getEmitter()
+
+Get the event emitter for custom event handling.
+
+```javascript
+const emitter = testdriver.getEmitter()
+```
+
+**Returns:** `EventEmitter2` - Event emitter instance
+
+**Example:**
+```javascript
+const emitter = testdriver.getEmitter();
+
+emitter.on('command:start', (data) => {
+  console.log('Command started:', data);
+});
+
+emitter.on('command:success', (data) => {
+  console.log('Command succeeded:', data);
+});
+
+emitter.on('command:error', (error) => {
+  console.error('Command failed:', error);
+});
+```
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('My Test Suite', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    // Initialize client
+    client = new TestDriver(process.env.TD_API_KEY, {
+      os: 'windows',
+      resolution: '1366x768',
+      logging: true
+    });
+    
+    // Set up event listeners
+    const emitter = testdriver.getEmitter();
+    emitter.on('log:info', (msg) => console.log('[INFO]', msg));
+    
+    // Authenticate and connect
+    await testdriver.auth();
+    const instance = await testdriver.connect({ newSandbox: true });
+    
+    console.log('Connected to sandbox:', instance.instanceId);
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('runs a test', async () => {
+    // Your test code here
+  });
+});
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Reuse sandboxes across tests">
+    Use `beforeAll`/`afterAll` to create one sandbox per test suite rather than per test. This significantly reduces execution time.
+  </Accordion>
+  
+  <Accordion title="Handle connection errors gracefully">
+    Wrap `connect()` in a try-catch block to handle network issues or quota limits:
+    
+    ```javascript
+    try {
+      await testdriver.connect({ newSandbox: true });
+    } catch (error) {
+      console.error('Failed to connect:', error.message);
+      throw error;
+    }
+    ```
+  </Accordion>
+  
+  <Accordion title="Always disconnect">
+    Use `afterAll` or try-finally blocks to ensure `disconnect()` is called even if tests fail. This prevents orphaned sandboxes.
+  </Accordion>
+  
+  <Accordion title="Use environment variables for API keys">
+    Never hardcode API keys. Use environment variables:
+    
+    ```javascript
+    const testdriver = new TestDriver(process.env.TD_API_KEY);
+    ```
+  </Accordion>
+</AccordionGroup>