Mobile Devices, Cloud Browsers and Emulation

TestCafe makes it easy to maintain your website’s compatibility with a wide array of devices.

• You can run TestCafe tests on remote devices such as smartphones and tablets.
• You can run TestCafe tests on popular cloud testing services.
• You can simulate mobile devices in Chromium-based browsers.

Remote and Mobile Devices

You can run TestCafe tests on remote devices, including smartphones. TestCafe officially supports the mobile versions of Safari and Google Chrome.

Quick guide

1. Ensure that your remote device is on the same network as the computer that runs TestCafe.
2. If you use the CLI, add the remote browser alias to your list of browsers. If you use the Test Runner API, follow the recipe below to set up a remote connection.
3. Launch TestCafe with this configuration. TestCafe will output a URL for the remote device.
4. Open the URL in a compatible remote browser (such as Safari or Google Chrome). TestCafe will execute the test in that browser.
5. Test reports are sent to the shell that you used to launch TestCafe.

Test Runner Recipe

The Test Runner API includes dedicated methods that manage remote browser connections.

1. The createBrowserConnection method initiates remote connections. Execute this method asynchronously, and save the return value to a variable.
2. Obtain the test URL from the variable’s url property.
3. Await the ready connection status.
4. Pass the connection variable to the browsers method, and run the test as usual.

const { once }         = require('events');
const createTestCafe   = require('testcafe');
const testcafe         = await createTestCafe('localhost', 1337, 1338);
const runner           = await testcafe.createRunner();
const remoteConnection = await testcafe.createBrowserConnection();

// Output the URL to stdout.
console.log(remoteConnection.url);

// Wait for the browser to connect.
await once(remoteConnection, 'ready');

const failedCount = await runner
    .src('test.js')
    .browsers(remoteConnection)
    .run();

console.log(failedCount);
await testcafe.close();

Cloud Testing Services

Use browser provider plugins to run tests in cloud browsers.

Service	Plugin
Sauce Labs	testcafe-browser-provider-saucelabs
BrowserStack	testcafe-browser-provider-browserstack
LambdaTest	testcafe-browser-provider-lambdatest

Look for more TestCafe browser providers on npm or create your own browser provider plugin.

Simulate Devices with Chromium

Chromium-based browsers (Google Chrome, Chromium and Microsoft Edge) can run in device mode. If you enable device mode, the browser changes its viewport size and behavior to emulate the experience you’d have on a different device. You can select a device from the predefined list, or configure a custom device.

Chromium device mode is a lower-cost alternative to running tests on real hardware, or paying for a cloud service subscription.

The following sections explain how you can run TestCafe tests in device mode.

Device Mode Guide

Change the browser alias to enable Chromium emulation.

1. Enclose the browser alias in quotation marks: "chrome".
2. Add the “emulation” keyword: "chrome:emulation".
3. Add the “device” keyword. It indicates that we want to select one of the existing device emulation presets: "chrome:emulation:device".
4. Follow that up with the name of the device: "chrome:d:\chrome_portable\chrome.exe:emulation:device=iphone X"
5. To launch a custom browser, replace the path: prefix with that browser’s alias: "chrome:d:\chrome_portable\chrome.exe:emulation:device=iphone X".

CLI

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

Runner

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

Simulate A Custom Device

If none of the device emulation presets suit your needs, you can emulate a device with a custom screen resolution. This is different from the t.resizeWindow action.

Specify a screen resolution in pixels with the width and height options. Specify whether you want to simulate a desktop or a mobile device with the mobile boolean option. See the options section for the complete list of emulation mode options.

Custom Device Guide

1. Enclose the browser alias in quotation marks: "chrome".
2. Add the “emulation” keyword: "chrome:emulation".
3. Customize your emulation settings with options. Separate different options with the semicolon: "chrome:emulation:width=100;height=200;mobile=true;orientation=vertical;touch=true"
4. To launch a custom browser, replace the path: prefix with that browser’s alias: "chrome:d:\chrome_portable\chrome.exe:emulation:width=100;height=200;mobile=true;orientation=vertical;touch=true".

CLI

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

Runner

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

Headless Mode

To run Chromium in both emulation mode and headless mode, add the the :headless keyword to the browser alias, and set the cdpPort option to 9223.

CLI

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

Runner

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

User Profile

TestCafe launches browsers with an empty user profile — see Browsers. If you want to enable the :userProfile option in emulation mode, set cdpPort to 9222.

CLI

testcafe chrome:userProfile:emulation:cdpPort=9222 test.js

Runner

runner
    .src('tests/sample-fixture.js')
    .browsers('chrome:userProfile:emulation:cdpPort=9222')
    .run();

Customize the User Agent String

The user agent string includes information about the browser, the operating system, and the vendor. TestCafe reads the user agent string to make adjustments necessary for smooth test execution.

You can set a custom user agent string with the userAgent emulation option. If you specify an invalid user agent string, or mock a user string of an incompatible browser, your tests may not run correctly.

If you select a device preset, the browser automatically sets the correct user string for that device. If you neither select a device nor specify a custom user agent string, the browser keeps its regular user agent string in emulation mode.

Special characters in user agent strings

Special characters in the user agent string can lead to test execution errors.

Make sure to escape the following characters:

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

CLI

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:

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

Escape special characters with a single quote, and use a backslash for semicolons:

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

Runner

Escape semicolons with a double backslash:

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();

Emulator Options

Parameter	Type	Description	Default
device	String	Device name (see the list of options).	None
width	Number	Screen width in pixels.	The width of the device or the default browser width.
height	Number	Screen height in pixels.	The height of the device or the default browser height.
scaleFactor	Number	Device scale factor.	The scale factor of the device or your testing environment’s scale factor.
mobile	Boolean	Emulates a mobile device. Changes the viewport meta tag, the behavior of overlay scroll bars, font size, etc.	true if you pick a mobile device.
orientation	vertical / horizontal	The device orientation.	vertical
userAgent	String	The user agent string.	The user agent string of the device or your browser.
touch	Boolean	Enables touch event emulation. Requires a touch-capable target device, or a compatible userAgent.	true if the device or your computer has a touch screen.
cdpPort	Number	A Chrome Debugging Protocol port (0-65535). Specify port 9222 if you use the :userProfile option or the --user-data-dir flag.	TestCafe automatically assigns a free port.