Page Actions

Dec 22, 2021
14 minutes to read

Page actions simulate user-page interactions: clicks, key presses, and so on.

You can record most page actions for both test scripts and codeless tests.

The TestCafe framework implements page actions as methods of the testController object. TestCafe documentation includes a Guide to Page Interaction, as well as in-depth reference articles on each of the action methods.

| |

| |

Select Editable Content

Select Text Area Content

| |

Click

Clicks a webpage element.

Corresponding TestCafe API method: t.click().

Parameter	Description
Element Selector	Specifies which web element should be clicked.

You can also specify additional parameters for the action. See Click Action Options.

Double Click

Double-clicks a webpage element.

Corresponding TestCafe API method: t.doubleClick().

Parameter	Description
Element Selector	Specifies which web element should be double-clicked.

You can also specify additional parameters for the action. See Click Action Options.

Right Click

Right-clicks a webpage element.

Corresponding TestCafe API method: t.rightClick().

Parameter	Description
Element Selector	Specifies which web element should be right-clicked.

You can also specify additional parameters for the action. See Click Action Options.

Type Text

Types text within an input element.

Corresponding TestCafe API method: t.typeText().

Parameter	Description
Element Selector	Identifies the webpage element that receives input focus.
Text	The text to be typed into the specified webpage element.

The Type Text action also clicks the specified element before text is typed if this element is not focused. This is not recorded as a separate Click action in the test. If the target element is not focused after the click, the Type Text action does not type text.

You can also specify additional parameters for the action. See Typing Action Options.

Enter Values Into DateTime, Color and Range Inputs

TestCafe Studio cannot record your actions when you interact with certain types of HTML5 inputs, like DateTime, Color or Range.

To enter values into these inputs, add the Type Text action to a test and specify a value to be typed.

The following table lists the input types and shows how to format the entered values:

Input type	Pattern	Example
Date	`yyyy-mm-dd`	`2017-12-23`
Week	`yyyy-Www`	`2017-W03`
Month	`yyyy-mm`	`2017-08`
DateTime	`yyyy-mm-ddThh:mm`	`2017-11-03T05:00`
Time	`hh:mm`	`15:30`
Color	`#rrggbb`	`#003000`
Range	`n`	`45`

Press Key

Presses the specified keyboard key.

Corresponding TestCafe API method: t.pressKey().

Parameter	Description
Key	The sequence of keys and key combinations to be pressed.

The following table shows how to specify keys of different types, key sequences, and combinations:

Key Type	Example
Alphanumeric keys	`a`, `A`, `1`
Modifier keys	`shift`, `alt` (⌥ key on macOS), `ctrl`, `meta` (meta key on Linux and ⌘ key on macOS)
Navigation and action keys	`backspace`, `tab`, `enter`
Key combinations	`shift+a`, `ctrl+d`
Sequential key presses	Any of the above in a string separated by spaces, for example, `a ctrl+b`

The following navigation and action keys are supported:

backspace
tab
enter
capslock
esc
space
pageup
pagedown
end
home
left
right
up
down
ins
delete

Browser Processing Emulation

When a user presses a key or a key combination, the browser dispatches an event that triggers handlers in page code. Most browsers also respond to common keystrokes with their integrated actions (for instance, they select text when you press Cmd/Ctrl+A or switch focus when you press Shift+Tab).

The Press Key action only triggers page handlers for most keystrokes. Browser processing is emulated with a limited set of elements:

Shortcut	Elements
`'ctrl+c'`, `'ctrl+v'`	None. Clipboard operations are not emulated.
`ctrl+a`	text field-based inputs, `<textarea>`, `contentEditable`
`backspace`	text field-based inputs, `<textarea>`, `contentEditable`
`delete`	text field-based inputs, `<textarea>`, `contentEditable`
`left`	text field-based inputs, radio button inputs, `<textarea>`, `<select>`, `contentEditable`
`right`	text field-based inputs, radio button inputs, `<textarea>`, `<select>`, `contentEditable`
`up`	text field-based inputs, radio button inputs, `<textarea>`, `<select>`
`down`	text field-based inputs, radio button inputs, `<textarea>`, `<select>`
`shift+left`	text field-based inputs, `<textarea>`
`shift+right`	text field-based inputs, `<textarea>`
`shift+up`	text field-based inputs, `<textarea>`
`shift+down`	text field-based inputs, `<textarea>`
`home`	text field-based inputs, `<textarea>`
`end`	text field-based inputs, `<textarea>`
`shift+home`	text field-based inputs, `<textarea>`
`shift+end`	text field-based inputs, `<textarea>`
`enter`	text field-based inputs, `<textarea>`, `<select>`, `<a>`
`tab`	focusable elements
`shift+tab`	focusable elements
`esc`	`<select>`

Note

The backspace, delete, left and right key presses in contentEditable elements are processed only when text is selected.

Text Field-Based Inputs

TestCafe Studio supports selection and navigation with keystrokes in the following input types:

