@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/mouse-down.mdx

@@ -1,161 +1,84 @@
 ---
-title: "mouseDown"
-description: "Press the mouse button without releasing it"
+title: "mouseDown()"
+sidebarTitle: "mouseDown"
+description: "Press and hold the left mouse button on an element, to start a drag."
 icon: "arrow-pointer"
 ---
 
-## Overview
-
-The `mouseDown()` method pushes the mouse button at the location of an element. It does not release the button. Use this for drag operations, custom gestures, or when you need precise control of the mouse events. You can call it on an [`Element`](/core-concepts/elements) instance. Or you can use it with a selector.
-
-## Syntax
+Press the left mouse button on an element and keep it held down. Use it with [`hover()`](/hover) and [`mouseUp()`](/mouse-up) to drag and drop:
 
 ```javascript
-// Mouse down on an element
-await element.mouseDown();
-
-// Mouse down using a selector
-await ai.mouseDown('selector');
+await testdriver.find('Task card titled "Write docs"').mouseDown();
+await testdriver.find('Done column').hover();
+await testdriver.find('Done column').mouseUp();
 ```
 
-## Parameters
+## element.mouseDown()
 
-When called on an `Element`, no parameters are required.
+Moves the mouse to the point where [`find()`](/find) located the element, then presses the left button. The button stays down until you call `mouseUp()`. It's the same as `element.click('mouseDown')`.
 
-When called directly on the AI client:
+```typescript
+element.mouseDown(): Promise<void>
+```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `selector` | `string` | The selector describing the element where the mouse button should be pressed |
+It takes no parameters.
 
-## Returns
+### Errors
 
-It returns a `Promise<void>`. The promise resolves when TestDriver pushes the mouse button.
+Throws an `ElementNotFoundError` if `find()` didn't locate the element. See [click()](/click#errors) for how to check `found()` first.
 
-## Examples
+## Press at coordinates
 
-### Basic Drag Operation
+The client has no `mouseDown()` method. To press the button at a point on the screen, pass `action: 'mouseDown'` to [`testdriver.click()`](/click#testdriver-click-options):
 
 ```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();
+await testdriver.click({ x: 200, y: 300, action: 'mouseDown' });
+await testdriver.click({ x: 600, y: 300, action: 'mouseUp' });
 ```
 
-### Drag and Drop with Direct Selectors
+Prefer the element methods, which keep working when the layout or screen size changes.
 
-```javascript
-await ai.mouseDown('draggable card');
-await ai.hover('drop zone');
-await ai.mouseUp();
-```
+## Examples
 
-### Selecting Multiple Items
+### Reorder a list
 
 ```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');
-});
+await testdriver.find('drag handle on the first task in the list').mouseDown();
+await testdriver.find('the third task in the list').mouseUp();
 ```
 
-### Custom Drawing Application
+### Draw on a canvas
 
 ```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();
-});
+await testdriver.find('top-left corner of the drawing canvas').mouseDown();
+await testdriver.find('center of the drawing canvas').hover();
+await testdriver.find('bottom-right corner of the drawing canvas').mouseUp();
 ```
 
-### Long Press Gesture
+## Complete example
 
-```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();
-});
-```
+```javascript tests/drag-and-drop.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-### Resizing UI Elements
+describe('Drag and drop', () => {
+  it('moves a task to the Done column', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://your-app.example.com/board' });
 
-```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);
+    await testdriver.find('Task card titled "Write docs"').mouseDown();
+    await testdriver.find('Done column').hover();
+    await testdriver.find('Done column').mouseUp();
+
+    const result = await testdriver.assert('the "Write docs" card is in the Done column');
+    expect(result).toBe(true);
+  });
 });
 ```
 
-## Important Notes
-
-- Always pair `mouseDown()` with [`mouseUp()`](/mouse-up) to complete the gesture
-- The mouse button remains pressed until `mouseUp()` is called
-- Use [`hover()`](/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
+## Related
 
-- [`mouseUp()`](/mouse-up) - Release the mouse button
-- [`hover()`](/hover) - Move mouse to element
-- [`click()`](/click) - Full click (mouseDown + mouseUp)
-- [`doubleClick()`](/double-click) - Double-click on element
-- [`rightClick()`](/right-click) - Right-click for context menu
+- [mouseUp()](/mouse-up): release the button
+- [hover()](/hover): move the mouse while the button is down
+- [click()](/click): a full press and release
+- [Perform actions](/performing-actions): every kind of action in one guide

package/docs/mouse-up.mdx

@@ -1,164 +1,82 @@
 ---
-title: "mouseUp"
-description: "Release the mouse button"
+title: "mouseUp()"
+sidebarTitle: "mouseUp"
+description: "Release the left mouse button on an element, to finish a drag."
 icon: "arrow-pointer"
 ---
 
-## Overview
-
-The `mouseUp()` method releases the mouse button. It completes a drag operation or a custom mouse gesture that you started with [`mouseDown()`](/mouse-down). Call it without parameters to release the button at the present mouse position.
-
-## Syntax
+Release the mouse button you pressed with [`mouseDown()`](/mouse-down). Call it on the element where the drag should end:
 
 ```javascript
