@testdriverai/agent 7.8.0-canary.10

package/docs/v7/hover.mdx

@@ -0,0 +1,279 @@
+---
+title: "hover()"
+sidebarTitle: "hover"
+description: "Hover over elements or coordinates"
+icon: "hand-pointer"
+---
+
+## Overview
+
+Move the mouse cursor over elements or specific coordinates without clicking, useful for revealing tooltips, dropdowns, and hover effects.
+
+## Element Hover
+
+Hover over a located element.
+
+### Syntax
+
+```javascript
+await element.hover()
+```
+
+### Returns
+
+`Promise<void>`
+
+### Examples
+
+```javascript
+// Find and hover
+const tooltip = await testdriver.find('info icon');
+await tooltip.hover();
+
+// Wait to see tooltip
+await new Promise(r => setTimeout(r, 1000));
+
+// Hover over menu to reveal submenu
+const menu = await testdriver.find('Products menu');
+await menu.hover();
+
+const submenu = await testdriver.find('Laptops submenu item');
+await submenu.click();
+```
+
+## Coordinate Hover
+
+Hover at specific screen coordinates.
+
+### Syntax
+
+```javascript
+await testdriver.hover(x, y)
+```
+
+### Parameters
+
+<ParamField path="x" type="number" required>
+  X coordinate
+</ParamField>
+
+<ParamField path="y" type="number" required>
+  Y coordinate
+</ParamField>
+
+### Returns
+
+`Promise<void>`
+
+### Examples
+
+```javascript
+// Hover at coordinates
+await testdriver.hover(500, 300);
+
+// Hover and wait
+await testdriver.hover(500, 300);
+await new Promise(r => setTimeout(r, 1000));
+```
+
+## Best Practices
+
+<Check>
+  **Prefer element hover over coordinates**
+  
+  ```javascript
+  // ✅ Preferred
+  const icon = await testdriver.find('info icon');
+  await icon.hover();
+  
+  // ❌ Avoid
+  await testdriver.hover(500, 300);
+  ```
+</Check>
+
+<Check>
+  **Wait after hovering for dynamic content**
+  
+  ```javascript
+  const menuItem = await testdriver.find('Settings menu');
+  await menuItem.hover();
+  
+  // Wait for submenu to appear
+  await new Promise(r => setTimeout(r, 500));
+  
+  const subItem = await testdriver.find('Profile submenu');
+  await subItem.click();
+  ```
+</Check>
+
+<Check>
+  **Verify element was found before hovering**
+  
+  ```javascript
+  const element = await testdriver.find('tooltip trigger');
+  if (!element.found()) {
+    throw new Error('Element not found');
+  }
+  await element.hover();
+  ```
+</Check>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Tooltips">
+    ```javascript
+    // Hover to show tooltip
+    const icon = await testdriver.find('help icon');
+    await icon.hover();
+    
+    await new Promise(r => setTimeout(r, 1000));
+    
+    // Read tooltip content
+    const tooltipText = await testdriver.extract('the tooltip text');
+    console.log('Tooltip:', tooltipText);
+    ```
+  </Accordion>
+  
+  <Accordion title="Dropdown Menus">
+    ```javascript
+    // Hover to reveal dropdown
+    const menuItem = await testdriver.find('Products menu item');
+    await menuItem.hover();
+    
+    // Wait for dropdown animation
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Click submenu option
+    const category = await testdriver.find('Electronics category');
+    await category.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Image Previews">
+    ```javascript
+    // Hover over thumbnail to see preview
+    const thumbnail = await testdriver.find('product thumbnail');
+    await thumbnail.hover();
+    
+    await new Promise(r => setTimeout(r, 800));
+    
+    // Verify preview appears
+    await testdriver.assert('product preview is displayed');
+    ```
+  </Accordion>
+  
+  <Accordion title="Hover Effects">
+    ```javascript
+    // Test hover state styling
+    const button = await testdriver.find('call to action button');
+    await button.hover();
+    
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Verify hover effect
+    await testdriver.assert('button background changed to blue');
+    ```
+  </Accordion>
+  
+  <Accordion title="Drag and Drop">
+    ```javascript
+    // Use hover in drag and drop
+    const item = await testdriver.find('draggable item');
+    await item.mouseDown();
+    
+    // Hover over drop zone
+    const dropZone = await testdriver.find('drop area');
+    await dropZone.hover();
+    
+    await new Promise(r => setTimeout(r, 300));
+    await dropZone.mouseUp();
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Hover Interactions', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    client = new TestDriver(process.env.TD_API_KEY);
+    await testdriver.auth();
+    await testdriver.connect();
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('should show tooltip on hover', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Find and hover over icon
+    const infoIcon = await testdriver.find('information icon');
+    await infoIcon.hover();
+    
+    // Wait for tooltip to appear
+    await new Promise(r => setTimeout(r, 1000));
+    
+    // Verify tooltip is visible
+    await testdriver.assert('tooltip is displayed');
+    
+    // Extract tooltip text
+    const tooltipText = await testdriver.extract('the tooltip message');
+    console.log('Tooltip says:', tooltipText);
+  });
+
+  it('should navigate dropdown menu', async () => {
+    // Hover over main menu
+    const menu = await testdriver.find('Navigation menu');
+    await menu.hover();
+    
+    // Wait for dropdown
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Hover over submenu item
+    const submenu = await testdriver.find('Account submenu');
+    await submenu.hover();
+    
+    await new Promise(r => setTimeout(r, 300));
+    
+    // Click nested menu item
+    const settings = await testdriver.find('Settings option');
+    await settings.click();
+    
+    await testdriver.assert('settings page is displayed');
+  });
+
+  it('should preview images on hover', async () => {
+    // Hover over product image
+    const productImg = await testdriver.find('product 1 thumbnail');
+    await productImg.hover();
+    
+    // Wait for preview
+    await new Promise(r => setTimeout(r, 800));
+    
+    // Verify preview appeared
+    await testdriver.assert('large product preview is shown');
+    
+    // Move away
+    const otherElement = await testdriver.find('page heading');
+    await otherElement.hover();
+    
+    // Verify preview disappeared
+    await new Promise(r => setTimeout(r, 500));
+    await testdriver.assert('product preview is hidden');
+  });
+});
+```
+
+## Related Methods
+
+- [`find()`](/v7/find) - Locate elements to hover
+- [`click()`](/v7/click) - Click after hovering
+- [`mouseDown()`](/v7/click) - Start drag operations

package/docs/v7/locating-elements.mdx

@@ -0,0 +1,71 @@
+---
+title: "Locating Elements"
+description: "Find UI elements using natural language descriptions"
+icon: "crosshairs"
+---
+
+## Locating Single Elements
+
+Use natural language to describe elements. Descriptions should be specific enough to locate the element, but not too-specific that they break with minor UI changes. For example:
+
+```javascript
+await testdriver.find('email input field');
+await testdriver.find('first product card in the grid');
+await testdriver.find('dropdown menu labeled "Country"');
+```
+
+<Info>TestDriver will cache found elements for improved performance on subsequent calls. Learn more about [element caching here](/v7/caching).</Info>
+
+## Debugging Found Elements
+
+After finding an element, you can inspect its properties for debugging:
+
+```javascript
+const button = await testdriver.find('submit button');
+console.log(button);
+```
+
+This outputs all element properties:
+
+```javascript
+{
+  description: 'submit button',
+  found: true,
+  x: 150,
+  y: 300,
+  coordinates: { x: 150, y: 300, centerX: 200, centerY: 320 },
+  threshold: 0.8,
+  confidence: 0.95,
+  similarity: 0.92,
+  selector: 'button[type="submit"]',
+  cache: {
+    hit: true,
+    strategy: 'pixel-diff',
+    createdAt: '2025-01-15T10:30:00Z',
+    diffPercent: 0.02,
+    imageUrl: 'https://...'
+  }
+}
+```
+
+## Working with Multiple Elements
+
+Find and interact with multiple elements:
+
+```javascript
+// Find all matching elements
+const products = await testdriver.findAll('product card');
+console.log(`Found ${products.length} products`);
+
+// Interact with each
+for (const product of products) {
+  const title = await product.find('title text');
+  console.log('Product:', title.text);
+
+  await product.find('add to cart button').click();
+}
+
+// Or find specific element
+const firstProduct = products[0];
+await firstProduct.click();
+```

package/docs/v7/making-assertions.mdx

@@ -0,0 +1,32 @@
+---
+title: "Making Assertions"
+description: "Verify application state with AI-powered assertions"
+icon: "check-double"
+---
+
+## Making Assertions
+
+Use AI-powered assertions to verify application state:
+
+```javascript
+// Verify visibility
+await testdriver.assert('login page is displayed');
+await testdriver.assert('submit button is visible');
+await testdriver.assert('loading spinner is not visible');
+
+// Verify content
+await testdriver.assert('page title is "Welcome"');
+await testdriver.assert('success message says "Account created"');
+await testdriver.assert('error message contains "Invalid email"');
+
+// Verify state
+await testdriver.assert('checkbox is checked');
+await testdriver.assert('dropdown shows "United States"');
+await testdriver.assert('button is disabled');
+
+// Verify visual appearance
+await testdriver.assert('submit button is blue');
+await testdriver.assert('form has red border');
+```
+
+<Info>Assertions are not cached and always re-evaluated to ensure accuracy.</Info>

package/docs/v7/mcp.mdx

@@ -0,0 +1,9 @@
+---
+title: "GitHub Copilot Guide"
+sidebarTitle: "GitHub Copilot Guide"
+description: "Execute natural language tasks using AI"
+icon: "github"
+---
+
+## Overview
+

package/docs/v7/mouse-down.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/mouse-up) to complete the gesture
+- The mouse button remains pressed until `mouseUp()` is called
+- Use [`hover()`](/v7/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/mouse-up) - Release the mouse button
+- [`hover()`](/v7/hover) - Move mouse to element
+- [`click()`](/v7/click) - Full click (mouseDown + mouseUp)
+- [`doubleClick()`](/v7/double-click) - Double-click on element
+- [`rightClick()`](/v7/right-click) - Right-click for context menu

package/docs/v7/mouse-up.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/mouse-down). 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/mouse-down) 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/click) instead of mouseDown/mouseUp pair
+
+## Related Methods
+
+- [`mouseDown()`](/v7/mouse-down) - Press mouse button without releasing
+- [`hover()`](/v7/hover) - Move mouse to element
+- [`click()`](/v7/click) - Complete click (mouseDown + mouseUp)
+- [`doubleClick()`](/v7/double-click) - Double-click on element
+- [`rightClick()`](/v7/right-click) - Right-click for context menu