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 are not guaranteed to execute correctly.

Browser List

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

You are free to specify different types of browsers in one command call.

Local Browsers

You can specify locally installed browsers by using browser aliases or paths (with the path: prefix). The list of all the available browsers can be obtained by calling the --list-browsers command.

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

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

To run tests against all installed browsers, use the all alias.

testcafe all tests/sample-fixture.js

Portable Browsers

You can specify portable browsers by 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, surround it with backticks and additionally surround the whole parameter including the keyword in quotation marks.

On Windows cmd.exe, the default command prompt, use double quotation marks.

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

On Unix shells like bash, zsh, csh (on macOS, Linux, Windows Subsystem for Linux) and Windows PowerShell, prefer single quotation marks.

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

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

For details, see Testing in Headless Mode.

Using Chrome Device Emulation

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

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

To learn more, see Using Chrome Device Emulation

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 will provide URLs to open in required browsers on your remote device.

If you run tests concurrently, specify the total number of instances of all browsers 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 by using the device on which you are going to test your application. As a result, the browsers will be connected to TestCafe and tests will start.

Browsers Accessed Through Browser Provider Plugins

To run tests in cloud browsers or other browsers accessed through a browser provider plugin, specify a browser alias that consists of the {browser-provider-name} prefix and the name of a browser itself (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 right after browser alias. Surround the browser call and its arguments with quotation marks.

On Windows cmd.exe, the default command prompt, use double quotation marks.

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

On Unix shells like bash, zsh, csh (on macOS, Linux, Windows Subsystem for Linux) and Windows PowerShell, prefer 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 surrounded with 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

You can specify arguments for local browsers only.

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 located 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 will run tests from the test or tests directories.


-h, --help

Displays usage information for commands.

testcafe --help

-v, --version

Displays the TestCafe version.

testcafe --version

-b, --list-browsers

Lists aliases of the local browsers available on your computer.

testcafe --list-browsers

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

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

The following command runs tests in all available browsers and generates a report in the 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 will be 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 screenshot capturing and specifies the directory path to save screenshots to.

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

-S, --screenshots-on-fails

Takes a screenshot whenever a test fails. Screenshots are saved to the directory specified by using 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

-q, --quarantine-mode

Enables the quarantine mode for tests that fail. In this mode, a failed test is executed several more times. The test result depends on the outcome (passed or failed) that occurs most often. That is, if the test fails on most attempts, the result is failed. And vice versa, if the test is executed successfully on most of the attempts, the result is passed.

If the test result differs between test runs, the test is marked as unstable.

testcafe all tests/sample-fixture.js -q

-e, --skip-js-errors

Prevents tests from failure when a JavaScript error occurs on a tested web page. By default, in case of such errors, TestCafe stops test execution and posts an error message to a report. If you want TestCafe to ignore JavaScript errors, specify this argument.

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

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

Specifies that tests should run concurrently.

TestCafe will open n instances of the same browser thus creating a pool of browser instances. Tests will run concurrently against this pool, i.e. each test will run in the first free instance.

To learn more about concurrent test execution, see Concurrent Test Execution.

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

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

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

TestCafe will run 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 will run tests whose names match the specified pattern.

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

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

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

TestCafe will run a fixture with the specified name.

testcafe ie my-tests -f sample-fixture

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

TestCafe will run fixtures whose names match the specified pattern.

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

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

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

Executes the specified shell command before running tests. Use it to launch or deploy the application you are going to test.

After testing is finished, this application will be automatically terminated.

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

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

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

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

In the footer, a status bar is displayed in which you can resume test execution or step to the next action or assertion.

Debugging status bar

If the test you run in the debugging mode contains a test hook, it will be 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.


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

If this option is enabled, TestCafe pauses the test at the moment it fails. This allows you to explore 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 amount of 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 amount of time, in milliseconds, within which selectors make attempts 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 amount of 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.

Default value: 3000

testcafe ie my-tests --assertion-timeout 10000

--page-load-timeout <ms>

Specifies the amount of 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

--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

--ports <port1,port2>

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

If ports are not specified, TestCafe selects ports.

--hostname <name>

Specifies the hostname of your computer. It is used when running tests in remote browsers.

If the hostname is not specified, TestCafe will use the operating system hostname or network IP address of the current machine.

--speed <factor>

Specifies the speed of test execution.

By default, tests run at the maximum speed. However, if you need to watch a test running to understand what happens in it, this speed may seem too fast. In this instance, 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 speed is also specified for an individual action, the action speed setting overrides test speed.

Default value: 1


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

testcafe remote my-tests --qr-code


Enables colors on the command line.


Disables colors on the command line.