Browsers

This topic lists browsers supported by TestCafe and describes how to use various browser features.

• Browser Support
  • Officially Supported Browsers
  • Locally Installed Browsers
  • Portable Browsers
  • Browsers on Remote Devices
  • Browsers in Cloud Testing Services
  • Microsoft Edge Legacy Support
  • Nonconventional Browsers
• Test in Headless Mode
  • Automation Port
• Use Chromium Device Emulation
  • Emulate a Device
  • Emulate Screen Size
  • Use Emulation in Headless Mode
  • Use Emulation in Chrome Portable
  • Substitute a User Agent
  • Emulator Parameters
• User Profiles

Browser Support #

Officially Supported Browsers #

While TestCafe is designed to support most modern browsers, there are a limited number of officially supported browsers. TestCafe is actively tested with these browsers.

• Google Chrome: Stable, Beta, Dev and Canary
• Internet Explorer (11+)
• Microsoft Edge (legacy and Chromium-based)
• Mozilla Firefox
• Safari
• Google Chrome mobile
• Safari mobile

TestCafe supports the latest version of each browser (unless specified explicitly).

Locally Installed Browsers #

TestCafe automatically detects popular browsers installed on a local computer. You can use a short name - the browser alias - to identify browsers when you launch a test.

The following table lists browsers that can be detected automatically.

Call the testcafe command with the --list-browsers flag to view a list of all available browsers.

To run tests in a different local browser, specify the path to the browser's executable file.

To test in Microsoft Edge Chromium and Legacy on the same machine, install them side-by-side. Once installed, see the Microsoft Edge Legacy Support section below for information on how to enable testing in older versions.

For more information and examples, see the following:

• Command line: Local Browsers
• API: runner.browsers
• Configuration file: browsers

Portable Browsers #

To use a portable browser, specify the path to the browser's executable file. For more information and examples, see the following:

• Command line: Portable Browsers
• API: runner.browsers
• Configuration file: browsers

Browsers on Remote Devices #

To run tests on a remote mobile and desktop device, the device must have network access to the TestCafe server.

First, you will need to create a remote browser connection.

• Command line: specify the remote alias (see Remote Browsers)
• API: use the createBrowserConnection method
• Configuration file: browsers

After that, TestCafe generates a URL to open in the browser that you need to test (on a remote device). This URL is then exposed through the API or displayed in the console. Access this URL from the desired browser. It then connects to the TestCafe server and starts the test.

Note that when you run tests in a remote browser, you cannot take screenshots or resize the browser window.

Browsers in Cloud Testing Services #

TestCafe allows you to use browsers from cloud testing services. You can access them through browser provider plugins.

The following plugins for cloud services are currently provided by the TestCafe team.

You can search npm for community-developed plugins. Their names begin with the testcafe-browser-provider- prefix: https://www.npmjs.com/search?q=testcafe-browser-provider.

You can also create your own plugin. See Browser Provider Plugin for instructions.

Microsoft Edge Legacy Support #

Tests are run in Microsoft Edge Legacy if it is the only version of Edge installed on the machine.

If both Chromium-based and Legacy versions are available, you can change the default Edge application in System Settings to test with the Legacy version.

To test with the Legacy version of Edge, open Default apps in Windows Settings and scroll down to select Default Apps by Protocol. Set the MICROSOFT-EDGE: protocol to Legacy Edge.

Nonconventional Browsers #

To run tests in a different type of browser, use a browser provider plugin.

You can search npm for community-developed plugins. Their names begin with the testcafe-browser-provider- prefix: https://www.npmjs.com/search?q=testcafe-browser-provider.

You can also create your own plugin. See Browser Provider Plugin for instructions.

Test in Headless Mode #

TestCafe allows you to run tests in Google Chrome and Mozilla Firefox without a visible UI shell - in headless mode (Chrome Headless, Firefox Headless). Use the :headless parameter to launch a browser in headless mode.

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

runner
    .src('tests/sample-fixture.js')
    .browsers('chrome:headless')
    .run();

Specify a path to the browser executable if you use a portable version of the browser. Use the browser alias instead of the path: prefix.

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

runner
    .src('tests/sample-fixture.js')
    .browsers('firefox:path/to/firefox:headless')
    .run();

Note that Take screenshot and Resize window are fully supported in headless mode.

Automation Port #

Chrome and Firefox require a remote control port for TestCafe to attach to a browser instance. TestCafe automatically assigns a free port, but you can specify a custom port via the cdpPort argument (for Chrome) or the marionettePort argument (for Firefox).

