t.dragToElement Method

Drags an element onto another web page element.

t.dragToElement( selector, destinationSelector [, options] )
Parameter Type Description
selector Function | String | Selector | Snapshot | Promise Identifies the webpage element being dragged. See Select Target Elements.
destinationSelector Function | String | Selector | Snapshot | Promise Identifies the webpage element that serves as the drop location. See Select Target Elements.
options (optional) Object A set of options that provide additional parameters for the action. See Options.

This sample shows how to drop an element into a specific area using the t.dragToElement action.

import { ClientFunction } from 'testcafe';

fixture `My fixture`
    .page `http://www.example.com/`;

const designSurfaceItems = Selector('.design-surface').find('.items');

test('Drag an item from the toolbox', async t => {
    await t
        .dragToElement('.toolbox-item.text-input', '.design-surface')
        .expect(designSurfaceItems.count).gt(0);
});

You can drag an element to a specified offset with the t.drag method.

Select Target Elements

For actions that target DOM elements, use the selector parameter to identify the desired element.

You can pass any of the following objects as a selector.

  • A CSS selector string.

    test('My Test', async t => {
    
        // Click will be performed on the first element
        // that matches the CSS selector.
        await t.click('#submit-button');
    });
    
  • A selector.

    import { Selector } from 'testcafe';
    
    fixture `My fixture`
        .page `http://www.example.com/`;
    
    const lastItem = Selector('.toc-item:last-child');
    
    test('My Test', async t => {
    
        // Click will be performed on the element selected by
        // the 'getLastItem' selector.
        await t.click(lastItem);
    });
    
  • A client-side function that returns a DOM element.

    test('My Test', async t => {
    
        // Click will be performed on the element returned by the function,
        // which is the third child of the document's body.
        await t.click(() => document.body.children[2]);
    });
    
  • A DOM node snapshot.

    import { Selector } from 'testcafe';
    
    fixture `My fixture`
        .page `http://www.example.com/`;
    
    test('My Test', async t => {
        const topMenuSnapshot = await Selector('#top-menu');
    
        // Click will be performed on the element whose snapshot
        // is specified. This is an element with the '#top-menu' ID.
        await t.click(topMenuSnapshot);
    });
    
  • A Promise returned by a selector.

    import { Selector } from 'testcafe';
    
    const submitButton = Selector('#submit-button');
    
    fixture `My fixture`
        .page `http://www.example.com/`;
    
    test('My Test', async t => {
    
        // Click will be performed on the element specified by the selector
        // as soon as the promise is resolved.
        await t.click(submitButton());
    });
    

Before executing an action, TestCafe waits for the target element to appear in the DOM and become visible. If this does not happen within the selector timeout, the test fails.

Note that TestCafe cannot interact with page elements under other elements. If the target element is not on top when an action is triggered, TestCafe waits for this element to appear in the foreground. If this does not happen within the selector timeout, the action is performed with an overlaying element. For information on why the target element can be overlaid, see the stacking description in the z-index topic.

Upload action is the only method that does not require the target input to be visible. You can also perform the upload action when the input is overlaid.

Options

{
    modifiers: {
        ctrl: Boolean,
        alt: Boolean,
        shift: Boolean,
        meta: Boolean
    },

    offsetX: Number,
    offsetY: Number,
    destinationOffsetX: Number,
    destinationOffsetY: Number,
    speed: Number
}
Parameter Type Description Default
ctrl, alt, shift, meta Boolean Indicate which modifier keys are to be pressed during the drag action. false
offsetX, offsetY Number Mouse pointer coordinates that define a point where dragging is started. If an offset is a positive integer, coordinates are calculated relative to the top-left corner of the target element. If an offset is a negative integer, they are calculated relative to the bottom-right corner. The center of the target element.
destinationOffsetX, destinationOffsetY Number Mouse pointer coordinates that define a point where dragging is finished. If an offset is a positive integer, coordinates are calculated relative to the top-left corner of the destination element. If an offset is a negative integer, they are calculated relative to the bottom-right corner. The center of the destination element.
speed Number The speed of action emulation. Defines how fast TestCafe performs the action when running tests. A number between 1 (the maximum speed) and 0.01 (the minimum speed). If test speed is also specified in the CLI, API or in test code, the action speed setting overrides test speed. 1

Example

import { Selector } from 'testcafe';

const fileIcon      = Selector('.file-icon');
const directoryPane = Selector('.directory');

fixture `My Fixture`
    .page `https://example.com/`;

test('My Test', async t => {
    await t
        .dragToElement(fileIcon, directoryPane, {
            offsetX: 10,
            offsetY: 10,
            destinationOffsetX: 100,
            destinationOffsetY: 50,
            modifiers: {
                shift: true
            }
        });
});