> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/recording-tests-steps/recording-drag-and-drop.md).

# Recording drag & drop

How BugBug records and runs drag and drop: what is recorded, the drag and drop points, range sliders, sortable lists built on mouse events, and how to fix DRAG\_AND\_DROP\_FAILED.

BugBug records drag and drop automatically. Press the mouse button on an element, move it at least 20 pixels and release it: BugBug saves a **Drag & drop** step. You don't need to turn on any mode.

{% hint style="info" %}
**In short**

* A drag of 20 pixels or more is recorded as a **Drag & drop** step with two elements: the dragged element and the drop target.
* A native range slider (`<input type="range">`) is recorded as a **Change value** step with the final value, not as drag and drop.
* When the app's drag doesn't react to the **Drag & drop** step, build it from **Press mouse button**, **Move** and **Release mouse button** steps.
* All fields of the step are described in [Actions](https://docs.bugbug.io/editing-tests/actions.md#drag-and-drop-beta).
  {% endhint %}

## What is recorded

| You do                                                  | BugBug records                                                                    |
| ------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Press, move 20 px or more, release                      | **Drag & drop**, with the element you pressed and the element you released it on. |
| Press, move less than 20 px, release                    | A click.                                                                          |
| Drag a native range slider                              | **Change value** with the slider's final value.                                   |
| Select text with the mouse, or drag inside a `<select>` | Nothing extra. These are not treated as drag and drop.                            |

For a recorded step, BugBug saves two points:

* **Drag point**: where you pressed, as pixels from the top-left corner of the dragged element.
* **Drop point**: where the center of the dragged element was when you released it, as pixels from the top-left corner of the drop target.

Both are saved as the **Custom** position, so the test drags and drops at the same spots as you did.

## How the step runs

1. BugBug finds the dragged element and moves the mouse to the drag point.
2. It finds the drop target and calculates the drop point.
3. It presses the left mouse button at the drag point, moves the mouse to the drop point in 20 small moves over about 200 ms, and releases the button there.
4. The step passes when the page receives the release (`drop`, `mouseup` or `pointerup`) at the drop point.

## Add a Drag & drop step manually

{% hint style="warning" %}
Drag & drop is in **beta**. If it doesn't work with your app, use the [three-step drag](#when-drag-and-drop-doesnt-work-with-your-app).
{% endhint %}

Add a **Drag & drop** step and set:

| Setting in the app               | YAML                                                        | Description                                                                                                                                 |
| -------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Drag element**                 | `selector`                                                  | The element you grab.                                                                                                                       |
| **Drag element: click position** | `interaction_position`, `dnd_drag_x`, `dnd_drag_y`          | Where to press on the dragged element. With **Custom position**, the X and Y are the distance in pixels from the element's top-left corner. |
| **Drop on element**              | `drop_selector`                                             | The element to drop on.                                                                                                                     |
| **Drop position in element**     | `dnd_drop_interaction_position`, `dnd_drop_x`, `dnd_drop_y` | Where to release on the drop target. With **Custom position**, the X and Y are the distance in pixels from the element's top-left corner.   |

The positions take the same values as other mouse actions: `smart`, `custom`, `topLeft`, `topCenter`, `topRight`, `middleLeft`, `middleCenter`, `middleRight`, `bottomLeft`, `bottomCenter`, `bottomRight`.

```yaml
- action: dragAndDrop
  action_details:
    selector: "xpath=//*[@data-testid='card-1']"
    drop_selector: "xpath=//*[@data-testid='done-column']"
    dnd_drag_on: element
    dnd_drop_on: element
    interaction_position: custom
    dnd_drag_x: 10
    dnd_drag_y: 10
    dnd_drop_interaction_position: custom
    dnd_drop_x: 40
    dnd_drop_y: 20
```

### Which element to select

* **Element to drag**: the element that reacts to pressing the mouse button, usually the card, row or drag handle itself. If the app has a dedicated handle icon, select the handle.
* **Drop target**: an element that is on the page before the drag starts, for example the column, list or drop zone. Don't select a placeholder that appears only during the drag.

### Custom sliders

For a slider built from `div` elements, drag the handle and drop it on the slider track. Set the drop position to **Custom** and use `dnd_drop_x` to choose how far along the track to release, in pixels from the track's left edge.

## When Drag & drop doesn't work with your app

Some drag libraries, for example sortable lists in jQuery UI, need a slower movement or a mouse button that stays pressed during several moves. Build the drag from three steps instead:

1. **Press mouse button** (`mouseDown`) on the element to drag.
2. **Move** (`mouseMove`) to the drop target, with the left mouse button held (`mouse_buttons: [left]`) and several intermediate moves (`mouse_move_steps`).
3. **Release mouse button** (`mouseUp`) on the drop target.

```yaml
- action: mouseDown
  action_details:
    selector: "xpath=//li[normalize-space(text())='Item 1']"
- action: mouseMove
  action_details:
    selector: "xpath=//li[normalize-space(text())='Item 3']"
    mouse_buttons:
      - left
    mouse_move_steps: 10
- action: mouseUp
  action_details:
    selector: "xpath=//li[normalize-space(text())='Item 3']"
```

To move to a point instead of an element, set `is_target_document: true` with `client_x` and `client_y` on the **Move** step. The coordinates are in pixels from the top-left corner of the viewport.

## Troubleshooting

| Problem                                       | What to do                                                                                                                                                                                                                                                                                       |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DRAG_AND_DROP_FAILED`                        | The page didn't receive the release at the drop point before the step's [timeout](https://docs.bugbug.io/preventing-failed-tests/timeout.md). Check the screenshot: is the drop target where you expect it? Try another drop position, or use the three-step drag above.                         |
| `EVENT_DISPATCHED_ON_INVALID_ELEMENT`         | Another element received the mouse event, for example a modal or sticky header on top. Close or wait for it in an earlier step.                                                                                                                                                                  |
| `ELEMENT_REMOVED`                             | The element BugBug was working with was removed from the page during the step, for example because the app replaces the dragged element with a copy when the drag starts. Try the three-step drag above, with the drop target as the element of the **Move** and **Release mouse button** steps. |
| The element doesn't move, but the step passes | The app ignores this kind of drag. Use the three-step drag above and increase `mouse_move_steps`.                                                                                                                                                                                                |

See also [Error codes](https://docs.bugbug.io/debugging-tests/error-codes.md).

## FAQ

<details>

<summary>Does BugBug record drag and drop?</summary>

Yes. A drag of 20 pixels or more is recorded as a **Drag & drop** step automatically. Native range sliders are recorded as **Change value** steps.

</details>

<details>

<summary>How do I move a range slider?</summary>

For a native `<input type="range">`, use a **Change value** step with the new value. That's also what the recorder saves. For a custom slider, drag the handle and drop it on the track with a **Custom** drop position, or, if the slider supports arrow keys, use a **Type text** step on the handle with `{right}` or `{left}` (see [Using keyboard shortcuts](https://docs.bugbug.io/recording-tests-steps/using-keyboard-shortcuts.md#pressing-keys-in-a-test)).

</details>

<details>

<summary>What do dnd_drag_x, dnd_drag_y, dnd_drop_x and dnd_drop_y mean?</summary>

With the **Custom** position, they are pixels from the top-left corner of the element: `dnd_drag_x` and `dnd_drag_y` on the dragged element, `dnd_drop_x` and `dnd_drop_y` on the drop target. With other positions they are ignored.

</details>

<details>

<summary>Can I drag to a point in the viewport instead of an element?</summary>

Use **Press mouse button**, **Move** with `is_target_document: true`, `client_x` and `client_y`, and **Release mouse button**. The Move coordinates are in pixels from the top-left corner of the viewport.

</details>

<details>

<summary>Why does Drag &#x26; drop fail with DRAG_AND_DROP_FAILED?</summary>

The page didn't receive the mouse release at the drop point before the timeout. Usually the drop target moved, is covered, or the app needs a slower drag. See [Troubleshooting](#troubleshooting).

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bugbug.io/recording-tests-steps/recording-drag-and-drop.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
