> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testdriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# hover-image

> Locate an image on the screen and perform an action.

<div className="replay-block">
  <iframe src="https://app.dashcam.io/replay/6866b26c07fd82bc6701f6a5?share=p5XLOhNUkE7FcGi2Nu2pZQ&embed=true&timestamp=90000&playbackRate=5" width="1000" height="350" />
</div>

```yaml testdriver/hover-image.yaml highlight={9-11} theme={null}
version: 6.0.0
steps:
  - prompt: login
    commands:
      - command: run
        file: testdriver/snippets/login.yaml
  - prompt: click on the image of a shopping cart
    commands:
      - command: hover-image
        description: shopping cart icon next to the Cart text in the top right corner
        action: click
  - prompt: assert that you see an empty shopping cart
    commands:
      - command: assert
        expect: Your cart is empty
```

## Description

The `hover-image` command is used to locate an image on the screen based on a description and perform an action on it. This can include hovering, clicking, double-clicking or dragging the image.

## Arguments

| Argument      | Type     | Description                                                                                                                                                                       |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `description` | `string` | A description of the image and what it represents. Don't include the image itself here.                                                                                           |
| `action`      | `string` | The action to take when the image is found. Available actions are: `click`, `right-click`, `double-click`, `hover`. Also supports `drag-start` and `drag-end` for dragging images |

The `hover-image` command is useful for interacting with visual elements that can't be identified using text-based selectors.

***

## Drag functionality

* The `drag-start` and `drag-end` actions are used to drag an image to a specific location. `drag-start` could be the image (or inner text element, in which case using `hover-text` is preferred) to drag and `drag-end` is the location is supposed to be dragged to. This could be coupled with [`hover-text`](/commands/hover-text) or [`match-image`](/commands/match-image) or just `hover-image`.

### Example: Drag and Drop to upload an image

```yaml drag-and-drop.yaml theme={null}
version: 6.0.0
steps:
  - prompt: click on the image of a shopping cart
    commands:
      - command: hover-image
        description: a pink tree image in the file explorer
        action: drag-start
      - command: hover-text
        text: Upload
        description: The drop zone of the application
        action: drag-end
```

***

## Example usage

```yaml theme={null}
command: hover-image
description: search icon in the webpage content
action: click
```

## Protips

* Use clear and concise descriptions for the image to improve detection accuracy.
* Ensure the action specified matches the intended interaction with the image.
* If the hover-image command fails to locate an image based on the provided description, consider using the match-image command instead. The match-image command is specifically designed for scenarios where precise image matching is required, such as when the visual element can't be reliably described with text. It works by directly comparing the image on the screen with a reference image file.

## Gotchas

* If the image can't be located based on the description, the command will fail.
* Ensure the screen resolution and scaling settings are consistent to avoid detection issues.