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 and applies settings specified in the programming API. API settings override values from the configuration file. TestCafe prints information about every overridden property in the console.


Make sure the browser tab that runs tests stays 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 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 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 so that you can 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
ajaxRequestTimeout Number Wait time (in milliseconds) for fetch/XHR requests. If no response is received within the specified period, an error is thrown. 120000
pageRequestTimeout Number Time (in milliseconds) to wait for HTML pages. If the page isn’t received within the specified period, an error is thrown. 25000
browserInitTimeout Number Time (in milliseconds) for browsers to connect to TestCafe and report that they are ready to test. If one or more browsers fail to connect within this period, TestCafe throws an error. 120000 for local browsers, 360000 for remote browsers
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 Stops the test run if a test fails. You can focus on the first error before all the tests finish. 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. false
disableScreenshots Boolean Prevents TestCafe from taking screenshots. When this option is specified, screenshots are not taken whenever a test fails or when t.takeScreenshot or t.takeElementScreenshot is executed. false
disableMultipleWindows Boolean Disables support for multi-window testing in Chrome and Firefox. Use this option if you encounter compatibility issues with your existing tests.

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

Related configuration file properties:


const createTestCafe = require('testcafe');

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

try {
    const runner = testcafe.createRunner();

    const failed = await{
        skipJsErrors: true,
        quarantineMode: true,
        selectorTimeout: 50000,
        assertionTimeout: 7000,
        pageLoadTimeout: 8000,
        speed: 0.1,
        stopOnFirstFail: true

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

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, call the method once. To run multiple live mode sessions simultaneously, create multiple TestCafe server instances.

Cancel Test Tasks

To stop an individual test task, cancel a promise returned by

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


You can cancel all pending tasks with the runner.stop method.