diff --git a/content/en/synthetics/browser_tests/test_steps.md b/content/en/synthetics/browser_tests/test_steps.md index a61e8518023..c14d4bcbebe 100644 --- a/content/en/synthetics/browser_tests/test_steps.md +++ b/content/en/synthetics/browser_tests/test_steps.md @@ -57,6 +57,27 @@ Datadog records steps you perform on your application, such as uploading, and a {{< img src="synthetics/browser_tests/upload_file_step.png" alt="Create an upload file step" style="width:70%;" >}} +### Drag and drop + +Datadog records drag and drop interactions you perform on your application as a step. A drag and drop interaction is billed as a single step in your browser test. + +Common use cases include: +- Dragging a widget into a dashboard +- Reordering filters +- Moving a card into a group +- Rearranging notebook elements + + +{{< img src="synthetics/browser_tests/drag_and_drop_step.mp4" alt="Drag and drop step recorded in a browser test" video="true" width="70%" >}} + +To record a drag and drop step, start the recorder and perform the drag and drop action in your application. The recorder detects the drag source and drop target and creates a single **Drag and Drop** step. + +After recording, you can review and edit the drag source element, drop target element, interaction points, and timing settings. + +For complex applications or non-native drag and drop implementations, see [Drag and drop](#drag-and-drop-1) in the Manually added steps section. + + + ## Manually added steps You can manually add and arrange steps on the left corner of the browser test recording. @@ -218,6 +239,49 @@ This step uses a dedicated click, not a hovering mechanism, to avoid generating Select **Hover** and click on an element to add a step. +#### Drag and drop + +Create this interaction step to simulate dragging an element from one location to another. This is useful when refining existing tests or when recording is not practical. + +1. Click **Add Step**. +2. Select **Interaction**. +3. Choose **Drag and Drop**. +4. Select the element to drag. +5. Select the element to drop onto. + + +{{< img src="synthetics/browser_tests/drag_and_drop_manual_step.png" alt="Drag and drop manual interaction step configuration" style="width:70%;" >}} + +Each drag and drop step includes the following options: + +* **Drag Step Target Element**: The element to be dragged. +* **Drop Step Target Element**: The element that receives the drop. +* **User Specified Locator** (optional): Override the detected element with a custom CSS or XPath selector. This is recommended in the following cases: + * **Ghost preview or drag overlay**: Some libraries create a floating clone of the dragged element. The recorder may capture this ghost element as the drop target. Because the worker does not physically move the mouse during execution, the test may attempt to drag to the ghost preview instead of the real container, resulting in inconsistent or failing steps. Manually edit the drop target to select the actual container element, or use a custom selector. + * **Nested DOM structures**: Draggable or droppable logic may be attached to a parent element while the cursor detects a deeply nested child. Some libraries prevent event bubbling or rely on specific classes or custom attributes, which can cause the recorder to capture the wrong element. Inspect the DOM and select the correct parent element. Look for library-defined classes or attributes that identify valid drag or drop targets. + * **Drop target detected as the dragged element**: In some cases, the same element is recorded as both the drag target and the drop target. If this happens, manually edit the drop target and select the intended destination element. +* **Interaction Point**: Defines where on the element the drag or drop occurs. Options: **Center** (default) or **Offset (Top-Left)**. +* **Delay before drag**: Time between pressing the mouse button and starting to move. +* **Delay before drop**: Time between reaching the target element and releasing the mouse button. Adjusting timing can improve reliability in complex or animated interfaces. + +**Note**: Some applications create the draggable element only after you hover over another element. Confirm this is not the case and add a **Hover** step before the drag and drop step if needed. + +**Native vs. custom drag and drop** + +Applications implement drag and drop in two ways: + +* **Native HTML5 drag and drop**: Uses standard browser drag events such as `dragstart`, `dragover`, and `drop`. +* **Custom mouse-based implementation**: Simulates drag and drop using pointer events such as `mousedown`, `mousemove`, and `mouseup`. Commonly used by libraries such as dnd-kit. + +The drag and drop step supports both approaches. For custom mouse-based implementations, target detection may be less reliable. In these cases, review the selected elements, interaction points, and timing configuration so the test accurately reproduces real user behavior. + +**Best practices** + +* Review recorded steps before saving using the step replayer. +* Use stable CSS or XPath selectors when possible. +* Adjust timing settings to reduce flakiness. +* Add a **Hover** step before the drag and drop step if your application creates the draggable element only after a hover interaction. + #### Scroll Browser tests automatically scroll to the elements that need to be interacted with. In most cases, you do not need to add a scroll step manually. Use the scroll step when you need to trigger an additional interaction, such as an infinite scroll.