Getting Started

In this article

This article describes the basics of TestCafe for readers with zero prior TestCafe experience. It requires basic familiarity with JavaScript, the web, and the command line.

What Is TestCafe?

TestCafe is an end-to-end testing framework for web applications. TestCafe runs on Node.js. TestCafe supports all three major operating systems — Linux, Windows, and macOS.

You can use TestCafe to simulate common user scenarios in major desktop browsers, cloud browsers, and on mobile devices. If your website malfunctions, TestCafe reports can help you diagnose the issue.

Install TestCafe

Main article: Install TestCafe

Install TestCafe


TestCafe requires a recent version of the Node.js platform. Run the following command to confirm that your setup includes Node.js:

node --version

The best way to install the TestCafe framework is to use npm — the most popular Node.js package manager. The NPM repository hosts ready-to-use builds of the framework. Confirm that your setup contains an up-to-date version of the package manager:

npm --version


Run the following command to install the testcafe package from npm:

npm install -g testcafe

Create a new test

Main article: Test Structure

Let’s create a simple test for the TestCafe demo page.

New test file

  1. TestCafe tests are Node.js scripts. Create a new TypeScript or JavaScript file, and open the file in the text editor.

  2. TestCafe test files consist of fixtures and tests. A fixture is a groups of tests that share the same starting URL. Invoke the fixture keyword to create a new fixture.

    fixture('Getting Started')
  3. Use the page method to set the starting URL of the fixture.

    fixture('Getting Started')
  4. Finally, declare a new test with the test method.

    fixture('Getting Started')
    test('My first test', async t => {
        // Test code goes here

Add test actions

Main article: Test Actions

Let’s add two simple actions to the “My first test” test function.

Test actions

Action 1: Type text

The first action — t.typeText — populates the #developer-name input field with a dummy name:

await t.typeText('#developer-name', 'John Smith');

The first argument is a CSS Selector that identifies the target element. We want to target the input field with the developer-name ID. The appropriate keyword for this element is #developer-name.

The second argument contains the input value. The name of our imaginary developer is John Smith. We can just pass this string to the method without any modifications.

Action 2: Click the button

The second action — — clicks the “Submit” button:


This action requires a single argument — a CSS Keyword that identifies the target element.

Chain multiple actions

Let’s chain these actions together. Action chains make your code easier to read.

fixture('Getting Started')

test('My first test', async t => {
    await t
        .typeText('#developer-name', 'John Smith')

Add a success condition

Tests without an explicit success condition are inconclusive.

All TestCafe tests fail if one of the following events occurs:

  1. HTTP Request failure. If TestCafe cannot reach the test page URL, the test fails.
  2. Action failure. If TestCafe cannot perform a test action — for example, if the target element does not exist — the test fails.
  3. JavaScript error. If your page throws a JavaScript error, the test fails.

These criteria confirm that TestCafe is able to perform all test actions without encountering a critical failure. But they don’t confirm that the actions have had the desired effect. That’s why you should add assertions (custom success conditions) to your test.

When we click the “Submit” button, the application should open a page that greets the developer by name. Follow these steps to create an assertion and check if that is the case:

  1. Create an assertion.
  2. Add a query that examines the page header to the left-hand side of the assertion.
  3. Add the expected value of the header to the right-hand side of the assertion.
  4. Add the assertion to the action chain.

1. Create an assertion

Main article: Assertions

Use an assertion to compare the actual value of the greeting to your expectations.

Assertions are comparisons that determine the test’s success. If the comparison fails, so does the test.

  • Assertions start with the t.expect() declaration.
  • Assertions consist of two parts that correspond to the two comparanda.
  • The assertion method that connects the two parts determines the nature of the comparison.

Add the following assertion to your test:

await t.expect(x).eql(y);

This assertion compares the value of x to the value of y, and succeeds if they are equal. Later in this tutorial, we will replace the x with the header’s actual value, and the y with the header’s expected value.

2. Examine the page

Main article: Element Selectors

The first argument of the assertion should include the actual value of the header. We can retrieve the content of the page’s header with a Selector query. Selectors filter the DOM, return page elements that match your criteria, and retrieve element properties.

  1. To use Selector queries, add the following import statement to the beginning of the file:

    import { Selector } from 'testcafe';
  2. Create a Selector query that matches the element with the article-header ID:

  3. To retrieve the element’s text content, add the innerText Selector method to the query:

  4. Place the Selector query into the left-hand side of the assertion:

    await t.expect(Selector('#article-header').innerText).eql(y);


When you place a Selector query inside an Assertion, the Selector becomes subject to the Smart Assertion Query Mechanism. If the query fails, TestCafe re-tries it within the assertion timeout. This failsafe makes your tests more stable.


Add the await keyword to execute a Selector query anywhere else in the test. For example:

const headerText = await Selector('#article-header').innerText

3. Define your expectations

Pass a string with the header’s expected value to the eql method:

await t.expect(Selector('#article-header').innerText).eql('Thank you, John Smith!');

This assertion executes the Selector query on the left and compares its value to the string on the right. It succeeds if the two values are the same.

4. Add the assertion to the action chain

import { Selector } from 'testcafe';

fixture('Getting Started')

test('My first test', async t => {
    await t
        .typeText('#developer-name', 'John Smith')
        .expect(Selector('#article-header').innerText).eql('Thank you, John Smith!');

Now that you have a working success condition, the test is complete.

Run the Test

Main article: Run tests

The easiest way to run TestCafe tests is to use the command line interface.

Test Launch

Specify the target browser and test file path. TestCafe opens the selected browser and starts test execution.

testcafe chrome getting-started.js

Reload tests on the fly

TestCafe can reload tests as you edit them. Enable live mode to take advantage of this capability:

testcafe chrome getting-started.js --live


You can interact with other applications while TestCafe runs your tests. However, do not switch away from the browser tab that runs the test or minimize the browser window. Inactive tabs and minimized browser windows may trigger a resource saving mode, which harms the test’s performance.

Do not zoom pages while testing. Tests may lose stability when you zoom the page in and out.

View Test Results

Main article: Reporters

TestCafe outputs real-time test results to the console.

Test Report

If a test fails, TestCafe outputs the error and highlights the failed action:

Test failure

What’s Next?

The following Basic Guides offer a deeper look at basic TestCafe capabilities: