Draggable actions

A draggable element can be selected by the user with a mouse, dragged to a droppable element, and dropped by releasing the mouse button.

Draggable element declaration

A draggable element must include draggable in its type property. In this example, one element is just draggable, but usually an element is both clickable and draggable because a user needs to click before they can drag.

{
  "elements" : [
    {
      "name" : "onlyDraggable",
      "type" : [ "draggable" ],
      "selector" : {
        "css" : ".drag-me"
      },
      "public" : true
    },
    {
      "name" : "myDraggable",
      "type" : [ "clickable", "draggable" ],
      "selector" : {
        "css" : ".drag-me-too"
      },
      "public" : true
    }
  ]
}

DragAndDrop API

The draggable type exposes the following API for an element:

• dragAndDrop(target: Element, hold: number) clicks and drags an element to the location of the target element, then drops. The target element is provided as a parameter and doesn't have to be draggable.

A second optional parameter defines a hold duration in seconds that is applied after the click and before the drag. This hold duration can be useful to simulate a real user in some cases.

Usage in a JavaScript test:

const source = await pageObject.getMyDraggable();
const target = await pageObject.getDropTarget();
// drag and drop without hold
await source.dragAndDrop(target);

Usage in a Java test:

Draggable source = pageObject.getMyDraggable();
BasicElement target = pageObject.getDropTarget();
// drag and drop with 3 sec hold
source.dragAndDrop(target, 3);

• dragAndDropByOffset(xOffset: number, yOffset: number, hold: number) drops an element using coordinates relative to the current location of the element. It has an optional parameter for hold duration in seconds.

Usage in a JavaScript test:

const source = await pageObject.getMyDraggable();
// drag and drop with 3 sec hold
await source.dragAndDropByOffset(100, 100, 3);

Usage in a Java test:

Draggable source = pageObject.getMyDraggable();
// drag and drop without hold
source.dragAndDropByOffset(100, 100);

Compose dragAndDrop

It's a good practice to compose a UI interaction as a public method inside a page object. Here are some examples of how to compose dragAndDrop and dragAndDropByOffset and how to provide a target element as a parameter.

Drop at a known target element

The most common use case is to drop an element at a known target element location. To do that, we pass elementReference to a known element as an argument:

{
  "elements": [
    {
      "name" : "myDraggable",
      "type" : ["draggable"],
      "selector": { "css": ".foo" }
    },
    {
      "name" : "dropTarget",
      "selector": { "css": ".moo" }
    }
  ],
  "methods": [
    {
      "name": "dragAndDropAtTarget",
      "compose": [
        {
          "element" : "myDraggable",
          "apply": "dragAndDrop",
          "args": [
            {
              "type": "elementReference",
              "value": "dropTarget"
            }
          ]
        }
      ]
    }
  ]
}

The generated method declarations have no parameters because the target element is referenced inside the statement of the dragAndDropAtTarget method.

Generated JavaScript method declaration:

dragAndDropAtTarget(): Promise<unknown>;

Generated Java method declaration:

public void dragAndDropAtTarget();

Drop at a known target element with hardcoded arguments

It's possible that the target element needs arguments for the selector or filter. Those arguments can be hardcoded in a compose statement. This example passes a hardcoded myClass value to the dropTarget in the dragAndDropAtTarget method.

{
  "elements": [
    {
      "name" : "myDraggable",
      "type" : ["draggable"],
      "selector" : { "css": ".foo" }
    },
    {
      "name" : "dropTarget",
      "selector" : {
        "css" : "target[class='%s']",
        "args" : [
          {
            "name" : "classStr",
            "type" : "string"
          }
        ]
      }
    }
  ],
  "methods": [
    {
      "name": "dragAndDropAtTarget",
      "compose": [
        {
          "element" : "myDraggable",
          "apply" : "dragAndDrop",
          "args" : [
            {
              "type" : "elementReference",
              "value" : "dropTarget",
              "args" : [
                { "value" : "myClass" }
              ]
            }
          ]
        }
      ]
    }
  ]
}

If we omitted the "value" : "myClass" hardcoded value for the dropTarget element, it would be inferred and added to the method parameters.

JavaScript example:

dragAndDropAtTarget(classStr: string): Promise<unknown>;

Java example:

public void dragAndDropAtTarget(String classStr);

Drop by offset inside a frame

It's always more reliable to dragAndDrop with a target element as shown in the previous section. However, that's not possible if the target element is inside a frame. Here's an example for Java:

// get source element coordinates
ElementRectangle source = sourceElement.getRect();

// enter frame and get target coordinates
MyPageObject targetPageObjectInsideFrame = utam.enterFrameAndLoad(frameElement, MyPageObject.class);
ElementRectangle target = targetPageObjectInsideFrame.getTargetElement().getRect();
utam.exitFrame();

// offset is a difference between element centers
int xOffset = (target.getX() + target.getWidth()/2) - (source.getX() + source.getWidth()/2);
int yOffset = (target.getY() + target.getHeight()/2) - (source.getY() + source.getHeight()/2);

// drag and drop with a 5 second pause
source.dragAndDropByOffset(xOffset, yOffset, 5);

We don't show JavaScript code here but it's similar and uses the same methods.