Run Tests

This article describes how to launch TestCafe tests.

Basics

There are two ways to launch TestCafe tests.

The simplest option is to use the testcafe shell command. Alternatively, you can launch tests with the Test Runner API.

Command Line Interface

The command line interface of TestCafe is simple and straightforward. In most cases, it’s the preferred way to launch Test Cafe tests. There are two mandatory arguments: the target browser and the test file. You can configure the test run with options and flags. 

testcafe <browsers> <test files> <options>

Test Runner API

The Test Runner API is a Node.js API that can launch, configure and terminate TestCafe tests. It works with JavaScript and TypeScript.

Advantages

The Test Runner has the following advantages over the CLI:

  • You can introduce additional logic to gain fine control over the execution of your test suite.
  • You can repeat the same test in a number of different run configurations without restarting it by hand.
  • You can integrate TestCafe with your favorite Node.js tools, such as gulp, create-react-app, or Angular Builders.
  • You can commit the test launch script to version control, with all the maintenance benefits that entails.

Quick Guide

  1. Use the testcafe.createRunner method to create a Runner instance.
  2. Add configuration methods.
    • Use the runner.src to specify the test file path or directory.
    • Use the runner.browsers method to specify the browser(s) you would like to run tests in.
  3. Call the runner.run method to run tests.
  4. If necessary, stop the test run with the runner.stop method.

The following example runs two test files in chrome and safari:

const createTestCafe = require('testcafe');
const testcafe = await createTestCafe('localhost', 1337, 1338);

try {
    const runner = testcafe.createRunner();

    const failed = await runner
        .src(["tests/fixture1.js", "tests/func/fixture3.js"])
        .browsers(["chrome", "safari"])
        .run();

    console.log('Tests failed: ' + failed);
}
finally {
    await testcafe.close();
}

Select Target Browsers

TestCafe supports a wide array of modern browsers. Additionally, you can run tests on Mobile devices and mobile device emulators.

CLI

Specify the browser alias as the first command line argument.

testcafe chrome my-fixture.js

The command above launches tests in Google Chrome. If you want to launch tests in multiple browsers, separate the aliases with a comma:

testcafe chrome,firefox my-fixture.js

Use the all alias to launch the test in all your local browsers.

Runner

Use the runner.browsers method to select the target browser:

await runner
    .browsers('chrome')
    .src('./tests/')
    .run();

Pass an array of browser aliases to select multiple browsers:

await runner
    .browsers(['safari', 'chrome'])
    .src('./tests/')
    .run();

Use the all alias to launch the test in all your local browsers.

Read the advanced Browsers guide to learn about custom browsers, headless browsers, and more.

Select Test Files

CLI

Include the path to the test file or directory as the second command line argument:

testcafe chrome my-fixture.js

You can specify multiple test files and directories:

testcafe safari my-fixture.js ./studio/tests

Runner

Use the runner.src method to specify test files and test file directories:

await runner
    .src('my-fixture.js')
    .browsers('chrome')
    .run();

If you want to specify multiple test files and directories, store them in an array:

await runner
    .browsers('safari')
    .src(['my-fixture.js', './studio/tests'])
    .run();

Further Reading

Use filters to only launch tests that meet certain criteria.

Options and flags

There are several ways to configure your test run. Both CLI users and Runner users can save their settings to a configuration file.

Command line options and Test Runner options have precedence over configuration file settings. When TestCafe overrides a configuration file setting, it outputs a description of the conflict to the console.

CLI

CLI users can specify command line options. The example below executes tests from the my-tests folder at the 0.1 speed.

testcafe chrome my-tests --speed 0.1

Runner

Test Runner users can pass Test Runner Options to the runner.run method. The example below executes tests from the my-tests folder at the 0.1 speed:

const createTestCafe = require('testcafe');
const testcafe = await createTestCafe('localhost', 1337, 1338);

try {
    const runner = testcafe.createRunner();

    const failed = await runner
        .src(["my-tests"])
        .browsers(["chrome", "safari"])
        .run({
        speed: 0.1
    });

    console.log('Tests failed: ' + failed);
}
finally {
    await testcafe.close();
}

Use a Proxy

If your network uses a proxy to access the test page, you need to specify the proxy URL. Use the --proxy command line argument or the runner.useProxy API method:

testcafe chrome ./my-tests/ --proxy proxy.mycompany.com

await runner
    .browsers('chrome')
    .src('./my-tests/')
    .useProxy('proxy.mycompany.com')
    .run();

You can also specify URLs that should bypass the proxy. Pass the list of URLs in the --proxy-bypass command line argument or a runner.useProxy parameter:

testcafe chrome ./my-tests/ --proxy proxy.corp.mycompany.com --proxy-bypass localhost:8080

await runner
    .browsers('chrome')
    .src('./my-tests/')
    .useProxy('proxy.corp.mycompany.com', 'localhost:8080')
    .run();

You can also specify the proxy URL in the configuration file.

View Test Results

When the test run is over, TestCafe displays the test report in the command shell. The reporter determines the format of the output. TestCafe includes five built-in reporters.

The following screenshot shows the result of a successful test, as reported by spec, the default reporter.

Test Report

Feel free to create a custom reporter plugin, or use one of the community reporters.

Further Reading