FAQ

General Questions
Troubleshooting

General Questions #

I have heard that TestCafe does not use Selenium. How does it operate? #

Unlike most testing solutions, TestCafe is not built on Selenium. This allows us to implement features you cannot find in Selenium-based tools (for example, testing on mobile devices, user roles, automatic waiting, etc.).

TestCafe uses a URL-rewriting proxy which allows it to work without the WebDriver. This proxy injects the driver script that emulates user actions into the tested page.

You can read about this in How it Works.

What is the difference between TestCafe Studio and open-source TestCafe? #

TestCafe Studio is a testing IDE built on top of the open-source TestCafe engine. It simplifies the way you record tests and helps you delegate testing to a QA team that does not want to write JavaScript.

Read the following article to learn how TestCafe Studio could fit into your workflow: What's Better than TestCafe? TestCafe Studio.

The table below compares TestCafe and TestCafe Studio:

	TestCafe	TestCafe Studio
No need for WebDriver, browser plugins or other tools	✓	✓
Cross-platform and cross-browser out of the box	✓	✓
Write tests in the latest JavaScript or TypeScript	✓	✓
Clear and flexible API supports ES6 and PageModel pattern	✓	✓
Stable tests due to the Smart Assertion Query Mechanism	✓	✓
Tests run fast due to intelligent Automatic Waiting Mechanism and Concurrent Test Execution	✓	✓
Custom reporter plugins	✓	✓
Use third-party Node.js modules in test scripts	✓	✓
Integration with popular CI systems	✓	✓*
Free and open-source	✓
Visual Test Recorder		✓
Interactive Test Editor		✓
Automatic Selector Generation		✓
Run Configuration Manager		✓
IDE-like GUI		✓

* You can use open-source TestCafe to run TestCafe Studio tests in CI systems.

Has TestCafe v2015.1 been deprecated? #

TestCafe v2015.1 is no longer available for purchase or subscription renewal. We recommend that TestCafe v2015.1 users switch to TestCafe Studio to access the latest features. See this blog post for details.

Which browsers does TestCafe support? What are the exact supported versions? #

You can find a list of supported browsers in our documentation. TestCafe is tested against the two latest versions of each browser except for the browsers whose versions are specified explicitly in this list.

We do not use the most recent JavaScript features in TestCafe code, which means it should work with any browser with HTML5 support released in the last three years.

Can I use third-party modules in tests? #

You can import third-party modules to the test code and inject scripts into tested webpages.

To import a module to a test file, use the import statement.

import fs from 'fs';

fixture `fixture`
   .page('http://localhost/testcafe/');

test('test', async t => {
   const filePath = 'filepath.js';

   await t.expect(fs.existsSync(filePath)).ok();
});

If a Node.js module or a JavaScript file can be executed in the browser, you can inject it into the tested page.

fixture `My fixture`
    .page `https://example.com`
    // The fixture.clientScripts method injects jquery.js
    // into all pages visited in this fixture.
    .clientScripts('scripts/jquery.js');

test('test', async t => {
    const clientFunction = ClientFunction(() => {
        // You can use $ here
        return $('div').text();
    });

    const text = await clientFunction();
});

For more information about how to inject scripts, see Inject Scripts Into Tested Pages.

How do I work with configuration files and environment variables? #

TestCafe allows you to specify settings in a configuration file.

If you need to use custom properties in the configuration, create a separate configuration file and import it to the tests.

Vote for the following GitHub issue if you want us to support custom properties in .testcaferc.json: #3593

For example, you can create the following config.json file to pass a website's base URL to test code:

{
    "baseUrl": "http://localhost/testcafe"
}

In the test code, import it like a regular JavaScript module:

import config from './config';

fixture `Fixture`
    .page `${config.baseUrl}/test1/index.html`;

Alternatively, you can use environment variables.

How do I identify elements with dynamic IDs? #

TestCafe selectors should use element identifiers that persist between test runs. However, many JavaScript frameworks generate dynamic IDs for page elements. To identify elements whose id attribute changes, use selectors based on the element's class, content, tag name, or position.

See the Select Elements With Dynamic IDs example for details.

Can I use TestCafe to test React Native apps? #

You can only use TestCafe to test something that runs in a browser, including Progressive Web Applications and Electron apps. TestCafe cannot automate native mobile applications because they do not run in a browser.

Troubleshooting #

