Command Line Interface

testcafe [options] <browser-list-comma-separated> <file-or-glob ...>

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 do not always execute correctly.

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.

Browser List

The browser-list-comma-separated argument specifies the list of browsers (separated by commas) where tests are run.

You can specify different browser types in one command call.

Local Browsers

You can specify locally installed browsers using browser aliases or paths (with the path: prefix). Use the --list-browsers command to output aliases for automatically detected browsers.

The following example demonstrates how to run a test in several browsers. The browsers are specified differently: one using an alias, the other using a path.

testcafe chrome,path:/applications/ tests/sample-fixture.js

Use the all alias to run tests in all the installed browsers.

testcafe all tests/sample-fixture.js

Portable Browsers

You can specify portable browsers using paths to the browser's executable file (with the path: prefix), for example:

testcafe path:d:\firefoxportable\firefoxportable.exe tests/sample-fixture.js

If the path contains spaces, enclose it in backticks and additionally surround the whole parameter including the keyword in quotation marks.

In Windows cmd.exe (default command prompt), use double quotation marks:

testcafe "path:`C:\Program Files (x86)\Firefox Portable\firefox.exe`" tests/sample-fixture.js

In Unix shells like bash, zsh, csh (macOS, Linux, Windows Subsystem for Linux) and Windows PowerShell, use single quotation marks:

testcafe 'path:`C:\Program Files (x86)\Firefox Portable\firefox.exe`' tests/sample-fixture.js

Do not use the path: prefix if you need to run a browser in the headless mode, use device emulation or user profiles. Specify the browser alias in these cases.

Testing in Headless Mode

To run tests in the headless mode in Google Chrome or Firefox, use the :headless postfix:

testcafe "firefox:headless" tests/sample-fixture.js

See Testing in Headless Mode for more information.

Using Chrome Device Emulation

To run tests in Chrome's device emulation mode, specify :emulation and device parameters.

testcafe "chrome:emulation:device=iphone X" tests/sample-fixture.js

See Using Chrome Device Emulation for more details.

Remote Browsers

To run tests in a browser on a remote device, specify remote as a browser alias.

testcafe remote tests/sample-fixture.js

If you want to connect multiple browsers, specify remote: and the number of browsers. For example, if you need to use three remote browsers, specify remote:3.

testcafe remote:3 tests/sample-fixture.js

TestCafe provides URLs you should open in your remote device's browsers.

If you run tests concurrently, specify the total number of all browsers' instances after the remote: keyword.

You can also use the --qr-code option to display QR-codes that represent the same URLs. Scan the QR-codes using the device on which you are going to test your application. This connects the browsers to TestCafe and starts the tests.

Browsers Accessed Through Browser Provider Plugins

To run tests in cloud browsers or other browsers accessed through a browser provider plugin, specify the browser's alias that consists of the {browser-provider-name} prefix and the name of a browser (the latter can be omitted); for example, saucelabs:Chrome@52.0:Windows 8.1.

testcafe "saucelabs:Chrome@52.0:Windows 8.1" tests/sample-fixture.js

Starting browser with arguments

If you need to pass arguments for the specified browser, write them after the browser's alias. Enclose the browser call and its arguments in quotation marks.

In Windows cmd.exe (default command prompt), use double quotation marks:

testcafe "chrome --start-fullscreen" tests/sample-fixture.js

In Unix shells like bash, zsh, csh (macOS, Linux, Windows Subsystem for Linux) and Windows PowerShell, use single quotation marks:

testcafe 'chrome --start-fullscreen' tests/sample-fixture.js

You can also specify arguments for portable browsers. If a path to a browser contains spaces, the path should be enclosed in backticks.

For Unix shells and Windows PowerShell:

testcafe 'path:`/Users/TestCafe/Apps/Google` --start-fullscreen' tests/sample-fixture.js

For cmd.exe:

testcafe "path:`C:\Program Files (x86)\Google\Chrome\Application\chrome.exe` --start-fullscreen" tests/sample-fixture.js

Only installed and portable browsers located on the current machine can be launched with arguments.

File Path/Glob Pattern

The file-or-glob ... argument specifies the files or directories (separated by a space) from which to run these tests.

For example, this command runs all tests in the my-tests directory:

