testdriverai 6.2.2 → 7.1.0

package/docs/v7/api/mouseDown.mdx

@@ -0,0 +1,161 @@
+---
+title: "mouseDown"
+description: "Press the mouse button without releasing it"
+icon: "arrow-pointer"
+---
+
+## Overview
+
+The `mouseDown()` method presses the mouse button at an element's location without releasing it. This is useful for drag operations, custom gestures, or when you need precise control over mouse events. You can either call it on an [`Element`](/v7/core-concepts/elements) instance or use it directly with a selector.
+
+## Syntax
+
+```javascript
+// Mouse down on an element
+await element.mouseDown();
+
+// Mouse down using a selector
+await ai.mouseDown('selector');
+```
+
+## Parameters
+
+When called on an `Element`, no parameters are required.
+
+When called directly on the AI client:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `selector` | `string` | The selector describing the element where the mouse button should be pressed |
+
+## Returns
+
+Returns a `Promise<void>` that resolves when the mouse button is pressed.
+
+## Examples
+
+### Basic Drag Operation
+
+```javascript
+// Start dragging an item
+const dragItem = await ai.find('file to drag');
+await dragItem.mouseDown();
+
+// Move to drop target
+const dropTarget = await ai.find('folder to drop into');
+await dropTarget.hover();
+
+// Release
+await ai.mouseUp();
+```
+
+### Drag and Drop with Direct Selectors
+
+```javascript
+await ai.mouseDown('draggable card');
+await ai.hover('drop zone');
+await ai.mouseUp();
+```
+
+### Selecting Multiple Items
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from '@testdriver/sdk';
+
+test('selects multiple items with click and drag', async () => {
+  const { ai } = await chrome('https://app.example.com');
+  
+  // Start selection at first item
+  await ai.mouseDown('first item in grid');
+  
+  // Drag to last item
+  await ai.hover('last item in grid');
+  
+  // Release to complete selection
+  await ai.mouseUp();
+  
+  // Verify multiple items selected
+  const selectedItems = await ai.find('selected items count');
+  expect(selectedItems.text).toContain('5 items selected');
+});
+```
+
+### Custom Drawing Application
+
+```javascript
+test('draws on canvas', async () => {
+  const { ai } = await chrome('https://drawing-app.example.com');
+  
+  // Start drawing
+  await ai.mouseDown('canvas at top-left corner');
+  
+  // Draw a line by moving mouse
+  await ai.hover('canvas at center');
+  await ai.hover('canvas at bottom-right corner');
+  
+  // Stop drawing
+  await ai.mouseUp();
+  
+  // Verify something was drawn
+  const canvas = await ai.exec('document.querySelector("canvas").toDataURL()');
+  expect(canvas).toBeTruthy();
+});
+```
+
+### Long Press Gesture
+
+```javascript
+test('triggers long press menu', async () => {
+  const { ai } = await chrome('https://mobile-app.example.com');
+  
+  // Press and hold
+  await ai.mouseDown('message in chat');
+  
+  // Wait for long-press menu
+  await new Promise(resolve => setTimeout(resolve, 500));
+  
+  // Verify menu appeared before releasing
+  const menu = await ai.find('message options menu');
+  expect(menu).toBeTruthy();
+  
+  // Release
+  await ai.mouseUp();
+});
+```
+
+### Resizing UI Elements
+
+```javascript
+test('resizes panel', async () => {
+  const { ai } = await vscode();
+  
+  // Grab resize handle
+  await ai.mouseDown('sidebar resize handle');
+  
+  // Drag to new position
+  await ai.hover('position 300 pixels from left edge');
+  
+  // Release
+  await ai.mouseUp();
+  
+  // Verify new size
+  const sidebar = await ai.find('sidebar');
+  expect(sidebar.width).toBeGreaterThan(250);
+});
+```
+
+## Important Notes
+
+- Always pair `mouseDown()` with [`mouseUp()`](/v7/api/mouseUp) to complete the gesture
+- The mouse button remains pressed until `mouseUp()` is called
+- Use [`hover()`](/v7/api/hover) to move the mouse while the button is pressed
+- For simple drag operations, consider using `ai()` with a natural language description like `"drag file to folder"`
+
+## Related Methods
+
+- [`mouseUp()`](/v7/api/mouseUp) - Release the mouse button
+- [`hover()`](/v7/api/hover) - Move mouse to element
+- [`click()`](/v7/api/click) - Full click (mouseDown + mouseUp)
+- [`doubleClick()`](/v7/api/doubleClick) - Double-click on element
+- [`rightClick()`](/v7/api/rightClick) - Right-click for context menu

package/docs/v7/api/mouseUp.mdx

@@ -0,0 +1,164 @@
+---
+title: "mouseUp"
+description: "Release the mouse button"
+icon: "arrow-pointer"
+---
+
+## Overview
+
+The `mouseUp()` method releases the mouse button, completing a drag operation or custom mouse gesture that was started with [`mouseDown()`](/v7/api/mouseDown). You can call it without parameters to release at the current mouse position.
+
+## Syntax
+
+```javascript
+// Release mouse button at current position
+await ai.mouseUp();
+```
+
+## Parameters
+
+None. The mouse button is released at the current cursor position.
+
+## Returns
+
+Returns a `Promise<void>` that resolves when the mouse button is released.
+
+## Examples
+
+### Complete Drag and Drop
+
+```javascript
+// Start dragging
+await ai.mouseDown('file to drag');
+
+// Move to drop location
+await ai.hover('target folder');
+
+// Complete the drop
+await ai.mouseUp();
+```
+
+### Selecting Multiple Files
+
+```javascript
+import { test } from 'vitest';
+import { vscode } from '@testdriver/sdk';
+
+test('selects range of files', async () => {
+  const { ai } = await vscode();
+  
+  // Click first file
+  await ai.click('first-file.js in explorer');
+  
+  // Hold shift and click last file
+  await ai.pressKeys('Shift');
+  await ai.mouseDown('last-file.js in explorer');
+  await ai.mouseUp();
+  
+  // Verify multiple files selected
+  const selectedCount = await ai.find('status bar showing file count');
+  expect(selectedCount.text).toContain('5 files');
+});
+```
+
+### Drawing Application
+
+```javascript
+test('draws a shape', async () => {
+  const { ai } = await chrome('https://drawing-app.example.com');
+  
+  // Select pencil tool
+  await ai.click('pencil tool');
+  
+  // Draw a line
+  await ai.mouseDown('canvas near top-left');
+  await ai.hover('canvas center');
+  await ai.hover('canvas bottom-right');
+  await ai.mouseUp();
+  
+  // Verify drawing exists
+  const strokes = await ai.exec('canvas.getContext("2d").getImageData(0,0,100,100)');
+  expect(strokes).toBeTruthy();
+});
+```
+
+### Resizing Window Panels
+
+```javascript
+test('resizes editor panel', async () => {
+  const { ai } = await vscode();
+  
+  // Grab the divider
+  await ai.mouseDown('panel resize divider');
+  
+  // Drag to new position
+  await ai.hover('position 400 pixels from left');
+  
+  // Release to complete resize
+  await ai.mouseUp();
+  
+  // Verify new panel size
+  const panel = await ai.find('editor panel');
+  expect(panel.width).toBeGreaterThan(350);
+});
+```
+
+### Drag to Reorder List Items
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from '@testdriver/sdk';
+
+test('reorders tasks in list', async () => {
+  const { ai } = await chrome('https://todo-app.example.com');
+  
+  // Start dragging first task
+  await ai.mouseDown('drag handle on first task');
+  
+  // Move down to third position
+  await ai.hover('third task position');
+  
+  // Drop the task
+  await ai.mouseUp();
+  
+  // Verify new order
+  const thirdTask = await ai.find('third task in list');
+  expect(thirdTask.text).toContain('Original first task');
+});
+```
+
+### Text Selection with Mouse
+
+```javascript
+test('selects text with mouse drag', async () => {
+  const { ai } = await chrome('https://document.example.com');
+  
+  // Start selection at beginning of word
+  await ai.mouseDown('start of "TestDriver" word');
+  
+  // Drag to end of word
+  await ai.hover('end of "TestDriver" word');
+  
+  // Complete selection
+  await ai.mouseUp();
+  
+  // Verify selection
+  const selection = await ai.exec('window.getSelection().toString()');
+  expect(selection).toBe('TestDriver');
+});
+```
+
+## Important Notes
+
+- `mouseUp()` must be preceded by [`mouseDown()`](/v7/api/mouseDown) to have an effect
+- Releases the button at the current cursor position
+- Completes any drag or selection operation that was in progress
+- For simple clicks, use [`click()`](/v7/api/click) instead of mouseDown/mouseUp pair
+
+## Related Methods
+
+- [`mouseDown()`](/v7/api/mouseDown) - Press mouse button without releasing
+- [`hover()`](/v7/api/hover) - Move mouse to element
+- [`click()`](/v7/api/click) - Complete click (mouseDown + mouseUp)
+- [`doubleClick()`](/v7/api/doubleClick) - Double-click on element
+- [`rightClick()`](/v7/api/rightClick) - Right-click for context menu