I have installed TestCafe but I cannot run it. What should I do? #

Check your firewall. First, make sure that your firewall does not block the ports TestCafe uses. TestCafe chooses free ports automatically by default. Use the --ports command line option or the createTestCafe API factory function to specify custom ports. After that, check that the firewall does not block these specific ports.

Check your proxy server. Another reason for this problem can be the proxy server you use to access the Internet. If your network is connected to the Web via a proxy, use the --proxy command line option or the useProxy API method to specify the proxy address.

For Linux check X11. Also note that if you run TestCafe on Linux, you need to make sure the system is running the X11 server. Without X11, you can only run tests in cloud services and headless Google Chrome. However, if you use the Xvbf server, you can run any other browser in the headless mode.

When I run a TestCafe test, I get an unexpected error. What can cause that? #

JavaScript errors. The most common reason for this is a JavaScript error on the tested page. Load this page in the browser, open the console and see if the page has any errors. In case there are errors, you can either fix them or use the --skip-js-errors flag to tell TestCafe to skip them.

Browser extensions. If this does not help, try running the problematic test in incognito mode. You can do this by adding an appropriate flag after the browser name.

testcafe "chrome -incognito" tests/test.js

testcafe "firefox –private-window" tests/test.js

If the test runs successfully, it might be browser extensions causing the issue. Try disabling them one by one and restart the test in the regular mode at each iteration. This way you can find out which extension prevents the test from running.

Third-party modules. In rare cases, third-party modules can be the cause. If you use a locally installed TestCafe, try installing it globally and running the test outside of the project to eliminate the influence of third-party modules.

I have installed TestCafe plugins but they do not work. What have I done wrong? #

Plugins should also be installed locally if you are using a locally installed TestCafe.

npm install --save-dev {pluginName}

If you are going to use a global TestCafe installation, or you wish to use the plugin in other projects as well, install it globally.

npm install -g {pluginName}

My test fails because TestCafe could not find the required webpage element. Why does this happen? #

This happens because either:

one of the selectors you used in test code does not match any DOM element, or
you used an incorrect CSS selector or a client-side function that returns no element to specify an action's target element.

To determine the cause of this issue, do the following:

Look at the error message in the test run report to learn which selector has failed.
Add the t.debug() method before this selector to stop test execution before it reaches this point.
Run the test and wait until the browser stops at the breakpoint.

Next, use the browser's development tools to ensure that elements satisfy the interaction requirements.

Also, try running the test in full screen. Use the t.maximizeWindow and t.resizeWindow actions to control the browser window size. If the test passes, it means your webpage hides the target element when the window is resized to smaller dimensions.

Finally, try updating TestCafe to the latest version to see if the problem persists.

TestCafe reports that a request has failed. What are the possible reasons? #

When TestCafe does not receive a successful response from a server, it outputs the following error:

A request to https://www.example.com has failed.
Use quarantine mode to perform additional attempts to execute this test.

You can use quarantine mode to complete the tests if this problem occurs infrequently.

However, we recommend that you determine the cause of this issue and address it.

This error can occur in the following situations:

The Web server is not responding #

Check if the Web and DNS servers are online and configured to accept requests to this URL.

Unstable or improperly configured network connection #

Check the network connection's settings.
Ensure that your network equipment works properly. If possible, establish a direct connection to the Internet/Web server.
Check the proxy server's settings or try a different proxy server.
Use VPN.
Connect to a different network.

Not enough resources in the container or CI system #

If you run TestCafe in a container or CI system, use the following steps to diagnose resource shortage:

Increase the container's resource limits.
Set the concurrency factor to 1.
Deploy the application's Web server on a separate machine.
Run tests on a local device outside a container.

If this fixes the tests, it indicates that they require additional resources. You can address this in the following ways:

Adjust the container's or environment's settings to allocate more resources.
If you use a cloud-based CI system, ask the service provider for an upgrade or consider a different CI service with better hardware or smaller loads.

According to users' feedback, the following CI systems work best with TestCafe:

'The browser can't open the page: can't establish a secure connection to the server' #

If your computer is connected to multiple networks (for instance, if it uses a VPN connection), TestCafe may incorrectly detect the host IP and not open the tested pages.

<browsername> cannot open the page because <browsername> is unable to establish a secure connection to the server.

To fix the issue, launch TestCafe with the --hostname localhost CLI option:

testcafe chrome test.js --hostname localhost