Runner.run Method

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 runs 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 runner.run 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
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. 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

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

Related configuration file properties:

Example

const createTestCafe = require('testcafe');

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

try {
    const runner = testcafe.createRunner();

    const failed = await runner.run({
        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, you can call the runner.run method only once. In rare cases when you need multiple live mode sessions to run in parallel, you can create several TestCafe server instances.

Cancel Test Tasks

You can cancel a promise returned by 'runner.run' to stop an individual test task:

const taskPromise = runner
    .src('tests/fixture1.js')
    .browsers([remoteConnection, 'chrome'])
    .reporter('json')
    .run();

taskPromise.cancel();

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