-// Release mouse button at current position
-await ai.mouseUp();
+await testdriver.find('Task card titled "Write docs"').mouseDown();
+await testdriver.find('Done column').mouseUp();
 ```
 
-## Parameters
+## element.mouseUp()
 
-None. The mouse button is released at the current cursor position.
+Moves the mouse to the point where [`find()`](/find) located the element, then releases the left button. Because the mouse moves before the release, the app sees a drag rather than a jump. It's the same as `element.click('mouseUp')`.
 
-## Returns
+```typescript
+element.mouseUp(): Promise<void>
+```
 
-It returns a `Promise<void>`. The promise resolves when TestDriver releases the mouse button.
+It takes no parameters.
 
-## Examples
+### Errors
 
-### Complete Drag and Drop
+Throws an `ElementNotFoundError` if `find()` didn't locate the element. See [click()](/click#errors) for how to check `found()` first.
 
-```javascript
-// Start dragging
-await ai.mouseDown('file to drag');
+## Release at coordinates
 
-// Move to drop location
-await ai.hover('target folder');
+The client has no `mouseUp()` method. To release the button at a point on the screen, pass `action: 'mouseUp'` to [`testdriver.click()`](/click#testdriver-click-options):
 
-// Complete the drop
-await ai.mouseUp();
+```javascript
+await testdriver.click({ x: 600, y: 300, action: 'mouseUp' });
 ```
 
-### Selecting Multiple Files
+Prefer `element.mouseUp()`, which keeps working when the layout or screen size changes.
 
-```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');
-});
-```
+## Examples
 
-### Drawing Application
+### Drop a file into an upload area
 
 ```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();
-});
+await testdriver.find('invoice.pdf in the file list').mouseDown();
+await testdriver.find('Drop files here area').hover();
+await testdriver.find('Drop files here area').mouseUp();
 ```
 
-### Resizing Window Panels
+### Resize a panel
 
 ```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);
-});
+await testdriver.find('divider between the sidebar and the editor').mouseDown();
+await testdriver.find('middle of the editor area').mouseUp();
 ```
 
-### Drag to Reorder List Items
+## Complete example
 
-```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');
-});
-```
+```javascript tests/drag-and-drop.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-### Text Selection with Mouse
+describe('Drag and drop', () => {
+  it('moves a task to the Done column', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://your-app.example.com/board' });
 
-```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');
+    await testdriver.find('Task card titled "Write docs"').mouseDown();
+    await testdriver.find('Done column').hover();
+    await testdriver.find('Done column').mouseUp();
+
+    const result = await testdriver.assert('the "Write docs" card is in the Done column');
+    expect(result).toBe(true);
+  });
 });
 ```
 
-## Important Notes
-
-- `mouseUp()` must be preceded by [`mouseDown()`](/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()`](/click) instead of mouseDown/mouseUp pair
-
-## Related Methods
+## Related
 
-- [`mouseDown()`](/mouse-down) - Press mouse button without releasing
-- [`hover()`](/hover) - Move mouse to element
-- [`click()`](/click) - Complete click (mouseDown + mouseUp)
-- [`doubleClick()`](/double-click) - Double-click on element
-- [`rightClick()`](/right-click) - Right-click for context menu
+- [mouseDown()](/mouse-down): press the button
+- [hover()](/hover): move the mouse while the button is down
+- [click()](/click): a full press and release
+- [Perform actions](/performing-actions): every kind of action in one guide