Interact With the Page

Test API includes a set of actions you can use to interact with the page.

The test controller object includes actions as its methods. You can chain these actions when you call them in code.

You can find a list of available actions (with reproducible examples) and links to their descriptions below.

TestCafe is intended to emulate real user behavior, so you cannot interact with elements, that are not visible at that moment.

For instance, you can not type into an input element with the display: none style.

Click

Click actions allow you to click an element on a page.

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://devexpress.github.io/testcafe/example/`;

test('Click test', async t => {
    const selectBasedOnText = Selector('label').withText('I have tried TestCafe');

    await t
        .click(selectBasedOnText);
});

Press Key

Press Key action allows you to press a key or key combination.

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://devexpress.github.io/testcafe/example/`;

test('Press Key test', async t => {
    await t
        .click('#tried-test-cafe')
        // pressing 'Space' imitates clicking the checkbox again
        .pressKey('space')
});

Navigate

Navigate action navigates to the specified URL.

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://devexpress.github.io/testcafe/example/`;

test('Navigate To URL test', async t => {
    await t
        .navigateTo('https://github.com/DevExpress/testcafe');
});

Type Text

Type Text action types the specified text in the selected input element.

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://devexpress.github.io/testcafe/example/`;

test('Type Text test', async t => {
    await t
        .typeText('#developer-name', 'John Doe');
});

Select Text

Actions that allow you to select text in inputs, <textarea>, and contentEditable elements.

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://devexpress.github.io/testcafe/example/`;

test('Select Text test', async t => {
    await t
        .typeText('#developer-name', 'John Doe')
        .selectText('#developer-name')
        .pressKey('delete');
});

Hover

Hover action allows you to hover the mouse pointer over the tested page.

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://js.devexpress.com`;

test('Hover test', async t => {
    await t
        .hover('.map-container');
});

Drag Elements

Drag actions allow you to drag elements on the tested page.

The drag actions do not invoke integrated browser actions such as text selection. Use them to perform drag-and-drop actions that page elements process. To select text, use t.selectText.

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://devexpress.github.io/testcafe/example/`;

test('Drag test', async t => {
    const triedCheckbox = Selector('label').withText('I have tried TestCafe');

    await t
        .click(triedCheckbox)
        .drag('#slider', 360, 0, { offsetX: 10, offsetY: 10 });
});

Upload Files

Actions that allow you to manipulate the state of file upload input elements:

Use the t.setFilesToUpload action to populate the input with the files you want to upload. If your application sends files as soon as you populate the field, the upload occurs when you call this action. Otherwise, you will have to begin the upload manually (for example, click the submit button).

Use the t.clearUpload action to clear the list of files to upload.

See the Test File Upload recipe for more details.

The t.setFilesToUpload action only works with <input type="file"> HTML elements, because browsers use these elements to upload files.

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://js.devexpress.com/Demos/WidgetsGallery/Demo/FileUploader/FileSelection/jQuery/Light/`;

test('Upload Files test', async t => {
    await t
        .switchToIframe('.demo-frame')
        .setFilesToUpload('.dx-fileuploader-input', [
            // substitute the following string with the path to a local file or multiple files you want to upload
            'path/to/file'
        ]);
});

Take Screenshot

These actions allow you to take screenshots of the tested page.

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://js.devexpress.com`;

test('Take Screenshot test', async t => {
    await t
        .takeScreenshot()
        .takeElementScreenshot('.map-container');
});

Work With Iframes

A TestCafe test's browsing context is limited to the main window or an <iframe>. To use an <iframe> in your test, switch the context from the main window to this <iframe>. You may need to switch back to the main window. If multiple <iframes> are present in your test, you should switch between them.

Use the following methods to switch between windows and iframes:

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://js.devexpress.com/Demos/WidgetsGallery/Demo/DataGrid/Overview/jQuery/Light/`;

test('Working With iframe test', async t => {
    await t
        .switchToIframe('.demo-frame')
        .click('.dx-datagrid-group-panel')
        .switchToMainWindow();
});

Handle Native Dialogs

TestCafe allows you to handle native dialogs that the browser may display during the test run.

You can close alert and beforeunload dialogs, choose an option in confirm dialogs or supply text for prompt dialogs.

Resize Window

Use resize window actions to maximize a browser window or resize it to fit a specified width and height or type of device.

Window resize actions are not supported when you run tests in remote browsers.

Note: These actions require a Windows machine with .NET 4.0 or newer, or a Linux machine with an ICCCM/EWMH-compliant window manager.

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://js.devexpress.com`;

test('Resize Window test', async t => {
    await t
        .resizeWindowToFitDevice('iphonexr')
        .maximizeWindow();
});

Wait

Wait action allows you to pause the test for a specified period of time.

Example

import { Selector } from 'testcafe';

fixture `Example`
    .page `https://js.devexpress.com`;

test('Wait test', async t => {
    await t
        .hover('.map-container')
        .wait(1000);
});

Remarks for Touch Devices

On touch devices, TestCafe emulates touch events instead of mouse events.

Mouse event Touch event
mousemove (when you hover or drag) touchmove (when you drag)
mousedown touchstart
mouseup touchend

Interaction Requirements

TestCafe actions can interact with elements if they satisfy the following conditions:

  • an element is within the body element of a page window or an <iframe> window. The element can be invisible to the user. If an element is outside of the viewport, TestCafe tries to reach it with a scroll.

  • an element is visible, with the following properties:

    Property Value
    display not set to none
    visibility set to visible (the default value)
    width >= 1px
    height >= 1px

  • an element is not overlapped.

    TestCafe actions target the center of an element or a point specified by an action's offsetX and offsetY options. If another element obstructs the target point, the action is executed on the top element (for instance, the t.click action clicks the element over it).

Examples

Download Files in IE

TestCafe cannot prevent native dialogs before file download in Internet Explorer. This dialog prevents automatic file download, but does not block the page.

The following example shows how to ignore the dialog and download the file:

<body>
    <form method="get" action="./src/file.zip">
        <button id="downloadButton" type="submit">Download!</button>
     </form>
</body>

This sample page includes a button that downloads a file from the /src folder on the server. To obtain the file, use a RequestLogger:

import { RequestLogger } from 'testcafe';

const fileDownloadLogger = RequestLogger(new RegExp('src/file.zip'), {
    logResponseBody: true,
    stringifyResponseBody: true
});

fixture `fixture`
    .page `./fileDownload.html`
    .requestHooks(fileDownloadLogger);

test(`Download a file and verify contents`, async t => {
    await t
        .click('#downloadButton')
        .expect(fileDownloadLogger.contains(r => {
            return  /File contents here/.test(r.response.body) &&   //verify response body
                    r.response.statusCode === 200;                  //verify response status code
        })).ok()
});

This test introduces a RequestLogger that logs requests to a location and received responses. Location is defined with a regular expression. The response body is then checked with a regular expression.

The response body received from the server is binary. Use the RequestLogger's stringifyResponseBody option to convert it to a string.

Scroll an Element into View

Since TestCafe scrolls to reach items that are on the page but not on-screen, the TestCafe API does not have a dedicated scroll action.

You can use any action (for example, hover) to scroll towards the desired part of the page.

If you specifically need to scroll the page without any action, use a ClientFunction.

import { ClientFunction } from 'testcafe';

const scrollBy = ClientFunction(() => {
    window.scrollBy(0, 1000);
});

test('Test', async t => {
      await scrollBy();
});