email
number
password
search
tel
text
url

You can also specify additional parameters for the Press Key action. See Basic Action Options.

Drag

Drags a webpage element to the specified location.

Corresponding TestCafe API method: t.drag().

Parameter	Description
Element Selector	Specifies which webpage element should be dragged.
Drag Offset X	Number. The drop coordinates’ X-offset from the mouse pointer’s initial position.
Drag Offset Y	Number. The drop coordinates’ Y-offset from the mouse pointer’s initial position.

You can also specify additional parameters for the action. See Mouse Action Options.

Drag To Element

Drags a webpage element to another element.

Corresponding TestCafe API method: t.dragToElement().

Parameter	Description
Element Selector	Specifies which webpage element should be dragged.
Destination Selector	Identifies the webpage element that serves as the drop location.

You can also specify additional parameters for the action. See Drag To Element Action Options.

Note

You cannot record this action. Use the Test Editor or the Script Editor to add this action to the test.

Select Text

Selects text within an input element.

Corresponding TestCafe API method: t.selectText().

Parameter	Description
Element Selector	Identifies the webpage element whose text should be selected.
Start Position	The selection’s start position. A zero-based integer.
End Position	The selection’s end position. A zero-based integer.

Start Position and End Position are recorded as 0 for email and number inputs in Chrome, Firefox, and Chromium-based Edge. These browsers deprecated the selectionStart, selectionEnd, and selectionDirection input properties so TestCafe Studio cannot detect the selection position. Specify the Start Position and the End Position to select text inside the email and number inputs. The entered value is taken into account as usual when the test runs.

To select all content in an email or number input, use the Click action, and then Press Key to press the ctrl+a combination.

Select Editable Content

Selects text within a contenteditable element.

Corresponding TestCafe API method: t.selectEditableContent().

Parameter	Description
Start Element Selector	Identifies the webpage element from which selection starts. The selection’s start position is the first character of the element’s text.
End Element Selector	Identifies the webpage element at which selection ends. The selection’s end position is the last character of the element’s text.

You can also specify additional parameters for the action. See the Basic Action Options section for details.

Note

You cannot record this action. Use the Test Editor or the Script Editor to add this action to the test.

Select Text Area Content

Selects text within a <textarea> element.

Corresponding TestCafe API method: t.selectTextAreaContent().

Parameter	Description
Element Selector	Identifies the `<textarea>` element whose text should be selected.
Start Line	The line number at which selection starts. A zero-based integer.
Start Position	The selection’s start position within the line defined by the Start Line parameter. A zero-based integer.
End Line	The line number at which selection ends. A zero-based integer.
End Position	The selection’s end position within the line that the End Line parameter defines. A zero-based integer.

