API

This article offers a full overview of the TestCafe API.

Command Line API

Main article: Command Line Interface

The Command Line Interface is the simplest way to launch and configure TestCafe tests.

Specify browser aliases, the test file path, and launch options to run a test:

testcafe chrome,edge test.js -s takeOnFails=true

Use the command-line interface to troubleshoot your installation:

testcafe -b # Returns the list of system browsers

Test Runner API

Main article: Run Tests

The TestCafe Test Runner API enables users to launch and control TestCafe instances with Node.js scripts.

Functions

Objects

  • TestCafe

    The TestCafe object manages test runners and browser connections.

  • Runner

    The Runner object configures and launches test tasks.

  • LiveModeRunner

    The LiveModeRunner object configures and launches test tasks in live mode.

  • BrowserConnection

    The BrowserConnection object configures browser connections.

Methods

TestCafe methods

The following methods control TestCafe instances:

Runner methods

The following methods configure the behavior of TestCafe test runners:

BrowserConnection methods

The following method configures the remote browser connection:

Events

BrowserConnection events

  • opened

    The opened event fires when TestCafe establishes a browser connection.

Configuration File API

Main article: Configuration File

Important

Command line options and TestCafe Runner options have precedence over configuration file settings.

On startup, TestCafe looks for a configuration file (.testcaferc.js, .testcaferc.cjs, or .testcaferc.json) in the current working directory. You can store your TestCafe settings in this file.

  • JSON configuration files store settings in key-value pairs:
    {
    skipJsErrors: true,
    hostname: "localhost"
}

  • JavaScript configuration files store settings in key-value pairs within a module.exports statement. These files can contain definitions for custom test actions, global test hooks and global request hooks. Configuration properties in JavaScript files can reference JavaScript methods, functions, and variables, which makes it easy to create dynamic configuration files.

    let os = require("os");

module.exports = {
    skipJsErrors: true,
    hostname: os.hostname()
}

Test Controller API

Main article: Test actions

TestController methods interact with browsers and web pages. The TestController object is available from the test body, test hooks, and Role definitions. Import the { t } object from the testcafe module to use TestController methods elsewhere.

Objects

Properties

The following property stores fixture information:

The following property stores test information:

The following property stores browser information:

The following properties store user-defined variables:

Test context methods

The following methods switch test execution context:

Page action methods

The following methods interact with the page:

The following method fires a custom DOM event:

TestCafe users can create custom test actions. Refer to the Custom Actions section of this article for more information.

API testing methods

The request method sends HTTP requests and returns server responses.

Role activation methods

The following action activates a Role:

Cookie management methods

The following three methods manage page cookies:

Test interruption methods

The following method stops the test for debugging purposes:

The following method temporarily pauses the test:

Assertion API

Assertions are functions that compare two values to decide test success.

Assertion declaration

The following method declares a new assertion and defines the first operand. To complete an assertion, chain an assertion method to the assertion declaration.

Assertion methods

Assertion methods define the second operand of the assertion, as well as the nature of the comparison.

To complete an assertion, chain a single assertion method to the assertion declaration:

t.expect(x).contains(y);

Browser actions

Browser actions interact with the browser and its windows.

Navigation

The following method navigates to the specified URL:

Window actions

The following methods manage browser windows:

Note

Use the t.getCurrentWindow method to obtain browser window IDs.

Methods that retrieve data

Client-side

The following method evaluates client functions:

Server-side

The following methods retrieve browser data:

The following method retrieves CDP session data:

Methods that adjust test settings

The following methods adjust test settings:

Request hook methods

The following methods manage request hooks:

Custom Actions

Main article: Custom Test Actions

TestCafe users can define custom test actions in a JavaScript configuration file. Users can include these methods in their tests alongside regular TestController methods.

Warning

Do not override regular TestController methods with custom actions.

Use the this keyword to access the TestController object inside custom action definitions:

module.exports = {
  customActions: {
   async makeCoffee () {
        await this.click();
    }, 
  }
};

You can use custom actions anywhere the TestController object is available. If the custom action does not return a value, you can chain it:

test('Test with a custom action', async t => {
    await t.click().customActions.makeCoffee().click();
})

Fixture API

Main article: Test Structure

The Fixture API enables users to create and configure fixtures — groups of tests.

Global Functions

  • fixture

    The fixture global function defines a fixture.

Methods

Hook methods

The following fixture methods configure fixture hooks:

Methods that adjust fixture settings

The following methods define fixture settings:

Request hook methods

The following method configures request hooks for the fixture:

Test API

Main article: Test Structure

The Test API enables users to create and configure tests.

Global functions

  • test

    The test global function defines a new test.

Methods

Hook methods

The following test methods configure test hooks:

Request hook methods

The following method configures request hooks for the test:

Settings

The following methods define test settings:

Selector API

Main article: Element Selectors

The Selector API enables users to create and configure Element Selectors — queries that traverse the DOM and retrieve client-side information.

Import the { Selector } object from the testcafe module to access the Selector constructor in your test file.

Objects

  • Selector

    Use the Selector constructor to create a new Selector object.

  • DOMNodeState

    When you asynchronously execute a Selector query, the query returns a DOMNodeState object. This object includes information about the state of the first element that matches the Selector query. You can append DOMNodeState methods and properties to the Selector query itself.

Methods

Selector construction methods

The following method creates a new Selector instance:

The following method overrides Selector constructor options:

Selector refinement methods

The following methods process the return value of a Selector:

Methods that retrieve node attributes

If you want to asynchronously retrieve the attributes of the elements that match your Selector, append DOMNodeState methods to the query.

Properties

The following properties store information about Selector results:

If you want to asynchronously access the attributes of the element that matches your Selector, append DOMNodeState properties to the query.

Client Function API

Main article: Client Functions

The Client Function API enables users to execute client-side JavaScript functions.

Objects

The ClientFunction object executes client-side code and returns its return value.

Methods

Role API

Main article: Authentication and Roles

The Role API enables users to define Roles — reusable authentication routines.

Constructor

  • Role

    The Role constructor initializes a new Role.

Constructor Methods

  • Role.anonymous()

    The anonymous() Role method retrieves a static anonymous role.

To activate a Role in a test, use the following TestController method:

Request Hook API

Main article: Intercept HTTP Requests

The Request Hook API enables users to define request hooks — functions that fire in response to HTTP requests.

Objects

Methods

RequestHook methods

RequestHook methods initialize and customize RequestHook instances.

RequestLogger methods

RequestLogger methods initialize and customize RequestLogger instances.

See also: RequestLogger properties

RequestMock methods

RequestMock methods initialize and customize RequestMock instances.

Methods that add and remove Request Hooks

The following two TestController methods manage request hooks throughout the test:

The following fixture method configures request hooks for fixtures:

The following method configures request hooks for tests:

Properties

RequestLogger properties

TestCafe Plugin API

The Plugin API enables users to create plug-ins for TestCafe: custom browser providers and test reporters.

  • BrowserProvider

    Use the BrowserProvider interface to define a new browser provider.

  • Reporter

    Use the Reporter interface to define a new reporter.

Version Logger API

The Version Logger API enables users to add the TestCafe version number to tests and test reports.