TestCafe v2015.1   |   Documentation
The documentation on this webpage describes TestCafe v2015.1. This product is no longer available and has been replaced by TestCafe Studio. TestCafe Studio is our new cross-platform IDE for end-to-end web testing.
To learn more about TestCafe Studio, please visit www.devexpress.com/testcafestudio

USER ACTIONS

Use the following methods to perform user actions. Remember that TestCafe has a maximum of one user action per test step.

act.click

Clicks webpage elements.

act.click( target [, options] )

target - user action target (required). Identifies the webpage element(s) being clicked.
options - mouse action options (optional). A set of options providing additional details about user action.

The following example shows how to pass an array of targets to the Click action. (TestCafe Example Page)

'@test'['Click Checkboxes and Check State'] = {
    'Click two checkbox labels': function() {
        var labels = [ $(':containsExcludeChildren(Support for testing on remote devices)'), 
                       $(':containsExcludeChildren(Reusing existing JavaScript code for testing)') ];
        act.click(labels);
    },
    'Confirm checked state': function() {
        ok($('#testing-on-remote-devices').is(':checked'));
        ok($('#re-using-existing-javascript').is(':checked'));
    }
};

The next example uses the options parameter to set the caret position in the edit box after it has been clicked.

'@test'['Click Input'] = {
    'Type name:': function () {
        act.type(getInput(), 'Peter Parker');
    },
    'Move caret position': function () {
        act.click(getInput(), {
            caretPos: 5
        });
    },
    'Erase a character': function () {
        act.press('backspace');
    },
    'Check result': function () {
        eq(getInput().val(), 'Pete Parker');
    }
};

function getInput() {
    return $('#Developer_Name');
}

act.rclick

Right-clicks webpage elements.

act.rclick( target [, options] )

target - user action target (required). Identifies the webpage element(s) being right-clicked.
options - mouse action options (optional). A set of options providing additional details about user action.

Note that this action will not invoke integrated browser context menus, native editor menus, etc. Use it to perform right-clicks that are processed by webpage elements, not the browser.

The following example shows how to use the Right Click action.

'@test'['Popup Menu'] = {
    'Right-click on the second cell': function () {
        act.rclick(getCellByIndex(2));
    },
    'Hover the third cell': function () {
        act.hover(getCellByIndex(3));
    }
};

act.dblclick

Double-clicks webpage elements.

act.dblclick( target [, options] )

target - user action target (required). Identifies the webpage element(s) being double-clicked.
options - mouse action options (optional). A set of options providing additional details about the user action.

Note that this action will not invoke integrated browser actions such as text selection. Use it to perform double-clicks that are processed by webpage elements, not the browser.

act.drag

Drags a webpage element to a new position.

act.drag( target, destination [, options] )
act.drag( target, dragOffsetX, dragOffsetY [, options] )

target - user action target (required). Identifies the webpage element(s) being dragged.
destination - Specifies the drop location as a DOM element or jQuery object.
dragOffsetX, dragOffsetY - integer. These parameters specify drop coordinates as an offset from the mouse pointer's initial position.
options - mouse action options (optional). A set of options providing additional details about user action.

Note that this action will not invoke integrated browser actions such as copying and pasting text. Use it to perform drag and drop actions that are processed by webpage elements, not the browser.

The following example demonstrates how to use this action with a jQuery UI Slider control. (TestCafe Example Page)

'@test'['Drag slider'] = {
    'Click label "I have tried TestCafe"': function () {
        var label = $(':containsExcludeChildren(I have tried TestCafe)');
        act.click(label);
    },
    'Check initial slider value': function () {
        eq($('#Developer_Rating').val(), 1);
    },
    'Drag slider handle': function () {
        var sliderHandle = $('.ui-slider-handle');
        act.drag(sliderHandle, 360, 0, { offsetX: 10, offsetY: 10 });
    },
    'Check resulting slider value': function () {
        eq($('#Developer_Rating').val(), 7);
    }
};

act.hover

Hovers the mouse pointer over webpage elements.

act.hover( target [, options] )

target - user action target (required). Identifies the webpage element(s) to be hovered.
options - mouse action options (optional). A set of options providing additional details about user action.

Use this action to invoke popup elements such as hint windows, popup menus or dropdown lists that appear when hovering other elements.

The following example shows how to move the mouse pointer over a combo box to display the dropdown list, then select an item and check that the combo box value has changed. (TestCafe Example Page)

'@test'['act.hover example'] = {
    'Hover over the combo box': function () {
        var div = $('.text-field');
        act.hover(div);
    },
    'Select "Both"': function () {
        var div = $(':containsExcludeChildren(Both)').eq(0);
        act.click(div);
    },
    'Check result': function () {
        var value = $('.text-field').html();
        eq(value, 'Both');
    }
};

act.screenshot

Takes a screenshot of the tested page.

act.screenshot( )

Screenshots are saved to the test report, which you can view in the Results tab.

Important note

The method is not available on the Linux operating system.

act.navigateTo

Navigates to the specified url.

act.navigateTo( url )