You can also specify additional parameters for the action. See the [Basic Action Options] section (xref:400168#basic-action-options) for details.

Note

You cannot record this action. Use the Test Editor or the Script Editor to add this action to the test.

Wait

Pauses test execution for the specified period of time.

Corresponding TestCafe API method: t.wait().

Parameter	Description
Timeout	The pause duration (in milliseconds).

Note

You cannot record this action. Use the Test Editor or the Script Editor to add this action to the test.

Hover

Hovers over a webpage element with the mouse pointer.

Corresponding TestCafe API method: t.hover().

Parameter	Description
Element Selector	Identifies the webpage element being hovered over.

You can also specify additional parameters for the action. See the Mouse Action Options section for details.

Note

You cannot record this action. Use the Test Editor or the Script Editor to add this action to the test.

Set Files to Upload

Specifies files that should be uploaded to the server.

Corresponding TestCafe API method: t.setFilesToUpload().

Parameter	Description
Element Selector	Identifies the file upload input that allows you to specify files to be uploaded.
Files	Files to be uploaded.

Record the Action

To record the Set Files to Upload action, click a file upload input on a webpage and browse for desired files. TestCafe Studio copies the files to _<test_directory>/_uploads\ __, adds the Set Files to Upload action to a test and specifies the files from the _uploads_ folder as the action parameters.

Add the Action from the Actions panel

You should do the following when you add the Set Files to Upload action from the Actions panel:

Set up the Element Selector parameter.
Specify files for upload in one of the following ways:

Note

The Set Files to Upload and Clear Upload actions only allow you to manage the list of files for upload. These files are uploaded to the server after you initiate upload, for example, when you click the Upload or Submit button on a webpage. TestCafe can record this action, or you can add the Click action to the test manually.

Clear Upload

Removes all file paths from the specified file upload input.

Corresponding TestCafe API method: t.clearUpload().

Parameter	Description
Element Selector	Identifies the input field that should be cleared.

Action Options

To add an option to a codeless test action, click the Add Option button in the action parameters area, select the option in the list, and specify its value.

Basic Action Options

The following option is available for the Press Key , Select Text , Select Text Area Content and Select Editable Content actions:

Option	Type	Description	Default
Speed	Number	The action emulation’s speed. Defines how fast TestCafe Studio performs the action when running tests. A number between `1` (maximum) and `0.01` (minimum). This setting overrides the test speed specified in the run configuration settings.	`1`

Mouse Action Options

The following options are available for mouse actions: Drag and Hover :

Option	Type	Description	Default
Modifiers: Ctrl, Alt, Shift, Meta	Boolean	Indicate which modifier keys should be pressed during the mouse action. TestCafe Studio automatically adds Modifiers when it records on-page actions.	Disabled
Offsets: OffsetX, OffsetY	Number	Mouse pointer coordinates that define a point where the action is performed. If an offset is a positive integer, coordinates are calculated relative to the top-left corner of the target element. If an offset is a negative integer, they are calculated relative to the bottom-right corner. If you record actions on the webpage, TestCafe Studio stores the OffsetX and OffsetY parameters’ values. To use these values, click the Add Options button and select Offsets in the list. This adds the options with the recorded values.	The target element’s center.
Speed	Number	The action emulation’s speed. Defines how fast TestCafe Studio performs the action when running tests. A number between `1` (the maximum speed) and `0.01` (the minimum speed). This setting overrides the test speed that is specified in run configuration settings.	`1`

Drag To Element Action Options

The following options are available for the Drag To Element action.

Option	Type	Description	Default
Modifiers: Ctrl, Alt, Shift, Meta	Boolean	Indicate which modifier keys should be pressed during the drag action. TestCafe Studio automatically adds Modifiers when it records on-page actions.	Disabled
Offsets: OffsetX, OffsetY	Number	Mouse pointer coordinates that define a point where dragging starts. If an offset is a positive integer, coordinates are calculated relative to the target element’s top-left corner. If an offset is a negative integer, they are calculated relative to the bottom-right corner. If you record actions on the webpage, TestCafe Studio stores the OffsetX and OffsetY options’ values. To add the options with the recorded values, click the Add Options button and select Offsets in the list.	The target element’s center.
Speed	Number	The action emulation’s speed. Defines how fast TestCafe Studio performs the action when running tests. A number between `1` (the maximum speed) and `0.01` (the minimum speed). This setting overrides the test speed specified in run configuration settings.	`1`

Click Action Options

The following options are available for click actions: Click , Double Click and Right Click.

Option	Type	Description	Default
Modifiers: Ctrl, Alt, Shift, Meta	Boolean	Indicate which modifier keys should be pressed during the mouse action. TestCafe Studio automatically adds Modifiers when it records on-page actions.	Disabled
Offsets: OffsetX, OffsetY	Number	Mouse pointer coordinates that define a point where the action is performed. If an offset is a positive integer, coordinates are calculated relative to the target element’s top-left corner. If an offset is a negative integer, they are calculated relative to the bottom-right corner. If you record the action by performing it on the webpage, TestCafe Studio remembers the OffsetX and OffsetY option values. To add the options with the recorded values, click the Add Options button and select Offsets in the list.	The target element’s center.
Caret Position	Number	The initial caret position if the action is performed on a text input field. A zero-based integer.	The length of the input field content.
Speed	Number	The action emulation’s speed. Defines how fast TestCafe Studio performs the action when running tests. A number between `1` (the maximum speed) and `0.01` (the minimum speed). This setting overrides the test speed specified in the run configuration settings.	`1`

Caret Position is not recorded for email and number inputs in Chrome, Firefox, and Chromium-based Edge. These browsers deprecated the selectionStart, selectionEnd, and selectionDirection input properties, so TestCafe Studio cannot detect the caret position. If your scenario depends on the caret position, specify it explicitly. This parameter is then taken into account when the test runs.

Type Text Action Options

The following options are available for the Type Text action.

Option	Type	Description	Default
Modifiers: Ctrl, Alt, Shift, Meta	Boolean	Indicate which modifier keys should be pressed while typing. TestCafe Studio automatically adds Modifiers when it records on-page actions.	Disabled
Offsets: OffsetX, OffsetY	Number	Mouse pointer coordinates that define a point where the action is performed. If an offset is a positive integer, coordinates are calculated relative to the top-left corner of the target element. If an offset is a negative integer, they are calculated relative to the bottom-right corner. If you record actions on the webpage, TestCafe Studio stores the OffsetX and OffsetY option values. To add the options with the recorded values, click the Add Options button and select Offsets in the list.	The target element’s center.
Caret Position	Number	The initial caret position. A zero-based integer.	The length of the input field content.
Replace	Boolean	Enable the option to remove the current text in the target element, or disable it to leave the text as it is.	Disabled
Paste	Boolean	Enable the option to insert the entire block of current text with a single keystroke (similar to a copy & paste function), or disable it to insert the current text character by character.	Disabled
Speed	Number	The action emulation’s speed. Defines how fast TestCafe Studio performs the action when running tests. A number between `1` (maximum) and `0.01` (minimum). This setting overrides the test speed specified in the run configuration settings.	`1`