testcafe ie my-tests

The following command runs tests from the specified fixture files:

testcafe ie my-tests/fixture1.js my-tests/fixture2.js

You can also use globbing patterns to specify a set of files. For example, this command runs tests from files that match tests/*page*, namely tests/example-page.js and tests/main-page.js.

testcafe ie tests/*page*

If you do not specify any file or directory, TestCafe runs tests from the test or tests directories.


-h, --help

Displays commands' usage information.

testcafe --help

-v, --version

Displays the TestCafe version.

testcafe --version

-b, --list-browsers

Lists the aliases of the auto-detected browsers installed on the local machine.

testcafe --list-browsers

-r <name[:file],[...]>, --reporter <name[:file],[...]>

Specifies the name of a built-in or custom reporter that is used to generate test reports.

The following command runs tests in all available browsers and generates a report in xunit format:

testcafe all tests/sample-fixture.js -r xunit

The following command runs tests and generates a test report by using the custom reporter plugin:

testcafe all tests/sample-fixture.js -r my-reporter

The generated test report is displayed in the command prompt window.

If you need to save the report to an external file, specify the file path after the report name.

testcafe all tests/sample-fixture.js -r json:report.json

You can also use multiple reporters in a single test run. List them separated by commas.

testcafe all tests/sample-fixture.js -r spec,xunit:report.xml

Note that only one reporter can write to stdout. All other reporters must output to files.

-s <path>, --screenshots <path>

Enables screenshots and specifies the base directory where they are saved.

testcafe all tests/sample-fixture.js -s screenshots

Path Patterns

The captured screenshots are organized into subdirectories within the base directory. The following path patterns are used to define a relative path and name for screenshots the Take Screenshot actions take:

  • ${DATE}_${TIME}\test-${TEST_INDEX}\${USERAGENT}\${FILE_INDEX}.png if the quarantine mode is disabled;
  • ${DATE}_${TIME}\test-${TEST_INDEX}\run-${QUARANTINE_ATTEMPT}\${USERAGENT}\${FILE_INDEX}.png if the quarantine mode is enabled.

If TestCafe takes screenshots when a test fails (see --screenshots-on-fails option), the following path patterns are used:

  • ${DATE}_${TIME}\test-${TEST_INDEX}\${USERAGENT}\errors\${FILE_INDEX}.png;
  • ${DATE}_${TIME}\test-${TEST_INDEX}\run-${QUARANTINE_ATTEMPT}\${USERAGENT}\errors\${FILE_INDEX}.png if the quarantine mode is enabled.

You can also use the --screenshot-path-pattern option to specify a custom pattern.

-S, --screenshots-on-fails

Takes a screenshot whenever a test fails. Screenshots are saved to the directory specified in the -screenshots <path> option.

For example, the following command runs tests from the sample-fixture.js file in all browsers, takes screenshots if tests fail, and saves the screenshots to the screenshots directory:

testcafe all tests/sample-fixture.js -S -s screenshots

-p, --screenshot-path-pattern

Specifies a custom pattern to compose screenshot files' relative path and name. This pattern overrides the default path pattern.

You can use the following placeholders in the pattern:

Placeholder Description
${DATE} The test run's start date (YYYY-MM-DD).
${TIME} The test run's start time (HH-mm-ss).
${TEST_INDEX} The test's index.
${FILE_INDEX} The screenshot file's index.
${QUARANTINE_ATTEMPT} The quarantine attempt's number. If the quarantine mode is disabled, the ${QUARANTINE_ATTEMPT} placeholder's value is 1.
${FIXTURE} The fixture's name.
${TEST} The test's name.
${USERAGENT} The combination of ${BROWSER}, ${BROWSER_VERSION}, ${OS}, and ${OS_VERSION} (separated by underscores).
${BROWSER} The browser's name.
${BROWSER_VERSION} The browser's version.
${OS} The operation system's name.
${OS_VERSION} The operation system's version.
testcafe all tests/sample-fixture.js -s screenshots -p '${DATE}_${TIME}/test-${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png'

In Windows cmd.exe shell, use double quotes because single quotes do not escape spaces.

testcafe all tests/sample-fixture.js -s screenshots -p "${DATE} ${TIME}/test ${TEST_INDEX}/${USERAGENT}/${FILE_INDEX}.png"

-q, --quarantine-mode

Enables the quarantine mode for tests that fail.

testcafe all tests/sample-fixture.js -q

-d, --debug-mode

Specify this option to run tests in the debugging mode. In this mode, test execution is paused before the first action or assertion allowing you to invoke the developer tools and debug.

The footer displays a status bar in which you can resume test execution or skip to the next action or assertion.

Debugging status bar

If the test you run in the debugging mode contains a test hook, it is paused within this hook before the first action.

You can also use the Unlock page switch in the footer to unlock the tested page and interact with its elements.

-e, --skip-js-errors

When a JavaScript error occurs on a tested web page, TestCafe stops test execution and posts an error message and a stack trace to a report. To ignore JavaScript errors, use the -e(--skip-js-errors) option.

For example, the following command runs tests from the specified file and forces TestCafe to ignore JavaScript errors:

testcafe ie tests/sample-fixture.js -e

-u, --skip-uncaught-errors

When an uncaught error or unhandled promise rejection occurs on the server during test execution, TestCafe stops the test and posts an error message to a report. Note that if you run tests concurrently and such an error occurs in any test, all tests that are running at this moment will fail.

To ignore these errors, use the -u(--skip-uncaught-errors) option.

For example, the following command runs tests from the specified file and forces TestCafe to ignore uncaught errors and unhandled promise rejections:

testcafe ie tests/sample-fixture.js -u

-t <name>, --test <name>

TestCafe runs a test with the specified name.

For example, the following command runs only the "Click a label" test from the sample-fixture.js file:

testcafe ie tests/sample-fixture.js -t "Click a label"

-T <pattern>, --test-grep <pattern>

TestCafe runs tests whose names match the specified pattern.

For example, the following command runs tests whose names match Click.*. These can be Click a label, Click a button, etc.

testcafe ie my-tests -T "Click.*"

-f <name>, --fixture <name>

TestCafe runs a fixture with the specified name.

testcafe ie my-tests -f sample-fixture

-F <pattern>, --fixture-grep <pattern>

TestCafe runs fixtures whose names match the specified pattern.

For example, the following command runs fixtures whose names match Page.*. These can be Page1, Page2, etc.

testcafe ie my-tests -F "Page.*"

--test-meta <key=value[,key2=value2,...]>

TestCafe runs tests whose metadata matches the specified key-value pair.

For example, the following command runs tests whose metadata's device property is set to mobile, and env property is set to production.

testcafe chrome my-tests --test-meta device=mobile,env=production

--fixture-meta <key=value[,key2=value2,...]>

TestCafe runs tests whose fixture's metadata matches the specified key-value pair.

For example, the following command runs tests whose fixture's metadata has the device property set to the mobile value and the env property set to the production value.

testcafe chrome my-tests --fixture-meta device=mobile,env=production

-a <command>, --app <command>

Executes the specified shell command before running tests. Use it to set up the application you are going to test.

An application is automatically terminated after testing is finished.

testcafe chrome my-tests --app "node server.js"

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

Use the --app-init-delay option to specify the amount of time allowed for this command to initialize the tested application.

-c <n>, --concurrency <n>

Specifies that tests should run concurrently.

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 free instance.

See Concurrent Test Execution for more information about concurrent test execution.

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

testcafe -c 3 chrome tests/sample-fixture.js


Specifies whether to automatically enter the debug mode when a test fails.

If this option is enabled, TestCafe pauses the test when it fails. This allows you to view the tested page and determine the cause of the fail.

When you are done, click the Finish button in the footer to end test execution.

--app-init-delay <ms>

Specifies the time (in milliseconds) allowed for an application launched using the --app option to initialize.

TestCafe waits for the specified time before it starts running tests.

Default value: 1000

testcafe chrome my-tests --app "node server.js" --app-init-delay 4000

--selector-timeout <ms>

Specifies the time (in milliseconds) within which selectors attempt to obtain a node to be returned. See Selector Timeout.

Default value: 10000

testcafe ie my-tests --selector-timeout 500000

--assertion-timeout <ms>

Specifies the time (in milliseconds) TestCafe 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.

Default value: 3000

testcafe ie my-tests --assertion-timeout 10000

--page-load-timeout <ms>

Specifies the time (in milliseconds) passed after the DOMContentLoaded event, within which TestCafe waits for the window.load event to fire.

After the timeout passes or the window.load event is raised (whichever happens first), TestCafe starts the test.

Note that the DOMContentLoaded event is raised after the HTML document is loaded and parsed, while window.load is raised after all stylesheets, images and subframes are loaded. That is why window.load is fired after the DOMContentLoaded event with a certain delay.

Default value: 3000

You can set the page load timeout to 0 to skip waiting for the window.load event.

testcafe ie my-tests --page-load-timeout 0

--speed <factor>

Specifies the test execution speed.

Tests are run at the maximum speed by default. You can use this option to slow the test down.

factor should be a number between 1 (the fastest) and 0.01 (the slowest).

testcafe chrome my-tests --speed 0.1

If the speed is also specified for an individual action, the action's speed setting overrides the test speed.

Default value: 1

--ports <port1,port2>

Specifies custom port numbers TestCafe uses to perform testing. The number range is [0-65535].

TestCafe automatically selects ports if ports are not specified.

--hostname <name>

Specifies your computer's hostname. It is used when running tests in remote browsers.

If the hostname is not specified, TestCafe uses the operating system's hostname or the current machine's network IP address.

--proxy <host>

Specifies the proxy server used in your local network to access the Internet.

testcafe chrome my-tests/**/*.js --proxy
testcafe chrome my-tests/**/*.js --proxy