url: String (required). Specifies the url to navigate to.

The following example shows how to use act.navigateTo user action.

'@test'['Navigation to the EULA page'] = {
    ...
    'Click label "I want to..."': function () {
        var label = $(':containsExcludeChildren(I want to read the EULA)');
        act.click(label);
    },
    'Click submit button "Submit"': function () {
        var submitButton = $('#submit-button');
        act.click(submitButton);
    },
    'Navigate to the EULA page': function () {
        act.navigateTo('http://testcafe.devexpress.com/eula');
    }
};

act.press

Presses the specified keys.

act.press( keysCommand )

keysCommand: String (required). Specifies the key, combination or sequence to be pressed.

  • Alphanumeric keys
    'a', 'A', '1', ...
  • Modifier keys
    'shift', 'alt', 'ctrl', 'meta'
  • Navigation and action keys
    'backspace', 'tab', 'enter', 'capslock', 'esc', 'space', 'pageup', 'pagedown', 'end', 'home', 'left', 'right', 'down', 'ins', 'delete'
  • Key combinations
    'shift+a', 'ctrl+d', ...
  • Sequential key presses (any of the above in a space-separated string)
    'a ctrl+b'

In addition to key presses handled by webpage elements, TestCafe also allows you to execute certain key presses processed by the browser.

  • 'ctrl+a', 'backspace', 'delete', 'left', 'right', 'up', 'down', 'home', 'end', 'enter', 'tab', 'shift+tab', 'shift+left', 'shift+right', 'shift+up', 'shift+down', 'shift+home', 'shift+end'

With the exception of the keys and combinations listed above, the Press action will not invoke integrated browser keystrokes.

Important note

For web elements that have contentEditable attribute, TestCafe supports the following key-presses:
- 'ctrl+a',
- 'backspace', 'delete', 'left' and 'right' (only if there is selection within the element).

The following example shows how to use the act.press user action. (TestCafe Example Page)

'@test'['Key Presses'] = {
    'Type name:': function () {
        act.type(getInput(), 'Peter Parker');
    },
    'Erase "Peter"': function () {
        act.press('home right . delete delete delete delete');
    },
    'Check result': function () {
        eq(getInput().val(), 'P. Parker');
    }
};

function getInput() {
    return $('#Developer_Name');
}

act.select

Selects text within the target elements of a web page.

act.select( target [, offset] )

target - user action target (required). Identifies the webpage element(s) whose text will be selected.
offset - Integer (optional). Identifies the direction and the end position of selection. Positive offset value represents a forward selection (where the start position is the first symbol of the text, and the end position is specified by the offset value counted from the start). Negative offset value represents a backward selection (where the start position is the last symbol of the text, and the end position is specified by the offset value counted from the end). If the offset is not specified, the whole text will be selected within the target element.

Important note

For web elements that have contentEditable attribute, offset parameter should be specified as an ordinal number of the symbol counted from the start, including all invisible symbols.

act.select( target [, startPos, endPos] )

target - user action target (required). Identifies the webpage element(s) whose text will be selected.
startPos - Integer (optional). Specifies the start position of the selection.
endPos - Integer (optional). Specifies the end position of the selection.

NOTE: startPos and endPos can't have negative values. If the startPos value is greater than the endPos value, it will be executed as a backward selection.

act.select( target, startLine, startPos, endLine, endPos )

act.select user action with the following parameters is useful when it comes to implementing text selection within a textarea element.

target - user action target (required). Identifies the webpage element(s) whose text will be selected. If the input element is specified as a target, the last two parameters will be ignored.
startLine - Integer (optional). Specifies the line number at which selection will start.
startPos - Integer (optional). Specifies the start position of selection within the line defined by the startLine.
endLine - Integer (optional). Specifies the line number at which selection will end.
endPos - Integer (optional). Specifies the end position of selection within the line defined by endLine.

NOTE: startPos, endPos, startLine and endLine can’t have negative values. If the position defined by startLine and startPos is greater than the one defined by endLine and endPos, it will execute a backward selection.

The following version of the act.select user action allows you to implement text selection between two specified web elements (including texts of these elements).

act.select( target-1, target-2 )

target-1 - Object (Dom element, jQuery object, TextNode object) (required). Identifies a webpage element where the selection starts from. The start position of selection is the first character of the element’s text.
target-2 - Object (Dom element, jQuery object, TextNode object) (required). Identifies a webpage element where the selection ends. The end position of selection is the last character of the element’s text.

NOTE: If the web element defined by target-2 is located on a higher level of the page hierarchy than the one defined by target-1, the user action will execute a backward selection.

The following example demonstrates text selection within the input element (TestCafe Example Page).

'@test'['Select text within input'] = {
    'Type within “Your name:" input element': function () {
        act.type(getInput(), 'Test Cafe', {
            caretPos: 0
        });
    },
    'Select within "Your name:" input element': function () {
        act.select(getInput(), 7, 1);
    },
    'Confirm input selection state': function () {
        var input = getInput()[0];
        eq(input.selectionStart, 1);
        eq(input.selectionEnd, 7);
        if (input.selectionDirection)
            eq(input.selectionDirection, 'backward');
    }
};

