testdriverai 7.0.0 → 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/rightClick.mdx

@@ -0,0 +1,123 @@
+---
+title: "rightClick"
+description: "Perform a right-click action to open context menus"
+icon: "bars"
+---
+
+## Overview
+
+The `rightClick()` method performs a right-click action on an element, typically used to open context menus. You can either call it on an [`Element`](/v7/core-concepts/elements) instance or use it directly with a selector.
+
+## Syntax
+
+```javascript
+// Right-click on an element
+await element.rightClick();
+
+// Right-click using a selector
+await ai.rightClick('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 to right-click |
+
+## Returns
+
+Returns a `Promise<void>` that resolves when the right-click action completes.
+
+## Examples
+
+### Right-Click to Open Context Menu
+
+```javascript
+const fileItem = await ai.find('README.md file');
+await fileItem.rightClick();
+
+// Select menu option
+await ai.click('Delete from context menu');
+```
+
+### Direct Right-Click with Selector
+
+```javascript
+await ai.rightClick('image in the gallery');
+await ai.click('Save image as');
+```
+
+### VS Code Context Menu
+
+```javascript
+import { test } from 'vitest';
+import { vscode } from '@testdriver/sdk';
+
+test('renames a file via context menu', async () => {
+  const { ai } = await vscode();
+  
+  // Right-click on a file
+  await ai.rightClick('test.js in the file explorer');
+  
+  // Click rename option
+  await ai.click('Rename');
+  
+  // Type new name
+  await ai.type('test.spec.js');
+  await ai.pressKeys('Enter');
+  
+  // Verify rename
+  const renamedFile = await ai.find('test.spec.js in the file explorer');
+  expect(renamedFile).toBeTruthy();
+});
+```
+
+### Browser Context Menu
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from '@testdriver/sdk';
+
+test('opens link in new tab', async () => {
+  const { ai } = await chrome('https://example.com');
+  
+  // Right-click on a link
+  await ai.rightClick('Documentation link');
+  
+  // Select "Open in new tab"
+  await ai.click('Open link in new tab');
+});
+```
+
+### Custom Context Menu in Web App
+
+```javascript
+test('uses custom context menu', async () => {
+  const { ai } = await chrome('https://app.example.com');
+  
+  // Right-click on custom element
+  await ai.rightClick('project item in the list');
+  
+  // Wait for custom menu to appear
+  await ai.find('custom context menu');
+  
+  // Click menu option
+  await ai.click('Duplicate project');
+  
+  // Verify duplication
+  const duplicatedProject = await ai.find('project item (copy)');
+  expect(duplicatedProject).toBeTruthy();
+});
+```
+
+## Related Methods
+
+- [`click()`](/v7/api/click) - Single click on an element
+- [`doubleClick()`](/v7/api/doubleClick) - Double-click on an element
+- [`mouseDown()`](/v7/api/mouseDown) - Press mouse button without releasing
+- [`mouseUp()`](/v7/api/mouseUp) - Release mouse button
+- [`hover()`](/v7/api/hover) - Move mouse over element without clicking