Assert

You can use assertions to check if the tested page's state matches the expected state.

TestCafe provides a comprehensive set of assertions that are based on the Behavior-Driven Development style (BDD-style).

This topic consists of the following sections:

Assertion Structure

To construct assertions, use the test controller's expect method.

The t.expect method is followed by an assertion method that accepts an expected value and optional arguments.

The following example shows the structure of the deep equality assertion:

await t.expect( actual ).eql( expected, message, options );

The code snippet below demonstrates how to use assertions in a test:

import { Selector } from 'testcafe';


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


test('Check property of element', async t => {
   const developerNameInput = Selector('#developer-name');

   await t
       .expect(developerNameInput.value).eql('', 'input is empty')
       .typeText(developerNameInput, 'Peter Parker')
       .expect(developerNameInput.value).contains('Peter', 'input contains text "Peter"');
});

The following assertion methods are available:

Smart Assertion Query Mechanism

In synchronous functional testing, you can execute assertions immediately after test actions.

Synchronous Functional Testing

Functional tests are asynchronous on the web. This means that we cannot get the expected changes immediately after a user's actions. For example, it can take time for the tested page to send a request to the server for the required data or a user's action to invoke an animation after which the page reaches its final state. All these intervals cannot be pre-calculated because they depend on various factors: computer performance, network connection speed, etc. In this case, if we perform assertions immediately after the test action, we can get an inconclusive result.

Asynchronous Functional Testing

An additional timeout is usually added when performing asynchronous functional tests.

Asynchronous Functional Testing with Extra Waiting

To stabilize asynchronous functional tests, you need to add a timeout that allows changes to be applied. Note that adding a timeout can increase the test's duration.

TestCafe uses the smart assertion query mechanism if the assertion receives a Selector's DOM node state property or client function promise as an actual value: if an assertion did not pass, the test does not fail immediately. The assertion retries to pass multiple times, and each time it requests the actual property value. The test fails if the assertion could not complete successfully within a timeout:

TestCafe Smart Assertion Query Mechanism

Example:

The following web page is an example:

<div id="btn"></div>
<script>
var btn = document.getElementById('btn');

btn.addEventListener('click', function() {
    window.setTimeout(function() {
        btn.innerText = 'Loading...';
    }, 100);
});
</script>

Test code for this page can be as follows.

test('Button click', async t => {
    const btn = Selector('#btn');

    await t
        .click(btn)
        // A regular assertion fails immediately, but TestCafe retries to run DOM state
        // assertions many times within the timeout until this assertion passes successfully.
        // The default timeout is 3000 ms.
        .expect(btn.textContent).contains('Loading...');
});

The approach described above allows you to create stable tests with fast runtime and reduces the risk of errors.

You can specify the assertion query timeout in test code with the options.timeout option. To set the timeout when you launch tests, pass the timeout value to the runner.run method if you use API or specify the assertion-timeout option if you run TestCafe from the command line.

Options

options.timeout

Type: Number

The time (in milliseconds) an assertion can take to pass before the test fails if a selector property or client function promise is used.

Default value: The timeout is specified with the runner.run API method or the assertion-timeout command line option.

await t.expect(Selector('#elementId').innerText).eql('text', 'check element text', { timeout: 500 });

In addition to built-in assertions, you also can use assertions from Node.js's assert module or 3rd-party library (for example chai). In this case, specify the time required to complete asynchronous actions with the t.wait(timeout) method.

options.allowUnawaitedPromise

Only promises the selectors and client functions return can be passed as the assertion's actual value. If you pass a regular unawaited promise, TestCafe throws an error.

If you need to assert a regular promise, set the allowUnawaitedPromise option to true.

await t.expect(doSomethingAsync()).ok('check that a promise is returned', { allowUnawaitedPromise: true });