Runner Class

An object that configures and launches test tasks.

Created using the testCafe.createRunner function.


const createTestCafe = require('testcafe');
let testcafe         = null;

createTestCafe('localhost', 1337, 1338)
    .then(tc => {
        testcafe     = tc;
        const runner = testcafe.createRunner();

        return runner
            .src(['tests/fixture1.js', 'tests/func/fixture3.js'])
            .browsers(['chrome', 'safari'])
    .then(failedCount => {
        console.log('Tests failed: ' + failedCount);



Configures the test runner to run tests from the specified files.

src(source) → this
Parameter Type Description
source String | Array The relative or absolute path to a test fixture file, or several such paths. You can use glob patterns to include (or exclude) multiple files.

TestCafe can run:

  • JavaScript, TypeScript and CoffeeScript files that use TestCafe API,
  • TestCafe Studio tests (.testcafe files),
  • Legacy TestCafe v2015.1 tests.

You do not need to call this function if you specify the src property in the configuration file.

Related configuration file property: src


runner.src(['/home/user/js-tests/fixture.js', 'studio-fixture.testcafe']);
runner.src(['/home/user/tests/**/*.js', '!/home/user/tests/foo.js']);


Allows you to select which tests should be run.

filter(callback) → this
Parameter Type Description
callback function(testName, fixtureName, fixturePath, testMeta, fixtureMeta) The callback that determines if a particular test should be run.

The callback function is called for each test in the files the src method specifies.

Return true from the callback to include the current test or false to exclude it.

The callback function accepts the following arguments:

Parameter Type Description
testName String The name of the test.
fixtureName String The name of the test fixture.
fixturePath String The path to the test fixture file.
testMeta Object The test metadata.
fixtureMeta Object The fixture metadata.

Related configuration file property: filter


runner.filter((testName, fixtureName, fixturePath, testMeta, fixtureMeta) => {
    return fixturePath.startsWith('D') &&
        testName.match(someRe) &&
        fixtureName.match(anotherRe) && === 'true' &&
        fixtureMeta.env === 'staging';


Configures the test runner to run tests in the specified browsers.

browsers(browser) → this

The browser parameter can be any of the following objects or an Array of them:

Parameter Type Description Browser Type
String | Array A different browser alias for each browser type. See Browser Support for more details. Local browsers, cloud browsers, and browsers accessed through browser provider plugins.
{path: String, cmd: String} The path to the browser's executable (path) and command line parameters (cmd). The cmd property is optional. Local and portable browsers
BrowserConnection The remote browser connection. Remote browsers

You do not need to call this function if you specify the browsers property in the configuration file.

Related configuration file property: browsers

Using Browser Aliases

  • running local browsers
runner.browsers(['safari', 'chrome']);
  • running browsers accessed through browser provider plugins
runner.browsers('saucelabs:Chrome@52.0:Windows 8.1');

Specifying the Path to the Browser Executable

Use the path: prefix. Enclose the path in backticks if it contains spaces.

runner.browsers('path:`C:\\Program Files\\Internet Explorer\\iexplore.exe`');

Specifying the Path with Command Line Parameters

    path: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
    cmd: '--new-window'

Headless Mode, Device Emulation and User Profiles

You can add postfixes to browser aliases to run tests in the headless mode, use Chrome device emulation or user profiles.


For portable browsers, use the browser alias followed by the path to an executable.


The path: prefix does not support postfixes.

Passing a Remote Browser Connection

const createTestCafe = require('testcafe');
let runner           = null;
let testcafe         = null;

createTestCafe('localhost', 1337, 1338)
    .then(tc => {
        testcafe = tc;
        runner   = testcafe.createRunner();

        return testcafe.createBrowserConnection();
    .then(remoteConnection => {

        // Outputs remoteConnection.url so that it can be visited from the remote browser.

        remoteConnection.once('ready', () => {
                .then(failedCount => {


Specifies how TestCafe should take screenshots of the tested pages.

screenshots(options) → this
obsolete: screenshots(path [, takeOnFails] [, pathPattern] ) → this

The options object can include the following properties:

Option Type Description Default
path (optional) String The base path where the screenshots are saved. Note that to construct a complete path to these screenshots, TestCafe uses the default path patterns. You can override these patterns using the pathPattern property. './screenshots'
takeOnFails (optional) Boolean Specifies if screenshots should be taken automatically when a test fails. false
pathPattern (optional) String The pattern to compose screenshot files' relative path and name. See Path Pattern Placeholders for information about the available placeholders.
fullPage (optional) Boolean Specifies that the full page should be captured, including content that is not visible due to overflow. false

See Screenshots for details.

Pass the disableScreenshots option to the method to disable screenshots:{
    disableScreenshots: true

Related configuration file properties:


    path: 'reports/screenshots/',
    takeOnFails: true,
    pathPattern: '${DATE}_${TIME}/test-${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png'


Enables TestCafe to record videos of test runs.

video(path [, options, encodingOptions]) → this
Parameter Type Description
path String The base directory where videos are saved. Relative paths to video files are composed according to path patterns. You can also use the options.pathPattern property to specify a custom pattern.
options (optional) Object Options that define how videos are recorded. See Basic Video Options for a list of options.
encodingOptions (optional) Object Options that specify video encoding. You can pass all the options supported by the FFmpeg library. Refer to the FFmpeg documentation for information about the available options.

See Record Videos for details.

Related configuration file properties:

Example'reports/videos/', {
    singleFile: true,
    failedOnly: true,
    pathPattern: '${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.mp4'
}, {
    r: 20,
    aspect: '4:3'


Configures TestCafe's reporting feature.

reporter(name, output) → this
reporter(fn) → this
reporter([ name | { name, output } | fn ]) → this
Parameter Type Description Default
name String The name of the reporter.
output (optional) String | Writable Stream implementer The file path where the report is written or the output stream. stdout
fn A function that returns a custom reporter object.

To use a single reporter, specify a reporter name and, optionally, an output target as the second parameter.

To use multiple reporters, pass an array to this method. This array can include both strings (the reporter name) and { name, output } objects (if you wish to specify the output target). See examples below.

Note that if you use multiple reporters, only one can write to stdout.

Related configuration file property: reporter

Specifying the Reporter


Saving the Report to a File

runner.reporter('xunit', 'reports/report.xml');

Using Multiple Reporters

runner.reporter(['spec', {
    name: 'json',
    output: 'reports/report.json'

Specifying a Custom Reporter

You can implement a custom reporter in the code that launches tests. This approach allows you to implement your reporter faster if you need it for a single project or do not want to publish a reporter plugin.

Pass a function that returns the custom reporter object to the runner.reporter method.

import { createTestCafe } from 'testcafe';

const customReporter = () => {
    return {
        async reportTaskStart (startTime, userAgents, testCount) { /* ... */ },
        async reportFixtureStart (name, path, meta) { /* ... */ },
        async reportTestDone (name, testRunInfo, meta) { /* ... */ },
        async reportTaskDone (endTime, passed, warnings, result) { /* ... */ }

const testcafe = await createTestCafe(/* [...] */);
const runner   = testcafe.createRunner();

await runner.reporter(customReporter);

Implementing a Custom Stream

class MyStream extends stream.Writable {
    _write(chunk, encoding, next) {

const stream = new MyStream();
runner.reporter('json', stream);

You can also build your own reporter. Use a dedicated Yeoman generator to scaffold out a reporter plugin.


Specifies that tests should run concurrently.

concurrency(n) → this

TestCafe opens n instances of the same browser and creates a pool of browser instances. Tests are run concurrently against this pool, that is, each test is run in the first available instance.

The concurrency function takes the following parameters:

Parameter Type Description
n Number The number of browser instances that are invoked.

See Concurrent Test Execution to learn more about concurrent test execution.

Related configuration file property: concurrency

The following example shows how to run tests in three Chrome instances:



Specifies a shell command that is executed before running tests. Use it to launch or deploy the application that is tested.

async startApp(command, initDelay) → this

After the testing is finished, the application is automatically terminated.

The startApp function takes the following parameters:

Parameter Type Description Default
command String The shell command to be executed.
initDelay (optional) Number The amount of time (in milliseconds) allowed for the command to initialize the tested application.

TestCafe adds node_modules/.bin to PATH so that you can use binaries the locally installed dependencies provide without prefixes.

Related configuration file properties:


runner.startApp('node server.js', 4000);


Injects scripts into pages visited during the tests. Use this method to introduce client-side mock functions or helper scripts.

async clientScripts( script[, script2[, ...[, scriptN]]] ) → this
Parameter Type Description
script, script2, scriptN String | Object | Array Scripts to inject into the tested pages. See Provide Scripts to Inject to learn how to specify them.

Relative paths are resolved against the current working directory.

You can use the page option to specify pages into which scripts should be injected. Otherwise, TestCafe injects scripts into all pages visited during the test run.

        module: 'lodash'
        path: 'scripts/react-helpers.js',
        page: ''

The fixture.clientScripts and test.clientScripts methods allow you to inject scripts into pages visited during an individual fixture or test.

See Inject Scripts into Tested Pages for more information.

Related configuration file property: clientScripts


Specifies the proxy server used in your local network to access the Internet. Allows you to bypass the proxy when accessing specific resources.

async useProxy(host [, bypassRules]) → this
Parameter Type Description
host String The proxy server host.
bypassRules (optional) String | Array A set of rules that specify which resources are accessed bypassing the proxy.

If you access the Internet through a proxy server, use the useProxy method to specify its host.

When using a proxy server, you may still need to access local or external resources directly. In this instance, provide their URLs in the bypassRules option.

The bypassRules parameter takes one or several URLs that require direct access. You can replace parts of the URL with the * wildcard that corresponds to a string of any length. Wildcards at the beginning and end of the rules can be omitted (* and have the same effect).

Related configuration file properties:


The following example shows how to use the proxy server at


In the example below, the proxy server address is and two resources at localhost:8080 and are accessed directly.

runner.useProxy('', ['localhost:8080', '']);

The * proxy bypass rule means that all URLs in subdomains are accessed directly.

runner.useProxy('', '*');

You can also use the proxy host to specify authentication credentials.



Enables TestCafe to use a custom TypeScript configuration file and specifies its location.

async tsConfigPath(path) → this
Parameter Type Description
path String The absolute or relative path to the TypeScript configuration file. Relative paths are resolved against the current directory (the directory from which you run TestCafe).

Related configuration file property: tsConfigPath


Runs tests according to the current configuration. Returns the number of failed tests.

async run(options) → Promise<Number>

Before TestCafe runs tests, it reads settings from the .testcaferc.json configuration file if this file exists. Then it applies settings specified in the programming API. API settings override values from the configuration file in case they differ. TestCafe prints information about every overridden property in the console.

Make sure to keep the browser tab that is running tests active. Do not minimize the browser window. Inactive tabs and minimized browser windows switch to a lower resource consumption mode where tests are not guaranteed to execute correctly.

You can pass the following options to the function.

Parameter Type Description Default
skipJsErrors Boolean Defines whether to continue running a test after a JavaScript error occurs on a page (true), or consider such a test failed (false). false
skipUncaughtErrors Boolean Defines whether to continue running a test after an uncaught error or unhandled promise rejection occurs on the server (true), or consider such a test failed (false). false
quarantineMode Boolean Defines whether to enable the quarantine mode. false
debugMode Boolean Specifies if tests run in the debug mode. If this option is enabled, test execution is paused before the first action or assertion allowing you to invoke the developer tools and debug. In the debug mode, you can execute the test step-by-step to reproduce its incorrect behavior. You can also use the Unlock page switch in the footer to unlock the tested page and interact with its elements. false
debugOnFail Boolean Specifies whether to enter the debug mode when a test fails. If enabled, the test is paused at the moment it fails, so that you can explore the tested page to determine what caused the failure. false
selectorTimeout Number Specifies the time (in milliseconds) within which selectors make attempts to obtain a node to be returned. See Selector Timeout. 10000
assertionTimeout Number Specifies the time (in milliseconds) within which TestCafe makes attempts to successfully execute an assertion if a selector property or a client function was passed as an actual value. See Smart Assertion Query Mechanism. 3000
pageLoadTimeout Number Specifies the time (in milliseconds) TestCafe waits for the window.load event to fire after the DOMContentLoaded event. After the timeout passes or the window.load event is raised (whichever happens first), TestCafe starts the test. You can set this timeout to 0 to skip waiting for window.load. 3000
speed Number Specifies the test execution speed. A number between 1 (fastest) and 0.01 (slowest). If an individual action's speed is also specified, the action speed setting overrides the test speed. 1
stopOnFirstFail Boolean Defines whether to stop a test run if a test fails. You do not need to wait for all the tests to finish to focus on the first error. false
disablePageCaching Boolean Prevents the browser from caching page content. When navigation to a cached page occurs in role code, local and session storage content is not preserved. Set disablePageCaching to true to retain the storage items after navigation. For more information, see Troubleshooting: Test Actions Fail After Authentication. You can also disable page caching for an individual fixture or test.
disableScreenshots Boolean Prevents TestCafe from taking screenshots. When this option is specified, screenshots are not taken whenever a test fails or a screenshot action is executed.

After all tests are finished, call the testcafe.close function to stop the TestCafe server.

Related configuration file properties:


const createTestCafe = require('testcafe');
let testcafe         = null;

createTestCafe('localhost', 1337, 1338)
    .then(tc => {
        testcafe     = tc;
        const runner = testcafe.createRunner();

            skipJsErrors: true,
            quarantineMode: true,
            selectorTimeout: 50000,
            assertionTimeout: 7000,
            pageLoadTimeout: 8000,
            speed: 0.1,
            stopOnFirstFail: true
    .then(failed => {
        console.log('Tests failed: ' + failed);
    .catch(error => { /* ... */ });

If a browser stops responding while it executes tests, TestCafe restarts the browser and reruns the current test in a new browser instance. If the same problem occurs with this test two more times, the test run finishes and an error is thrown.

When you use a LiveModeRunner, you can call the method only once. In rare cases when you need multiple live mode sessions running in parallel, you can create several TestCafe server instances.

Cancelling Test Tasks

You can stop an individual test task at any moment by cancelling the corresponding promise.

const taskPromise = runner
    .browsers([remoteConnection, 'chrome'])


You can also cancel all pending tasks at once using the runner.stop function.

Quarantine Mode

The quarantine mode is designed to isolate non-deterministic tests (that is, tests that pass and fail without any apparent reason) from the other tests.

When the quarantine mode is enabled, tests run according to the following logic:

  1. A test runs at the first time. If it passes, TestCafe proceeds to the next test.
  2. If the test fails, it runs again until it passes or fails three times.
  3. The most frequent outcome is recorded as the test result.
  4. If the test result differs between test runs, the test is marked as unstable.

Note that it increases the test task's duration if you enable quarantine mode on your test machine because failed tests are executed three to five times.

See Martin Fowler's Eradicating Non-Determinism in Tests article for more information about non-deterministic tests.


Stops all the pending test tasks.

async stop()

You can also stop an individual pending task by cancelling the corresponding promise.