Testdriver Hover

---
name: testdriver:hover
description: Hover over elements or coordinates
---
<!-- Generated from hover.mdx. DO NOT EDIT. -->

## 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

```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

Put the cursor at 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()`](/find) - Locate elements to hover
- [`click()`](/click) - Click after hovering
- [`mouseDown()`](/click) - Start drag operations