var getInput = function () {
    return $('#Developer_Name');
};

act.type

Types the specified text into a webpage element.

act.type( target, text [, options] )

target - user action target (required). Identifies the element that will receive input focus.
text - String (required). The text to be typed into the specified webpage element. You cannot specify an empty string.
options - typing action options (optional). A set of options providing additional details about user action. If this parameter is omitted, TestCafe sets the cursor to the end of the text before typing, thus preserving the text that is already in the edit box.

NOTE: Use key press actions to implement text management operations such as selection or deletion.

The following example shows how to use act.type with and without options. (TestCafe Example Page)

'@test'['Type and Replace'] = {
    'Type name:': function () {
        act.type($('#Developer_Name'), 'Peter');
    },
    'Replace with last name': function () {
        act.type($('#Developer_Name'), 'Paker', {
            replace: true
        });
    },
    'Update last name': function () {
        act.type($('#Developer_Name'), 'r', {
            caretPos: 2
        });
    },
    'Check result': function () {
        eq($('#Developer_Name').val(), 'Parker');
    }
};

act.upload

Uploads a file or a set of files.

act.upload( target, path )

This action uploads an individual file.

target - String. Identifies the target element selector expression of the input field where the file is uploaded.
path - String. Identifies the relative path from the folder with the test file to the uploaded file.

Use the following variant of the user action to implement the uploading of multiple files at once.

act.upload( target, paths )

target - String. Identifies the target element selector expression of the input field where the files are uploaded.
paths - Array of Strings. Identifies a set of relative paths from the folder with the test file to the uploaded files.

If an error occurs during the uploading of the saved file(s), the test will fail.

If you need to imitate the browser's behaviour when a user clicks the Cancel button, use the following version of the user action.

act.upload( target )

target - String. Identifies the target element selector expression of the input field where the files are uploaded.

The following example illustrates how to use the act.upload user action.

'@test'['Uploading'] = {
    'Click file button': function() {
        act.click('#upload_input');
    },
    'Upload "1.jpg", "2.jpg", "3.jpg" files': function() {
        act.upload('#upload_input', [ './uploads/1.jpg', './uploads/2.jpg', './uploads/3.jpg' ]);
    },
    'Click div': function() {
        act.click('#upload_button');
    }
};

act.wait

Pauses the test for a specified period of time.

act.wait( milliseconds [, resumePredicate] )

milliseconds: Integer (required). The pause interval in milliseconds.
resumePredicate: Function (optional). The action calls this function repeatedly, and resumes the test if the return value is true. Use this keyword within the predicate to use the shared data of the step.

The following example uses the act.wait user action to pause the test while animation is running. (TestCafe Example Page)

'@test'['Wait Example'] = {
    'Initiate animation and wait': function () {
        $('.article-header').animate({ opacity: 0 }, 1000);
        act.wait(10000, isTransparent);
    },
    'Type': function () {
        var input = $('#Developer_Name');
        act.type(input, 'The wait is over!');
    }
};

function isTransparent() {
    return $('.article-header').css('opacity') == 0;
} 

act.waitFor

Allows you to pause test execution until a specified event occurs.

The waitFor action enables you to execute an asynchronous function while pausing a test run until it completes.

act.waitFor( event [, timeout] )

event: Function (required). Represents an asynchronous function that receives a callback argument. Use this keyword within the function to use the shared data of the step.
timeout: Integer (optional). The pause interval in milliseconds. If omitted, execution is paused for 10000 milliseconds.

Note that if the specified asynchronous event does not occur, the test will fail. Use the act.wait user action to enable a simple waiting mechanism without test failure.

The following versions of the waitFor action allow you to pause tests until a specific element (or multiple elements) appears on the page.

act.waitFor( selector [, timeout] )

selector: String (required). The CSS selector that selects elements to wait for.
timeout: Integer (optional). The pause interval in milliseconds. If omitted, execution is paused for 10000 milliseconds.

act.waitFor( selectors [, timeout] )

selectors: Array of strings (required). An array of CSS selectors that select elements to wait for.
timeout: Integer (optional). The pause interval in milliseconds. If omitted, execution is paused for 10000 milliseconds.

The following example uses the act.waitFor action to pause the test until the asynchronous function completes an HTTP request and obtains the status code.

'@test'['waitFor example'] = {
    'wait': function () {
        act.waitFor(function (callback) {
            $.get('http://some.address', function (jqxhr){
                eq(jqxhr.statusCode, 200);
                callback();
            });
        }, 500);
    }
};

The following example demonstrates how to use the act.waitFor action to pause the test until the animated element is loaded.

'@test'['Waiting for the animated element to load'] = {
    '1.Click the Start button to view the animated element': function() {
        act.click('.start-button');
    },
    '2.Wait for the animation to finish': function () {
        act.waitFor('#animated-element', 5000);
    },
    '3.Perform some actions with the animated element': function() {
        eq($('#animated-element').text(), 'The expected text');
    }
};