Simulating Keystrokes

Applies to TestComplete 15.20, last modified on January 19, 2022

Sometimes during testing you need to send a sequence of pressed buttons (a keystroke) to the specified object - a control or a window. You can simulate keystrokes from keyword tests and scripts by sending key codes to the specified control or window. The information below describes how to implement these actions from your tests.

Basic Concepts

You can simulate keyboard input from your tests by using the following methods:

  • SetText - sets text in an edit control.

  • OnscreenObject.Keys, Sys.Keys and Desktop.Keys - send key presses to the desired object. The difference between different Keys methods is that OnscreenObject.Keys types in the specified onscreen object, while Desktop.Keys and Sys.Keys type in the currently focused object. All of these methods have one parameter - a string of keys to be typed. This string can include alphanumeric characters as well as special key codes (Ctrl, Alt, F1, Tab and others). For complete information on the format of the string of keystrokes, see the method description.

  • Desktop.KeyDown and Desktop.KeyUp - simulate pressing and releasing the specified key by its virtual code.

  • LLPlayer.KeyDown and LLPlayer.KeyUp - simulate low-level pressing and releasing the specified key. These methods also have the Delay parameter.

Note that the SetText action changes the object text programmatically, so, it may take less time to execute. The Keys, KeyDown and KeyUp methods, in their turn, simulate actual key presses in the object, taking into account the Key pressing delay project setting. However, the key pressing methods also ensure that the appropriate keyboard events are raised in the tested application and the associated event handlers, if any, are executed. Therefore, these methods are preferable to SetText in certain cases.

Below is the information on how to use the described methods to simulate keystrokes from different kinds of tests.

Limitations

To simulate entering text both in keyword tests and in scripts, TestComplete elevated permissions must be higher than those of the tested application. That is, if TestComplete is running under a user account and you run your tested application with administrative privileges, TestComplete will not send test commands to the tested application. Run TestComplete as an administrator to avoid the issue.

Simulating Keystrokes in Keyword Tests

Suppose you need to simulate a keystroke in a window, for instance, the “John Watts [Enter]” string needs to be typed in the Notepad window. Add operations to the keyword test according to the following steps:

  • 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 which keystrokes should be sent 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 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.

  • Select the Keys method from the list. Click Next.

  • On the third page of the Operation Parameters wizard you can specify the Keys parameter of the selected method:

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

    • Specify String in the Type cell.

    • Type the following string with the keystroke: “John Watts [Enter]”. You can also specify a variable or test parameter that holds the desired string. Press Enter to confirm input.

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

Now the specified keystroke will be simulated when you run your keyword test. In our case, the string “John Watts” will be typed within the Notepad window, then the ENTER button will be pressed.

You can also call the SetText, Keys, KeyUp and .KeyDown methods from other keyword test operations, for instance, from the Call Object Method and Run Code Snippet operations. For more information on how to perform standard operations in keyword tests, see Common Tasks for Keyword Test Operations.

Simulating Keystrokes in Scripts

There are two ways of simulating keystrokes from a script:

  • Using the Keys method

  • Using the KeyUp and KeyDown methods

The detailed information below describes how simulate keystrokes in your script.

Using the Keys Method

The following code enters “John Watts” into the control with focus, then it simulates pressing the Tab key and enters Manager into the next control:

JavaScript, JScript

Sys.Process("notepad").Window("Notepad", "*").SetFocus();
Sys.Desktop.Keys("John Watts" + "[Tab]" + "Manager");

Python

Sys.Process("notepad").Window("Notepad", "*").SetFocus()
Sys.Desktop.Keys("John Watts" + "[Tab]" + "Manager")

VBScript

Sys.Process("notepad").Window("Notepad", "*").SetFocus()
Sys.Desktop.Keys ("John Watts" + "[Tab]" + "Manager")

DelphiScript

Sys.Process('notepad').Window('Notepad', '*').SetFocus();
Sys.Desktop.Keys('John Watts' + '[Tab]' + 'Manager');

C++Script, C#Script

Sys["Process"]("notepad")["Window"]("Notepad", "*")["SetFocus"]();
Sys["Desktop"]["Keys"]("John Watts" + "[Tab]" + "Manager");

Using the KeyUp and KeyDown Method