You can also specify authentication credentials with the proxy host.

testcafe chrome my-tests/**/*.js --proxy

--proxy-bypass <rules>

Specifies the resources accessed bypassing the proxy server.

When you access the Internet through a proxy server specified using the --proxy option, you may still need some local or external resources to be accessed directly. In this instance, provide their URLs to the --proxy-bypass option.

The rules parameter takes a comma-separated list (without spaces) of URLs that require direct access. You can replace parts of the URL with the * wildcard that matches any number of characters. Wildcards at the beginning and end of the rules can be omitted (* and have the same effect).

The following example uses the proxy server at with the localhost:8080 address accessed directly:

testcafe chrome my-tests/**/*.js --proxy --proxy-bypass localhost:8080

In the example below, two resources are accessed by bypassing the proxy: localhost:8080 and

testcafe chrome my-tests/**/*.js --proxy --proxy-bypass localhost:8080,

The * value means that all URLs in the subdomains are accessed directly.

testcafe chrome my-tests/**/*.js --proxy --proxy-bypass *

--ssl <options>

Provides options that allow you to establish an HTTPS connection between the client browser and the TestCafe server.

The options parameter contains options required to initialize a Node.js HTTPS server. The most commonly used SSL options are described in the TLS topic in Node.js documentation. Options are specified in a semicolon-separated string.