package/docs/v7/api/pressKeys.mdx

@@ -0,0 +1,349 @@
+---
+title: "pressKeys()"
+sidebarTitle: "pressKeys"
+description: "Press keyboard keys and shortcuts"
+icon: "keyboard"
+---
+
+## Overview
+
+Press one or more keyboard keys simultaneously, useful for keyboard shortcuts, navigation, and special keys.
+
+## Syntax
+
+```javascript
+await testdriver.pressKeys(keys)
+```
+
+## Parameters
+
+<ParamField path="keys" type="Array&lt;string&gt;" required>
+  Array of keys to press simultaneously
+</ParamField>
+
+## Returns
+
+`Promise<void>`
+
+## Common Keys
+
+### Special Keys
+- `'enter'`, `'tab'`, `'escape'`, `'backspace'`, `'delete'`
+- `'space'`, `'up'`, `'down'`, `'left'`, `'right'`
+- `'home'`, `'end'`, `'pageup'`, `'pagedown'`
+
+### Modifier Keys
+- `'ctrl'`, `'alt'`, `'shift'`
+- `'command'` (macOS), `'win'` (Windows)
+- `'ctrlleft'`, `'ctrlright'`, `'shiftleft'`, `'shiftright'`
+
+### Function Keys
+- `'f1'` through `'f24'`
+
+## Examples
+
+### Navigation
+
+```javascript
+// Tab to next field
+await testdriver.pressKeys(['tab']);
+
+// Shift+Tab to previous field
+await testdriver.pressKeys(['shift', 'tab']);
+
+// Arrow keys
+await testdriver.pressKeys(['down']);
+await testdriver.pressKeys(['up']);
+await testdriver.pressKeys(['left']);
+await testdriver.pressKeys(['right']);
+
+// Home/End
+await testdriver.pressKeys(['home']);  // Start of line
+await testdriver.pressKeys(['end']);   // End of line
+
+// Page navigation
+await testdriver.pressKeys(['pagedown']);
+await testdriver.pressKeys(['pageup']);
+```
+
+### Keyboard Shortcuts
+
+```javascript
+// Copy (Ctrl+C / Cmd+C)
+await testdriver.pressKeys(['ctrl', 'c']);
+
+// Paste (Ctrl+V / Cmd+V)
+await testdriver.pressKeys(['ctrl', 'v']);
+
+// Save (Ctrl+S)
+await testdriver.pressKeys(['ctrl', 's']);
+
+// Select All (Ctrl+A)
+await testdriver.pressKeys(['ctrl', 'a']);
+
+// Undo (Ctrl+Z)
+await testdriver.pressKeys(['ctrl', 'z']);
+
+// Redo (Ctrl+Y)
+await testdriver.pressKeys(['ctrl', 'y']);
+
+// Find (Ctrl+F)
+await testdriver.pressKeys(['ctrl', 'f']);
+
+// New tab (Ctrl+T)
+await testdriver.pressKeys(['ctrl', 't']);
+
+// Close tab (Ctrl+W)
+await testdriver.pressKeys(['ctrl', 'w']);
+
+// Refresh (F5 or Ctrl+R)
+await testdriver.pressKeys(['f5']);
+await testdriver.pressKeys(['ctrl', 'r']);
+```
+
+### System Shortcuts
+
+```javascript
+// Alt+Tab (Windows - switch apps)
+await testdriver.pressKeys(['alt', 'tab']);
+
+// Alt+F4 (Windows - close window)
+await testdriver.pressKeys(['alt', 'f4']);
+
+// Win+D (Windows - show desktop)
+await testdriver.pressKeys(['winleft', 'd']);
+
+// Win+L (Windows - lock screen)
+await testdriver.pressKeys(['winleft', 'l']);
+
+// Cmd+Tab (macOS - switch apps)
+await testdriver.pressKeys(['command', 'tab']);
+
+// Cmd+Q (macOS - quit app)
+await testdriver.pressKeys(['command', 'q']);
+```
+
+### Form Submission
+
+```javascript
+// Submit form
+await testdriver.pressKeys(['enter']);
+
+// Cancel/Close
+await testdriver.pressKeys(['escape']);
+
+// Check checkbox
+await testdriver.pressKeys(['space']);
+```
+
+### Text Editing
+
+```javascript
+// Delete selected text
+await testdriver.pressKeys(['delete']);
+
+// Backspace
+await testdriver.pressKeys(['backspace']);
+
+// Select all and delete
+await testdriver.pressKeys(['ctrl', 'a']);
+await testdriver.pressKeys(['delete']);
+
+// Cut text
+await testdriver.pressKeys(['ctrl', 'x']);
+```
+
+## Best Practices
+
+<Check>
+  **Wait after shortcuts**
+  
+  Some keyboard shortcuts trigger animations or navigation:
+  
+  ```javascript
+  await testdriver.pressKeys(['ctrl', 't']); // New tab
+  await new Promise(r => setTimeout(r, 500)); // Wait for tab
+  await testdriver.pressKeys(['ctrl', 'l']); // Focus URL bar
+  ```
+</Check>
+
+<Check>
+  **Use Tab for form navigation**
+  
+  Tab is more reliable than clicking multiple fields:
+  
+  ```javascript
+  const firstField = await testdriver.find('email input');
+  await firstField.click();
+  await testdriver.type('user@example.com');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.type('password123');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.pressKeys(['enter']); // Submit
+  ```
+</Check>
+
+<Warning>
+  **Platform-specific keys**
+  
+  Use the appropriate modifier key for the platform:
+  - Windows/Linux: `'ctrl'`
+  - macOS: `'command'`
+  
+  ```javascript
+  // For cross-platform, you might need to detect OS
+  const modKey = process.platform === 'darwin' ? 'command' : 'ctrl';
+  await testdriver.pressKeys([modKey, 'c']); // Copy
+  ```
+</Warning>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Form Navigation">
+    ```javascript
+    // Fill form using Tab
+    const firstField = await testdriver.find('name field');
+    await firstField.click();
+    await testdriver.type('John Doe');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('john@example.com');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('555-0123');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.pressKeys(['enter']); // Submit
+    ```
+  </Accordion>
+  
+  <Accordion title="Text Manipulation">
+    ```javascript
+    const textArea = await testdriver.find('comment textarea');
+    await textArea.click();
+    
+    // Select all existing text
+    await testdriver.pressKeys(['ctrl', 'a']);
+    
+    // Copy it
+    await testdriver.pressKeys(['ctrl', 'c']);
+    
+    // Type new text
+    await testdriver.type('New comment');
+    
+    // Undo if needed
+    await testdriver.pressKeys(['ctrl', 'z']);
+    ```
+  </Accordion>
+  
+  <Accordion title="Browser Navigation">
+    ```javascript
+    // Open new tab
+    await testdriver.pressKeys(['ctrl', 't']);
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Focus address bar
+    await testdriver.pressKeys(['ctrl', 'l']);
+    await testdriver.type('https://example.com');
+    await testdriver.pressKeys(['enter']);
+    
+    // Refresh page
+    await testdriver.pressKeys(['f5']);
+    
+    // Close tab
+    await testdriver.pressKeys(['ctrl', 'w']);
+    ```
+  </Accordion>
+  
+  <Accordion title="Application Shortcuts">
+    ```javascript
+    // Save document
+    await testdriver.pressKeys(['ctrl', 's']);
+    
+    // Print
+    await testdriver.pressKeys(['ctrl', 'p']);
+    
+    // Find in page
+    await testdriver.pressKeys(['ctrl', 'f']);
+    await testdriver.type('search term');
+    await testdriver.pressKeys(['escape']); // Close find
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Keyboard Navigation', () => {
+  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 navigate form with keyboard', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Find first field
+    const emailField = await testdriver.find('email input');
+    await emailField.click();
+    await testdriver.type('user@example.com');
+    
+    // Tab through fields
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('John');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('Doe');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('password123');
+    
+    // Submit with Enter
+    await testdriver.pressKeys(['tab']);
+    await testdriver.pressKeys(['enter']);
+    
+    await testdriver.assert('form submitted successfully');
+  });
+
+  it('should use keyboard shortcuts', async () => {
+    // Open new browser tab
+    await testdriver.pressKeys(['ctrl', 't']);
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Focus address bar
+    await testdriver.pressKeys(['ctrl', 'l']);
+    await testdriver.type('https://example.com');
+    await testdriver.pressKeys(['enter']);
+    
+    await new Promise(r => setTimeout(r, 2000));
+    
+    // Select all page content
+    await testdriver.pressKeys(['ctrl', 'a']);
+    
+    // Copy
+    await testdriver.pressKeys(['ctrl', 'c']);
+    
+    // Refresh page
+    await testdriver.pressKeys(['f5']);
+  });
+});
+```
+
+## Related Methods
+
+- [`type()`](/v7/api/type) - Type text
+- [`click()`](/v7/api/click) - Click elements
+- [`scroll()`](/v7/api/scroll) - Scroll pages