These methods simulate pressing and releasing of a key specified by its virtual-key code which includes some complex user actions. For example, some operations with a mouse require the Shift , Ctrl or Alt keys to be pressed. To do this, you may typically use the Shift parameter of Click, Double-Click and Drag actions (see above). However, sometimes you may need additional functionality that cannot be achieved by using this parameter. For instance, you may need to perform two drag-and-drop operations while the Shift key needs to be pressed only once. In this case, you should simulate pressing the Shift key through the script code.

JavaScript, JScript

function Test1()
{
  Sys.Desktop.KeyDown(VK_SHIFT);  // Simulates Shift pressing
  // Simulate dragging actions
  Sys.Desktop.KeyUp(VK_SHIFT);    // Simulates the releasing of Shift
}

Python

def Test1():
  Sys.Desktop.KeyDown(VK_SHIFT) # Simulates Shift pressing
  # Simulate dragging actions
  Sys.Desktop.KeyUp(VK_SHIFT)

VBScript

Sub Test1
  Sys.Desktop.KeyDown VK_SHIFT ' Simulates Shift pressing
  'Simulate dragging actions
  Sys.Desktop.KeyUp   VK_SHIFT ' Simulates the releasing of Shift
End Sub

DelphiScript

procedure Test1;
begin
  Sys.Desktop.KeyDown(VK_SHIFT); // Simulates Shift pressing
  // Simulate dragging actions
  Sys.Desktop.KeyUp(VK_SHIFT);  // Simulates the releasing of Shift
end;

C++Script, C#Script

function Test1()
{
  Sys["Desktop"]["KeyDown"](VK_SHIFT);  // Simulates Shift pressing
  // Simulate dragging actions
  Sys["Desktop"]["KeyUp"](VK_SHIFT);   // Simulates the releasing of Shift
}

Note: Note that each call to KeyDown must have a corresponding call to KeyUp. If not, applications may “think” that Shift is pressed: this may lead to strange application behavior.

You can also simulate keystrokes from scripts by using the low-level KeyDown and KeyUp methods of the LLPLayer object to emulate “hold and click” actions in your tests.

Simulating Keystrokes With Native-Language Characters

The Key methods recognize native-language characters within the parameter string and automatically switches the keyboard layout to enter these characters. You can also force TestComplete to change the keyboard layout for a tested application by calling the aqEnvironment.SetKeyboardLayout method. To determine what keyboard layout is currently set for the needed window of the tested application, use the aqEnvironment.GetKeyboardLayout method. To check whether support for the needed language is installed, call aqEnvironment.IsLanguageSupported.

To simulate native-language keystrokes, you can also use the [Xnn] or [Dnn]constants in the string passed to the Keys method. nn specifies the virtual-key code of the key to be “pressed”. For instance, [X221]u[X221]e will “type” the u and e characters with the circumflex accent.

The difference between X and D is that D simulates pressing of dead-key characters while X simulates pressing of any key by its virtual-key code. When you specify the D tag, TestComplete checks whether the specified dead-key character is supported by languages installed in the operating system. If the check is successful, TestComplete activates the appropriate keyboard layout and simulates the specified key press.

Another way to simulate typing of native-language or special characters is to use the [Altnn] constants in the string passed to the Keys method. This constant commands TestComplete to simulate the Alt key press and typing of numeric keys on the numeric keypad (that is, ALT+character_code on the numeric keypad, a standard way to enter characters by their ANSI character code).

To “type” native-language characters into rich edit controls, you can use the shortcut supports by these controls (this works with English, French, German, Italian, and Spanish keyboards only):

Shortcut Description Example Result
Ctrl+' (apostrophe) + the desired character Accent acute [Hold]^'a
Ctrl+` (grave) + the desired character Accent grave [Hold]^`a
Ctrl+~ (tilde) + the desired character Accent tilde [Hold]^~~a
Ctrl+; (semicolon) + the desired character Accent umlaut [Hold]^;a
Ctrl+Shift+6 + the desired character Accent circumflex [Hold]^!6a
Ctrl+, (comma) + c or C Accent cedilla [Hold]^,c

See Also

Simulating User Actions
Simulating Keystrokes in Browsers
Simulating Text Input on Android Devices (Legacy)
Simulating Text Input in Android Open Applications (Legacy)
Simulating User Actions on iOS Applications (Legacy)
Creating and Recording Low-Level Procedures

Highlight search results