testdriver:hover

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

await element.hover()

Returns

Promise<void>

Examples

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

await testdriver.hover(x, y)

Parameters

Returns

Promise<void>

Examples

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

// ✅ Preferred
const icon = await testdriver.find('info icon');
await icon.hover();

// ❌ Avoid
await testdriver.hover(500, 300);

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();

const element = await testdriver.find('tooltip trigger');
if (!element.found()) {
  throw new Error('Element not found');
}
await element.hover();

Use Cases

await new Promise(r => setTimeout(r, 1000));

// Read tooltip content
const tooltipText = await testdriver.extract('the tooltip text');
console.log('Tooltip:', tooltipText);
```

// Wait for dropdown animation
await new Promise(r => setTimeout(r, 500));

// Click submenu option
const category = await testdriver.find('Electronics category');
await category.click();
```

await new Promise(r => setTimeout(r, 800));

// Verify preview appears
await testdriver.assert('product preview is displayed');
```

await new Promise(r => setTimeout(r, 500));

// Verify hover effect
await testdriver.assert('button background changed to blue');
```

// Hover over drop zone
const dropZone = await testdriver.find('drop area');
await dropZone.hover();

await new Promise(r => setTimeout(r, 300));
await dropZone.mouseUp();
```

Complete Example

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() - Locate elements to hover
• click() - Click after hovering
• mouseDown() - Start drag operations