Drag and drop
Drag a task or list item onto its destination and check the result.
Use dragTo() to move a card between columns or sort a list by its handle. This guide shows how to choose a destination, prepare the page and check that the app accepted the move.
Move a task Link to Move a task
Call dragTo() on the source locator and pass the destination locator. On the task app's board, this moves the release-notes card into Done, then checks its new location.
import { expect, test } from '@rehearsal-labs/retest'test('moves release notes to done', async ({ page }) => { await page.goto('/drag') const done = page.getByTestId('done-column') await page.getByText('Write release notes').dragTo(done) await expect(done.getByText('Write release notes')).toBeVisible()})The drag goes from the source's centre to the destination's centre. Its completion does not prove that the app accepted or saved the move, so check the outcome afterwards.
Both locators must find one element on the same page. No match waits until the action budget expires, while several matches fail immediately with ambiguous.
Prepare the drag Link to Prepare the drag
Before pressing the mouse, Retest checks that the source is visible, stable, enabled and not covered. The destination must be visible, stable and uncovered at its centre, and both elements must fit in the viewport together.
Retest does not scroll while dragging. If both elements cannot fit in view together, change the viewport or prepare the page before calling dragTo().
A covered destination fails with not_actionable and names the covering element. A locator with no match eventually fails with not_found; these readiness failures send no input, so fix the locator or page state before trying again.
HTML and mouse drags Link to HTML and mouse drags
The same method handles HTML drag and drop and controls that follow mouse movement themselves. When a page begins an HTML drag, Retest carries its drag data through the browser's drag events to the drop handler.
For a mouse-driven control, Retest holds the button while moving in a straight line, then releases it at the destination. The default is five movement steps; increase steps if your list needs more movement events.
await page.goto('/drag')await page.getByTestId('handle').dragTo(page.getByTestId('slot-3'), { steps: 10 })await expect(page.getByTestId('order')).toHaveText('alpha in slot-3')This moves the sortable list's handle to its third slot and checks the resulting order. steps must be a whole number from 1 to 100; it controls movement events rather than repeating the drag.
When a drag fails Link to When a drag fails
A page may move the destination while the mouse travels. Retest reads it again before the drop and moves to its new centre, but it cannot complete a drop onto an element that has left the page.
If the destination disappears after the press, the action fails with not_actionable and records inputSent: true. Retest cancels an HTML drag or releases a mouse drag where it stopped, and the failure says which happened.
A timeout after the press also records that input was sent and ends the drag. Read the app's resulting state before deciding to run another move, because a mouse release may already have changed the list.
The report shows the source and destination in one drag step. For an HTML drag, it adds "through drag events", which helps you tell how the browser delivered the drop when debugging a failure.
Platform support Link to Platform support
dragTo() works on Chromium-family browsers and Electron. Firefox and WebKit refuse it with unsupported.
A drag from or to an element inside a frame is also unsupported, as is a drag on a page emulating a touch screen. This method uses the mouse; it is not a gesture API for iOS simulator or macOS native apps.