testcafe "chrome:headless:cdpPort=9223" tests/sample-fixture.js

runner
    .src('tests/sample-fixture.js')
    .browsers('chrome:headless:cdpPort=9223')
    .run();

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

runner
    .src('tests/sample-fixture.js')
    .browsers('firefox:headless:marionettePort=9223')
    .run();

Use Chromium Device Emulation #

You can run tests with Chromium's built-in device emulator in Google Chrome, Chromium and Chromium-based Microsoft Edge. Use the emulation browser parameter.

Emulate a Device #

Specify the target device with the device parameter.

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

runner
    .src('tests/sample-fixture.js')
    .browsers('chrome:emulation:device=iphone X')
    .run();

Emulate Screen Size #

You can specify parameters like width, height, or orientation to configure the device emulator.

testcafe "chrome:emulation:width=100;height=200;mobile=true;orientation=vertical;touch=true" tests/sample-fixture.js

runner
    .src('tests/sample-fixture.js')
    .browsers('chrome:emulation:width=100;height=200;mobile=true;orientation=vertical;touch=true')
    .run();

Use Emulation in Headless Mode #

You can combine device emulation and headless mode.

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

runner
    .src('tests/sample-fixture.js')
    .browsers('chrome:headless:emulation:device=iphone X;cdpPort=9223')
    .run();

Use Emulation in Chrome Portable #

To enable device emulation in Google Chrome Portable, use the browser alias. The path: prefix does not work in this case.

testcafe "chrome:d:\chrome_portable\chrome.exe:emulation:device=iphone X" tests/test.js

Substitute a User Agent #

Use the userAgent parameter to substitute a user agent string.

TestCafe relies on a user agent string to emulate browser behavior. Tests are not guaranteed to run correctly if you specify a user agent that is invalid or not supported by TestCafe.

JavaScript API #

When you launch TestCafe with JavaScript API, provide the user agent string in the runner.browsers method parameter. Escape semicolons from the TestCafe argument parser with a double backslash - as shown below:

runner
    .src('tests/sample-fixture.js')
    .browsers('chrome:emulation:userAgent=Mozilla/5.0 (Windows NT 10.0\\; Win64\\; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36')
    .run();

Command Line Interface #

You need to escape special characters in the user agent string when you specify it in the command line. These characters include the following:

• \ (backslash)
• ' (single quote)
• " (double quote)
• , (comma)
• ; (semicolon)
• : (colon)

The way to escape special characters depends on the shell you use. You also need to escape semicolons from the TestCafe argument parser with an additional backslash.

The following examples show how to escape user agent screens in bash and PowerShell.

bash

In bash, enter a dollar sign before the argument to allow single quotes. Escape special characters with a backslash and use a double backslash for semicolons - to escape them from the TestCafe argument parser:

testcafe $'chrome:emulation:userAgent=\'Mozilla/5.0 (Windows NT 10.0\\; Win64\\; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36\'' test.js

PowerShell

In PowerShell, escape special characters with a single quote and use a backslash for semicolons - to escape them from the TestCafe argument parser:

testcafe 'chrome:emulation:userAgent=''Mozilla/5.0 (Windows NT 10.0\; Win64\; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36''' test.js

Emulator Parameters #

Use the following parameters to configure the Chrome device emulator. Specify them after the emulation parameter as in the examples above.

User Profiles #

By default, TestCafe launches Chromium, Google Chrome, Microsoft Edge (Chromium-based, version 79 and above) and Mozilla Firefox with a clean profile (i.e. without extensions, bookmarks and other profile settings) - to minimize profile parameter influence on test runs.

However, if you need to start a browser with the current user profile, you can specify the :userProfile flag after the browser alias.

testcafe firefox:userProfile tests/test.js

runner
    .src('tests/fixture1.js')
    .browsers('firefox:userProfile')
    .run();

When you pass the :userProfile flag to a portable browser, also use the browser alias. The path: prefix does not work in this case.

testcafe chrome:d:\chrome_portable\chrome.exe:userProfile tests/test.js

If you use the :userProfile flag, set the cdpPort property to 9222 to record videos in Chrome and Chromium-based browsers.

testcafe chrome:userProfile:emulation:cdpPort=9222 test.js --video artifacts/videos

It is not recommended that you combine the :userProfile flag with either headless or emulation mode, because this can lead to unstable behavior.