USER ACTIONS

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( 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( 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( 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( 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( )

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

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( 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.

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( 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.

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.

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.

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.

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( 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.

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( 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( 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;
} 

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');
    }
};