testcafe --ssl pfx=path/to/file.pfx;rejectUnauthorized=true;...

Provide the --ssl flag if the tested webpage uses browser features that require secure origin (Service Workers, Geolocation API, ApplePaySession, SubtleCrypto, etc). See Connect to the TestCafe Server over HTTPS for more information.


Enables mechanisms to log and diagnose errors. You should enable this option if you are going to contact TestCafe Support to report an issue.

testcafe chrome my-tests --dev


Outputs a QR-code that represents URLs used to connect the remote browsers.

testcafe remote my-tests --qr-code

--sf, --stop-on-first-fail

Stops an entire test run if any test fails. This allows you not to wait for all the tests included in the test task to finish and allows focusing on the first error.

testcafe chrome my-tests --sf


Disables checks for test and fixture directives in test files. Use this flag to run dynamically loaded tests.

Test files should have the fixture and test directives. Otherwise, an error is thrown.

However, the .js file may not contain tests when you import tests from external libraries or generate them dynamically.


export default function runTests () {
    fixture `External tests`
        .page `http:///`;

    test('My Test', async t => {
        // ...


import runTests from './external-lib';


In this instance, specify the --disable-test-syntax-validation flag to bypass test syntax checks.

testcafe safari test.js --disable-test-syntax-validation


Enables colors in the command line.


Disables colors in the command line.