t.drag Method

Drags an element to a specified offset. Chainable.

t.drag(selector, dragOffsetX, dragOffsetY [, options]) → this | Promise<any>

Parameter	Type	Description
selector	Function | String | Selector | Snapshot | Promise	The target page element (See Select Target Elements).
dragOffsetX	Number	An X-offset of the drop coordinates from the mouse pointer’s initial position.
dragOffsetY	Number	An Y-offset of the drop coordinates from the mouse pointer’s initial position.
options (optional)	Object	Additional action options (see Options).

The following example demonstrates how to use the t.drag action with a slider:

import { Selector } from 'testcafe';

const slider = Selector('.ui-slider-handle');

fixture`TestController.drag`
    .page`https://devexpress.github.io/testcafe/example/`;

test('Drag slider', async t => {
    const sliderValue = await getSliderValue();

    await t
        .expect(sliderValue).eql(1)
        .click('#tried-test-cafe')
        .drag(slider, 360, 0, { offsetX: 10, offsetY: 10 });

    const newSliderValue = await getSliderValue();

    await t.expect(newSliderValue).eql(5);
});

You can use the t.dragToElement method to drag an element onto another element on the page.

Select Target Elements

Use the selector parameter to identify the target of a DOM event.

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

• A CSS selector string.

  test('Click submit', 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`Parameter as Selector`
      .page`https://devexpress.github.io/testcafe/example/`;
  
  const lastCheckbox = Selector('fieldset p:last-child [type="checkbox"]');
  
  test('Click last checkbox', async t => {
  
      // Click will be performed on the element selected by
      // the 'getLastItem' selector.
      await t.click(lastCheckbox);
  });
  

• A client-side function that returns a DOM element.

  test('Click first child of the body', 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[0]);
  });
  

• A DOM node snapshot.

  import { Selector } from 'testcafe';
  
  fixture`Parameter as DOM node snapshot`
      .page`https://devexpress.github.io/testcafe/example/`;
  
  test('Click preferred interface', async t => {
      const preferredInterface = await Selector('#preferred-interface');
  
      // Click will be performed on the element whose snapshot
      // is specified. This is an element with the '#preferred-interface' ID.
      await t.click(preferredInterface);
  });
  

• A Promise returned by a selector.

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

TestCafe waits for the target element to become visible before it executes an action. If this does not happen within the selector timeout, the test fails.

TestCafe cannot interact with background elements. If a different element overlaps the action target, TestCafe waits for this element to disappear. If this does not happen within the selector timeout, TestCafe performs the action with the element on top of the original target. Learn more about stacking and z-index on MDN.

Options

Mouse action options are used in t.drag and t.hover actions.

export interface MouseOptions {
    modifiers: {
        ctrl: boolean;
        alt: boolean;
        shift: boolean;
        meta: boolean;
    };

    offsetX: number;
    offsetY: number;
    speed: number;
}

Parameter	Type	Description	Default
ctrl, alt, shift, meta	Boolean	Indicate which modifier keys are to be pressed during the mouse action.	false
offsetX, offsetY	Number	Mouse pointer coordinates that define a point where the action is performed or 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.
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 sliderHandle = Selector('.ui-slider-handle');

fixture`Mouse options`
    .page`https://devexpress.github.io/testcafe/example/`;

test('Set an estimate', async t => {
    await t
        .click('#tried-test-cafe')
        .drag(sliderHandle, 360, 0, {
            offsetX:   10,
            offsetY:   10,
            modifiers: {
                shift: true,
            },
        });
});