Add the mouse_drag subroutine.

testapi.pm

@@ -1549,6 +1549,85 @@ sub mouse_hide(;$) {
     query_isotovideo('backend_mouse_hide', {offset => $border_offset});
 }
 
+=head2 mouse_drag
+  mouse_drag([$startpoint, $endpoint, $startx, $starty, $endx, $endy, $button, $timeout]);
+
+Click mouse C<$button>, C<'left'> or C<'right'>, at a given location, hold the button and drag 
+the mouse to another location where the button is released. You can set the C<$startpoint> 
+and C<$endpoint> by passing the name of the needle tag, i.e. the mouse drag happens between
+the two needle areas. Alternatively, you can set all the coordinates explicitly with C<$startx>,
+C<$starty>, C<$endx>, and C<$endy>. You can also set one point using a needle and another one
+using coordinates. Everything is fine when the location is correctly identifed. If both
+the coordinates and the needle are provided, the coordinates will be used to set up the
+locations and the needle location will be surpressed.
+
+=cut
+
+sub mouse_drag {
+        my %args = @_;
+        my $startx =
+        my $starty =
+        my $endx =
+        my $endy = 0;
+        # If full coordinates are provided, work with them as a priority,
+        if (defined $args{startx} and defined $args{starty}) {
+                $startx = $args{startx};
+                $starty = $args{starty};
+        }
+        # If the coordinates were not complete, use the needle as a fallback solution.
+        elsif (defined $args{startpoint}) {
+                my $startmatch = $args{startpoint};
+                # Check that the needle exists.
+                my $start_matched_needle = assert_screen($startmatch, $args{timeout});
+                # Calculate the click point from the area defined by the needle (take the center of it)
+                my $start_area = $start_matched_needle->{area}->[-1];
+                my $start_click_point = {
+                        xpos => $start_area->{w} / 2,
+                        ypos => $start_area->{h} / 2,
+                };
+                $startx = int($start_area->{x} + $start_click_point->{xpos});
+                $starty = int($start_area->{y} + $start_click_point->{ypos});
+        }
+        # If neither coordinates nor a needle is provided, report an error and quit.
+        else {
+                die "The starting point of the drag was not correctly provided. Either provide the 'startx' and 'starty' coordinates, or a needle marking the starting point.";
+        }
+
+        # Repeat the same for endpoint coordinates or needles.
+        if (defined $args{endx} and defined $args{endy}) {
+                $endx = $args{endx};
+                $endy = $args{endy};
+        }
+        elsif (defined $args{endpoint}) {
+                my $endmatch = $args{endpoint};
+                my $end_matched_needle = assert_screen($endmatch, $args{timeout});
+                my $end_area = $end_matched_needle->{area}->[-1];
+                my $end_click_point = {
+                        xpos => $end_area->{w} / 2,
+                        ypos => $end_area->{h} / 2,
+                };
+                $endx = int($end_area->{x} + $end_click_point->{xpos});
+                $endy = int($end_area->{y} + $end_click_point->{ypos});
+        }
+        else {
+                die "The ending point of the drag was not correctly provided. Either provide the 'endx' and 'endy' coordinates, or a needle marking the starting point.";
+        }
+        bmwqemu::log_call("mouse dragged", button => $button);
+        # Get the button variable. If no button has been provided, assume the "left" button.
+        my $button = $args{button} //= "left";
+
+        # Now, perform the actual mouse drag. Navigate to the startpoint location,
+        # press and hold the mouse button, then navigate to the endpoint location
+        # and release the mouse button.
+        mouse_set($startx, $starty);
+        query_isotovideo('backend_mouse_button', {button => $button, bstate => 1});
+        mouse_set($endx, $endy);
+        query_isotovideo('backend_mouse_button', {button => $button, bstate => 0});
+
+        # Sleep for a while to leave a trace on the SUT video.
+        sleep("5");
+}
+
 =head1 multi console support
 
 All C<testapi> commands that interact with the system under test do that