Simulating Mouse Actions

Applies to TestComplete 15.10, last modified on November 30, 2021

TestComplete includes special features for simulating mouse and mouse wheel events. You can simulate these events from keyword tests, scripts and low-level procedures. This topic provides detailed information on how to implement mouse event simulation in your tests. For information on how to simulate mouse wheel rotation, see Simulating Mouse Wheel Rotation.

Basic Concepts

To simulate clicks, double-clicks, dragging and hovering (hot-tracking) operations, each onscreen object and objects inherited from the onscreen object (window, Win32ComboBox, Win32TreeView and others) contain special actions:

  • Click, ClickR, ClickM - Simulates a single click performed with the left, right or middle mouse button.

  • DblClick, DblClickR, DblClickM - Simulates a double-click performed with the left, right or middle mouse button.

  • Drag, DragR, DragM - Simulates a dragging operation performed with the left, right or middle mouse button.

  • HoverMouse - Simulates moving the mouse pointer to the specified position within an object.

Each of these actions have parameters that specify window-related coordinates of the event. The click, double-click and drag actions have an additional parameter that specifies the keys or a combination of keys (Ctrl, Alt, Shift) that are pressed during simulating an event.

You can also simulate mouse clicks by using the MouseDown and MouseUp methods of the Desktop object or the MouseDown and MouseUp methods of the LLPlayer object. You can use these methods to emulate "hold and click" actions, as well as to simulate mouse clicks at any position on screen. Besides the described methods, different program objects, that are used to work with custom controls and menus have their specific actions and methods to simulate user actions on them. For complete information, see Working With Application Objects and Controls.

Simulating From Keyword Tests

You can simulate a mouse event from a keyword test by using the On-Screen Action operation with specified parameters. You can create a sequence of simulated events by adding the desired number of the On-Screen Action operations to the test.

For instance, to click at the point (30, 40) with the right mouse button within the Notepad window, add the following operations to the keyword test:

  • Open your keyword test for editing.

  • Add the On-Screen Action operation to the test. After the operation is dragged, TestComplete will display the Operation Parameters wizard.

  • Then you can specify an object to simulate a click within it in one of the following ways:

    • Type the full name of the object in the first page of the wizard. In our case, It will be a string Sys.Process("notepad").Window("Notepad", "Untitled - Notepad", 1).

    • Click the Pick Object... button, and when the Pick Object dialog appears, drag the target glyph () to the desired object. In our case, if we drag the glyph to the Notepad window caption and then release the mouse button, the following object will be selected by the wizard: “Sys.Process("notepad").Window("Notepad", "Untitled - Notepad", 1)”.

  • Click Next.

  • In the second page of the wizard, select the appropriate method from the list. In our case, it will be the ClickR method. Click Next.

  • On the third page of the Operation Parameters wizard you can specify parameters of the selected method. For information on each individual method parameters, see the method description:

    • ClientX

      • Choose the Constant from the Mode drop-down list.

      • Specify Integer in the Type cell.

      • Enter the x-coordinate of the point, where a click will be simulated, in the Value column. This coordinate is relative to the object. In our case, the x-coordinate is equal to 30. Press ENTER to confirm input in the cell.

    • ClientY

      • Choose the Constant from the Mode drop-down list.

      • Specify Integer in the Type cell.

      • Enter the y-coordinate of the point, where a click will be simulated, in the Value column. This coordinate is relative to the object. In our case, the y-coordinate is equal to 40. Press ENTER to confirm input in the cell.

    • Shift

      • Choose the Code Expression from the Mode drop-down list.

      • Specify Code Expression in the Type cell.

      • Enter the constant, that specifies whether the SHIFT, CTRL or ALT key is pressed during the click. For instance, if you enter the skAlt constant, the ALT key will be pressed during the click. For information about possible values, see TShiftKey. In our case, this parameter is equal to skNoShift. Press ENTER to confirm input in the cell.

  • Click Finish to save the changes and to close the wizard. TestComplete will append the operation to the test.

Now the mouse event will be simulated when you run your keyword test. In our example, a click of the right mouse button will be simulated at point (30,40) in window-relative coordinates and Shift will not be pressed during the click.

You can also use the Call Object Method operation to simulate mouse events. For more information on how to perform typical tasks in keyword tests, see Common Tasks for Keyword Test Operations.

Simulating From Scripts

You can simulate mouse events from a script routine. To do this, call the appropriate methods from your script.

Click at a Point

The following sample code simulates a click within the Notepad window at the point (30, 40):

JavaScript, JScript

var p, w;
p = Sys.Process("notepad");
w = p.Window("Notepad", "Untitled - Notepad", 0);
w = w.Window("Edit", "", 0);
w.Click(30, 40);

Python

p = Sys.Process("notepad")
w = p.Window("Notepad", "Untitled - Notepad", 0)
w = w.Window("Edit", "", 0)
w.Click(30, 40)

VBScript

Set p = Sys.Process("notepad")
Set w = p.Window("Notepad", "Untitled - Notepad", 0)
Set w = w.Window("Edit", "", 0)
w.Click 30, 40

DelphiScript

var
  p, w : OleVariant;
begin
  p := Sys.Process('notepad');
  w := p.Window('Notepad', 'Untitled - Notepad', 0);
  w := w.Window('Edit', '', 0);
  w.Click(30, 40);
end;

C++Script, C#Script

var p, w;
p = Sys["Process"]("notepad");
w = p["Window"]("Notepad", "Untitled - Notepad", 0);
w = w["Window"]("Edit", "", 0);
w["Click"](30, 40);

The ClickR action is used to invoke the context menu. See the example in Pasting Text via the Context Menu.

