Test Structure

This article describes how to structure TestCafe files.

Note

Use the TestCafe Setup Wizard to populate your project with sample tests.

Article Summary

TestCafe test files consist of fixtures. Fixtures are groups of tests that share the same starting URL. Hooks run before and after other parts of the test suite. You can attach hooks to fixtures, tests, and entire test runs.

Example: 

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

test('Test1', async t => {
    // Starts at http://devexpress.github.io/testcafe/example
});

Table of Contents

Fixtures

Note

If you use eslint, install the TestCafe plugin to avoid the 'fixture' is not defined and 'test' is not defined errors.

TestCafe test files begin with a fixture declaration. A fixture is a group of tests. Every test belongs to a fixture.

It is best to use one fixture per test file. If your test suite contains tests with different starting URLs, place these tests into several test files - one for each starting URL. Alternatively, you can specify the starting URL on a test-by-test basis.

Declare a fixture

Declare a fixture with the fixture keyword.

fixture`Test structure`

The fixture.page method defines the starting URL of the tests in the fixture. If you set a suite-wide base URL, you can omit this method.

Absolute fixture URL

An absolute fixture URL takes priority over the suite-wide base URL.

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

test('Test1', async t => {
    // Starts at http://devexpress.github.io/testcafe/example
});

Relative fixture URL

If you set a suite-wide base URL, you can define a relative starting URL for the tests in the fixture. Relative URLs begin with the period character (.).

For example, if your configuration file contains the following declaration:

    "baseUrl": "https://devexpress.github.io/testcafe"

You can define your fixture URL as such:

fixture`Test structure`
    .page`./example`;

test('Test1', async t => {
    // Starts at http://devexpress.github.io/testcafe/example
});

Tests

Tests belong to fixtures. The code for tests that constitute a particular fixture follow that fixture’s declaration.

Declare a Test

Declare a test with the test keyword. Pass two arguments to the test function - a string with the test’s name and an asynchronous function with test content.

fixture`Test structure`;

test('Test1', async t => {
    /* Test 1 Code */
});

test('Test2', async t => {
    /* Test 2 Code */
});

The asynchronous function with the test content needs to receive the test controller t object as an argument. The test controller object provides access to the TestCafe test API.

Specify Test Content

Use TestCafe actions to interact with the page. Use element selectors and client functions to retrieve client-side information. Use assertions to evaluate page data and determine if a test is successful.

The internal structure of TestCafe tests is up to the individual user. TestCafe tests may include any code, as long as it is valid. TestCafe tests can reference third-party libraries and communicate with other APIs.

Specify a Custom Starting URL

Use the test.page function to override the starting URL from the fixture definition.

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

test('My test', async t => {
    // Starts at http://devexpress.github.io/testcafe/blog/
}).page`https://devexpress.github.io/testcafe/blog/`;

Relative test URL

If you set a suite-wide base URL, you can define a relative starting URL for the test. Relative URLs begin with the period character (.).

For example, if your configuration file contains the following declaration:

    "baseUrl": "https://devexpress.github.io/testcafe"

You can define a custom test URL as such:

fixture`Test structure`
    .page`./example`;

test('Test1', async t => {
    // Starts at http://devexpress.github.io/testcafe/example
});

Hooks

Note

Test hooks and request hooks are different entities. Read the Request Interception Guide for more information on request hooks.

Hooks are functions that run immediately before or immediately after other test entities. You can attach hooks to the following test entities: tests, fixtures, and test runs.

“Before” hooks often prepare the testing environment (for example, to authenticate the user) for future tests. Likewise, “after” hooks often ‘reset’ the testing environment (for example, to remove a database object) after the end of a test.

You can attach a single hook to multiple entities of the same kind, which helps you reuse setup and teardown code.

Hook Types

Hooks by entity

The following two hooks run before and after test runs:

  • testRun.before
  • testRun.after

The following two hooks run before and after fixtures:

The following four hooks run before and after tests:

Local Hooks and Global Hooks

Local hooks reside inside individual test files. These hooks do not affect the rest of the test suite.

Global hooks apply to your entire test suite. You can only define them in a JavaScript configuration file.

Test and fixture hooks can be either local or global. Test run hooks are only global.

Read the Hooks guide to learn more.