@testdriverai/agent 7.11.229-canary → 7.11.232-test

package/docs/hover.mdx

@@ -1,279 +1,106 @@
 ---
 title: "hover()"
 sidebarTitle: "hover"
-description: "Hover over elements or coordinates"
+description: "Move the mouse over an element or a point without clicking, to reveal tooltips and menus."
 icon: "hand-pointer"
 ---
 
-## Overview
-
-Move the mouse cursor onto elements or coordinates without a click. Use this to show tooltips, dropdowns, and hover effects.
-
-## Element Hover
-
-Put the cursor on a found element.
-
-### Syntax
+Move the mouse onto an element without clicking. Use it to reveal tooltips, dropdown menus and hover styles.
 
 ```javascript
-await element.hover()
+await testdriver.find('Products menu in the top navigation').hover();
+await testdriver.find('Laptops in the Products dropdown').click();
 ```
 
-### Returns
+## element.hover()
 
-`Promise<void>`
-
-### Examples
-
-```javascript
-// Find and hover
-const tooltip = await testdriver.find('info icon');
-await tooltip.hover();
+Moves the mouse to the point where [`find()`](/find) located the element. It's the same as `element.click('hover')`.
 
-// Wait to see tooltip
-await new Promise(r => setTimeout(r, 1000));
+```typescript
+element.hover(): Promise<void>
+```
 
-// Hover over menu to reveal submenu
-const menu = await testdriver.find('Products menu');
-await menu.hover();
+It takes no parameters.
 
-const submenu = await testdriver.find('Laptops submenu item');
-await submenu.click();
-```
+### Errors
 
-## Coordinate Hover
+Throws an `ElementNotFoundError` if `find()` didn't locate the element. See [click()](/click#errors) for how to check `found()` first.
 
-Put the cursor at screen coordinates.
+## testdriver.hover(options)
 
-### Syntax
+Moves the mouse to a point on the screen by its coordinates. Prefer `element.hover()`, which keeps working when the layout or screen size changes.
 
-```javascript
-await testdriver.hover(x, y)
+```typescript
+testdriver.hover(options: { x: number; y: number }): Promise<void>
 ```
 
-### Parameters
-
-<ParamField path="x" type="number" required>
-  X coordinate
+<ParamField path="options" type="object" required>
+  <Expandable title="properties">
+    <ParamField path="x" type="number" required>
+      Distance from the left edge of the screen, in pixels.
+    </ParamField>
+    <ParamField path="y" type="number" required>
+      Distance from the top edge of the screen, in pixels.
+    </ParamField>
+  </Expandable>
 </ParamField>
 
-<ParamField path="y" type="number" required>
-  Y coordinate
-</ParamField>
+```javascript
+await testdriver.hover({ x: 640, y: 360 });
+```
 
-### Returns
+<Note>
+  The older form `testdriver.hover(x, y)` still works. Use the options object in new tests.
+</Note>
 
-`Promise<void>`
+## Examples
 
-### Examples
+### Read a tooltip
 
 ```javascript
-// Hover at coordinates
-await testdriver.hover(500, 300);
-
-// Hover and wait
-await testdriver.hover(500, 300);
-await new Promise(r => setTimeout(r, 1000));
+await testdriver.find('help icon next to the Password label').hover();
+const tooltip = await testdriver.extract('the text of the tooltip');
 ```
 
-## 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 a hover style
 
-<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
+```javascript
+await testdriver.find('Sign in button').hover();
+await testdriver.assert('the Sign in button is highlighted');
+```
 
-<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>
+### Drag an item
 
-## Complete Example
+`hover()` moves the mouse while the button is held down by [`mouseDown()`](/mouse-down):
 
 ```javascript
-import { beforeAll, afterAll, describe, it } from 'vitest';
-import TestDriver from 'testdriverai';
-
-describe('Hover Interactions', () => {
-  let testdriver;
+await testdriver.find('Task card titled "Write docs"').mouseDown();
+await testdriver.find('Done column').hover();
+await testdriver.find('Done column').mouseUp();
+```
 
-  beforeAll(async () => {
-    client = new TestDriver(process.env.TD_API_KEY);
-    await testdriver.auth();
-    await testdriver.connect();
-  });
+## Complete example
 
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
+```javascript tests/hover.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-  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);
-  });
+describe('Hover', () => {
+  it('highlights the sign in button on hover', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-  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');
-  });
+    await testdriver.find('Sign in button below the password field').hover();
 
-  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');
+    const result = await testdriver.assert('the mouse pointer is over the Sign in button');
+    expect(result).toBe(true);
   });
 });
 ```
 
-## Related Methods
+## Related
 
-- [`find()`](/find) - Locate elements to hover
-- [`click()`](/click) - Click after hovering
-- [`mouseDown()`](/click) - Start drag operations
+- [find()](/find): locate the element to hover over
+- [click()](/click): click after a menu opens
+- [mouseDown()](/mouse-down) and [mouseUp()](/mouse-up): drag and drop
+- [Perform actions](/performing-actions): every kind of action in one guide