Hold and Click

The following sample code demonstrates how to emulate holding down the CTRL key and clicking the left mouse button:

JavaScript, JScript

function HoldAndClickExample()
{
  //Launches Notepad
  WshShell.Run("notepad.exe", SW_NORMAL);
  
  //Presses CTRL in the Notepad main window
  LLPlayer.KeyDown(VK_CONTROL, 2000);
  
  // Specifies the coordinates of the click
  var coordX = 15;
  var coordY = 120;
  
  // Specifies a delay in milliseconds
  var sDelay = 2000; // 2 seconds
  
  // Simulates pressing the left mouse button
  LLPlayer.MouseDown(MK_LBUTTON, coordX, coordY, sDelay);
  // ...
  // Simulates releasing the left mouse button
  LLPlayer.MouseUp(MK_LBUTTON, coordX, coordY, sDelay);
  
  //Releases CTRL
  LLPlayer.KeyUp(VK_CONTROL, 2000);
}

Python

def HoldAndClickExample():
  # Launches Notepad
  WshShell.Run("notepad.exe", SW_NORMAL)
  # Presses CTRL in the Notepad main window
  LLPlayer.KeyDown(VK_CONTROL, 2000)
  # Specifies the coordinates of the click
  coorX = 15
  coorY = 120
  # Specifies a delay in milliseconds
  sDelay = 2000 # 2 seconds
  # Simulates pressing the left mouse button
  LLPlayer.MouseDown(MK_LBUTTON, coorX, coorY, sDelay)
  # Simulates releasing the left mouse button
  LLPlayer.MouseUp(MK_LBUTTON, coorX, coorY, sDelay)
  # Releases CTRL
  LLPlayer.KeyUp(VK_CONTROL, 2000)

VBScript

Sub HoldAndClickExample()

  ' Launches Notepad
  Call WshShell.Run("notepad.exe", SW_NORMAL)
  
  ' Presses CTRL in the Notepad main window
  Call LLPlayer.KeyDown(VK_CONTROL, 2000)
  
  ' Specifies the coordinates of the click
  coordX = 15
  coordY = 120
  
  ' Specifies a delay in milliseconds
  sDelay = 2000 ' 2 seconds
  
  ' Simulates pressing the left mouse button
  Call LLPlayer.MouseDown(MK_LBUTTON, coordX, coordY, sDelay)
  ' ...
  ' Simulates releasing the left mouse button
  Call LLPlayer.MouseUp(MK_LBUTTON, coordX, coordY, sDelay)
  
  ' Releases CTRL
  Call LLPlayer.KeyUp(VK_CONTROL, 2000)
  
End Sub

DelphiScript

function HoldAndClickExample;
begin
  
  // Launches Notepad
  WshShell.Run('notepad.exe', SW_NORMAL);
  
  //Presses CTRL in the Notepad main window
  LLPlayer.KeyDown(VK_CONTROL, 2000);
  
  // Specifies the coordinates of the click
  var coordX = 15;
  var coordY = 120;
  
  // Specifies a delay in milliseconds
  var sDelay = 2000; // 2 seconds
  
  // Simulates pressing the left mouse button
  LLPlayer.MouseDown(MK_LBUTTON, coordX, coordY, sDelay);
  // ...
  // Simulates releasing the left mouse button
  LLPlayer.MouseUp(MK_LBUTTON, coordX, coordY, sDelay);
  
  //Releases CTRL
  LLPlayer.KeyUp(VK_CONTROL, 2000);
  
end;

C++Script, C#Script

function HoldAndClickExample()
{
  // Launches Notepad
  WshShell["Run"]("notepad.exe", SW_NORMAL);
  
  //Presses CTRL in the Notepad main window
  LLPlayer["KeyDown"](VK_CONTROL, 2000);
  
  // Specifies the coordinates of the click
  var coordX = 15;
  var coordY = 120;
  
  // Specifies a delay in milliseconds
  var sDelay = 2000; // 2 seconds
  
  // Simulates pressing the left mouse button
  LLPlayer["MouseDown"](MK_LBUTTON, coordX, coordY, sDelay);
  // ...
  // Simulates releasing the left mouse button
  LLPlayer["MouseUp"](MK_LBUTTON, coordX, coordY, sDelay);
  
  //Releases CTRL
  LLPlayer["KeyUp"](VK_CONTROL, 2000);
}

Simulating From Low-Level Procedures

To simulate mouse events from this kind of test, you should record the desired sequence of user actions as a low-level procedure - moving the mouse, clicking, see Creating and Recording Low-Level Procedures. After that you can run this low-level procedure, when it is needed to simulate the recorded actions. For more information, see Running Low-Level Procedures.

Possible Issues

Before simulating a click on a control, TestComplete performs a number of verifications. It finds the target control, determines the point of the click in it, and then checks whether this point is visible on the screen and whether it is overlapped by some other control or window. It is possible that, during the check, the point or entire control becomes overlapped with another control or window, or changes its position (if the control moves). This typically happens with applications and web pages that have animated elements.

To avoid the problem, you have to use test commands that will pause the test execution until the animation is over. The easiest way to achieve this is to use test commands that delay test execution for some time. A more sophisticated approach is to use the Wait methods that pause the test execution until the object state changes. For instance, you can determine properties, whose values change during the animation (this can be VisibleOnScreen), and use the WaitProperty method to pause the test run until the property gets the needed value. See Waiting for an Object to Have a Specific Property Value and Waiting for Object State Changes.

See Also

Simulating User Actions
Simulating Mouse Wheel Rotation
Creating and Recording Low-Level Procedures

Highlight search results