Simulating Keyboard Input with pressKeys Method

In automation testing, it's often necessary to simulate keyboard input, especially for text boxes or other controls that require keyboard input. The pressKeys() method is a widely supported feature in CukeTest, applicable to various control types. With this method, you can simulate entering strings in input boxes or perform other keyboard operations. The pressKeys() method is available in different technology types as follows:

  1. Global Keyboard Object
  2. Qt Automation
  3. Windows Automation
  4. Java Automation
  5. ATK Automation
  6. Virtual Controls

Method Signature

JavaScript
Python
interface PressKeysOptions {
    textOnly?: boolean,
    cpm?: number
}

pressKeys(keys: string, options?: PressKeysOptions | number): Promise<void>;
class PressKeysOptions():
    textOnly: bool
    cpm: int

Parameter Description

  • keys: string type
    The key or string to input, supports key combinations. Maximum string length is 1024 characters. Note that certain special characters in the string (such as ^+~%{}()) will be interpreted as control keys (such as Shift, Ctrl) rather than being entered as characters. For specific key commands, refer to Appendix: Input Key Correspondence Table.

  • options: PressKeysOptions | number (Optional)
    Optional parameters to control the input mode, including:

    • textOnly: boolean type. When set to true, all characters are entered as plain text, ignoring control key commands, equivalent to the Keyboard.typeString() method.
    • cpm: number type, i.e., characters per minute, used to control input speed. It's recommended to set the cpm value above 200. Due to different systems and applications handling input speed differently, the actual input speed may vary from the set value.

    If a number is passed directly as options, it will be treated as the cpm parameter.

  • Return Value:
    pressKeys() is an asynchronous method with no return value.

Feature Overview

pressKeys() implements string input or key combination operations by simulating keyboard signals, so it can be used not only for simple text input but also for complex keyboard operations, such as simulating login, navigation, cut, paste, etc. The following sample code demonstrates how to use pressKeys() to implement login functionality:

JavaScript
Python
await input.pressKeys("username{TAB}password~");
input.pressKeys("username{TAB}password~")

Where {TAB} represents pressing the Tab key, and ~ represents the Enter key. This code can be used to simulate entering username and password on a login interface that supports Tab switching and Enter submission.

Example 1: Entering Special Characters

If you need to enter text containing special characters, such as tilde ~, percent sign %, etc., these characters will conflict with key commands. In this case, you can use curly braces {} to wrap special characters to avoid ambiguity. The following example shows how to enter complex special characters:

JavaScript
Python

let textarea = model.getDocument("Text Editor"); // Same for the following examples
//Requirement: Enter special symbols "+^%~()[]{}"
await textarea.pressKeys("{+}");
await textarea.pressKeys("{^}");
await textarea.pressKeys("{%}");
await textarea.pressKeys("{~}");
await textarea.pressKeys("{(}");
await textarea.pressKeys("{)}");
await textarea.pressKeys("{[}");
await textarea.pressKeys("{]}");
await textarea.pressKeys("{{}");
await textarea.pressKeys("{}}");
await textarea.pressKeys("\""); // Quotes need to be escaped


textarea = model.getDocument("Text Editor"); # Same for the following examples
#Requirement: Enter special symbols "+^%~()[]{}"
textarea.pressKeys("{+}")
textarea.pressKeys("{^}")
textarea.pressKeys("{%}")
textarea.pressKeys("{~}")
textarea.pressKeys("{(}")
textarea.pressKeys("{)}")
textarea.pressKeys("{[}")
textarea.pressKeys("{]}")
textarea.pressKeys("{{}") 
textarea.pressKeys("{}}")
textarea.pressKeys("\"")  # Quotes need to be escaped

Example 2: Inserting Newlines and Tabs

If you need to insert newlines or tabs in text, you can use {ENTER} to represent the Enter key and {TAB} to represent the tab character, as shown below:

JavaScript
Python
await textarea.pressKeys("{ENTER}");
await textarea.pressKeys("~");  // Another representation for the Enter key
await textarea.pressKeys("{TAB}");
textarea.pressKeys("{ENTER}")
textarea.pressKeys("~")  # Another representation for the Enter key
textarea.pressKeys("{TAB}")

Example 3: Using Key Combinations

Sometimes you may need to use key combinations to complete certain tasks, such as closing windows or cutting and pasting text. The following code demonstrates how to use pressKeys() to simulate common key combination operations:

JavaScript
Python
await textarea.pressKeys("+{LEFT 5}");  // Shift + Left arrow key, select 5 characters
await textarea.pressKeys("^x");         // Ctrl + x, cut
await textarea.pressKeys("^v");         // Ctrl + v, paste
await textarea.pressKeys("^w");         // Ctrl + w, close window
await textarea.pressKeys("%{F4}");      // Alt + F4, close window
textarea.pressKeys("+{LEFT 5}")  # Shift + Left arrow key, select 5 characters
textarea.pressKeys("^x")         # Ctrl + x, cut
textarea.pressKeys("^v")         # Ctrl + v, paste
textarea.pressKeys("^w")         # Ctrl + w, close window
textarea.pressKeys("%{F4}")      # Alt + F4, close window

Difference Between Key Combinations and Regular Keys

When using control keys (such as Shift, Ctrl, Alt), pressKeys() will treat these keys and subsequent keys as key combinations. If you need to simulate holding down a control key for continuous input, you can use parentheses to wrap the string, as shown below:

JavaScript
Python
await textarea.pressKeys("+abc");   // Input result is Abc
await textarea.pressKeys("+(abc)"); // Input result is ABC
textarea.pressKeys("+abc")   # Input result is Abc
textarea.pressKeys("+(abc)") # Input result is ABC

If you need to hold down a control key while performing mouse operations (such as holding Ctrl while dragging), you can combine Keyboard.keyDown() and Keyboard.keyUp() methods. For detailed usage, refer to Key Combination Clicks.

Summary

pressKeys() is a very flexible API suitable for simulating various keyboard inputs. Note that pressKeys() is an instance method of Test Object, and you must specify the target control for keyboard input to use it.