General Info

Can I use TestCafe for free?

Yes! The TestCafe framework includes everything you need to write and run end-to-end tests. Anybody can download and install TestCafe from the NPM registry for free. The framework’s source code is available on GitHub under the open-source MIT license.

What is the difference between TestCafe and TestCafe Studio?

TestCafe and TestCafe Studio can run the exact same tests. There’s no difference when it comes to testing capabilities, browser support, OS support, or test suite size.

The main difference between the two products is the workflow.

  • TestCafe is a command-line application that runs test scripts. It requires a basic understanding of JavaScript and the Node.JS ecosystem. TestCafe is free and open-source.
  • TestCafe Studio is a desktop application that allows you to interactively record and edit tests. You can use it to create test scripts or codeless tests. Many TestCafe Studio capabilities do not require any programming knowledge. You can buy a TestCafe Studio license from DevExpress.

What operating systems does TestCafe support?

TestCafe and TestCafe Studio work on macOS, Linux, and Windows. See the following guides: Install TestCafe and Install TestCafe Studio.

I want to run tests in different browsers. Which browsers does TestCafe support?

TestCafe can run tests in any modern browser. However, the TestCafe team only guarantees compatibility with the two latest versions of every popular browser.

Does the technology stack of my web application affect TestCafe tests?

Your web application can use any language, framework, or platform — Ruby, Node.js, Rust, C#, PHP, Blazor, or something else. TestCafe runs tests in the browser, and does not interact with your application’s back-end. If your client-side code conforms to modern web standards, TestCafe can test it.

What programming language do TestCafe tests use?

You can write TestCafe test scripts in the following programming languages:

  • JavaScript
  • TypeScript
  • CoffeeScript

Community plugins offer support for Gherkin and Cucumber syntax.

TestCafe Studio can record TestCafe tests in the following formats:

  • JavaScript
  • TypeScript
  • Codeless tests (*.testcafe). Codeless tests do not support the full range of TestCafe capabilities.

TestCafe can run legacy TestCafe v2015.1 tests (*.test.js). Legacy tests do not support the full range of TestCafe capabilities.

Can I test mobile applications with TestCafe?

TestCafe can test any application that runs in a browser. It can test mobile websites, Progressive Web Applications and Electron apps.

TestCafe offers the following mobile testing capabilities:

  • Run TestCafe tests on remote devices, such as smartphones and tablets.
  • Run TestCafe tests on cloud browser farms, such as BrowserStack and SauceLabs.
  • When you run TestCafe tests in Chromium-based browsers, you can enable the device emulation mode.

TestCafe cannot test native mobile applications (such as ReactNative apps) or WebView-based mobile apps (such as Apache Cordova apps).

Can I use TestCafe for performance testing?

We do not recommend the use of TestCafe for performance or load testing.

TestCafe is a functional testing tool. TestCafe cannot measure performance metrics, such as time to first byte (TTFB) or requests per second.

To run tests, TestCafe injects automation scripts and custom styles into the browser. These extra resources create an overhead that affects application performance. That’s why performance or load tests do not yield conclusive results.

Can I use TestCafe for API testing?

Yes! TestCafe includes everything you need to create API tests. Use the server-side t.request method to issue HTTP requests. Use assertions to validate server responses.

For more information, read the API Testing guide.

Can tests emulate keyboard shortcuts or interact with browser dialogs?

The purpose of TestCafe is to interact with web applications. To accomodate popular testing scenarios, the framework can interact with common native dialogs. However, TestCafe is still subject to the following limitations:

  • TestCafe cannot emulate system events, such as key press combinations or GPS signals.
  • TestCafe cannot access system resources, such as the clipboard.
  • TestCafe cannot interact with browser windows, such as the Print dialog, or HTML5 input prompts.

Most of the time, you can work around these limitations. Let’s consider a couple of examples.

Example 1: Location request dialogs

Imagine that your application needs to detect the user’s location. In a real life scenario, the application triggers a dialog box that requests location data. This dialog is a part of the browser, and TestCafe cannot interact with the dialog directly. To work around this limitation, create a mock function that feeds dummy data to your application. This solution significantly simplifies the testing process. See the Mock Geolocation API example.

Example 2: Native HTML5 inputs

The UI of native HTML5 inputs (date, time, color, etc.) is technically a part of the browser, not a part of your page. Therefore, you cannot use regular TestCafe actions to interact with these dialogs. However, for testing purposes it makes little difference whether you interact with the dialog or enter the value as text. Use the typeText action to enter a value instead.

Exceptions

Can I run tests in multiple browsers at once?

  • TestCafe can launch multiple browsers simultaneously. Specify multiple browsers at launch and quickly uncover browser-specific errors.
  • Concurrency mode allows you to launch multiple instances of each browser to speed up the testing process.

Does TestCafe impose any limitations on Cross-Origin testing?

No.

Can TestCafe access elements in an “iframe”?

Yes. TestCafe can access elements inside iframes, even if these iframes are nested. To access an iframe, change the test execution context with the t.switchToIframe method.

Can TestCafe access elements in a different browser window?

Yes. TestCafe can interact with elements across multiple browser windows. This is necessary to fill OAuth forms and interact with chat windows. Use window management methods to switch between different browser windows.

Can TestCafe test applications that use WebSockets?

Yes.

Can TestCafe feed mock data to a web application?

Yes. You can emulate HTTP responses to feed sample data to your app, troubleshoot connectivity errors, and test your application during infrastructure downtime.

Can TestCafe inject third-party client-side libraries into a web application?

Yes. You can execute custom client-side code to parse the web page, examine its state, or even add extra dependencies.

Can TestCafe access resources that require authentication?

Of course. You can authenticate users with regular page actions, and use role scripts to switch between different user accounts on the fly.

Can TestCafe handle two-factor authentication?

Two-factor authentication usually falls outside the scope of functional testing tools. TestCafe is no exception. We do not offer any built-in tools that handle two-factor authentication.

It is important to consider the purpose of your test. Do you want to test the two-factor authentication process itself? If so, test this capability with non-functional methods.

If you need to access resources that require two-factor authentication, consider the following workaround. Deploy your application in a separate testing environment. To prevent possible security risks, make sure that the testing environment does not have access to your production data. Then, turn off two-factor authentication for that particular deployment. That’s it — now your website is ready for functional testing.

Can I integrate TestCafe tests into my CI workflow?

Yes. Most modern CI/CD platforms can launch TestCafe tests. There are even plugins that simplify this process for select CI providers. Refer to our Continuous Integration guides for more information.

How does TestCafe work if it doesn’t use Selenium/WebDriver?

Unlike traditional testing solutions, TestCafe does not use Selenium or WebDriver. Instead, TestCafe includes a hybrid automation engine that can execute both system-level and in-browser code. A proxy that injects client-side automation scripts into web pages connects the two parts of the engine.

The hybrid engine allows TestCafe to implement capabilities that Selenium lacks, such as user roles and automatic waiting algorithms. Moreover, TestCafe has native access to the DOM and can safely execute custom client-side scripts.

To manage windows and perform other browser actions, TestCafe makes use of CDP and Marionette.

Our design choices have a minor downside. Since TestCafe injects automation scripts into the browser, the events that TestCafe triggers are not fully native. The value of the isTrusted property of these events is false. To prevent this behavior, we plan to fully integrate CDP and Marionette into the framework in the near future.

Refer to the Why TestCafe article for more information about the framework’s architecture.

Do I need to change my application’s code to use TestCafe?

No, you don’t need to change your application code to run TestCafe tests.

We do, however, encourage the use of custom HTML attributes for key page elements. Custom HTML attributes increase test stability and simplify Element Selector queries.

What programming languages and techniques do I need to know in order to master TestCafe?

Basic JavaScript knowledge is enough to get started with TestCafe and follow our code examples.

If you want to further improve your end-to-end tests, learn more about the following subjects:

  • CSS selectors
  • HTML5 markup
  • Modern client-side JavaScript
  • Promises and async/await syntax (for a better understanding of the TestCafe API and its asynchronous code)
  • Node.js (TestCafe tests are Node.js scripts. You can integrate third-party Node modules into your tests.)
  • TypeScript (to leverage the benefits of a type safe language).

How do I know if TestCafe is right for me? How do I convince others?

  1. Think about your current situation. What user scenarios do you need to test? Can TestCafe accommodate these scenarios?
  2. Think about your plans. What do you plan to add to your product? Will TestCafe be able to accommodate your growing testing needs?

TestCafe is a good fit if the framework satisfies your current needs, and can satisfy the needs you expect to soon develop. Try TestCafe and see how it feels. Deliberately write tests that are likely to cause trouble, and identify any potential deal-breakers.

Once you gain enough hands-on experience, you will have a good understanding of TestCafe and its capabilities. If you know people with similar needs, share this information and convince them to try TestCafe for themselves.

I want to avoid common mistakes in test design. Where can I learn about TestCafe best practices?

The Best Practices article lists guidelines that we use to create stable and reliable tests. You can find additional code examples throughout our documentation and in the dedicated sample test repository.

Does TestCafe collect or share my test data?

  • The TestCafe framework doesn’t collect or share any data related to your tests.
  • TestCafe Studio may collect and upload anonymous data if you opt in during installation. You can change this setting at any time.

How do I subscribe to TestCafe news or learn about recent updates?

On average, the TestCafe team publishes framework updates every month. We strictly adhere to the semver policy.

  • View the Release notes page for more information on most TestCafe updates.
  • View the Changelog on GitHub for more information on the contents of minor TestCafe patches.
  • Watch the TestCafe repository on GitHub to keep track of the framework’s development.
  • Visit our Blog for in-depth articles about the framework’s capabilities. Subscribe to the blog’s RSS feed to receive notifications every time TestCafe publishes a new article.
  • Read the TestCafe Studio Version History article for more information on the content of TestCafe Studio updates.
  • Follow us on Twitter and Facebook.

How do I ask for technical support?

We offer dedicated technical support to TestCafe Studio license holders. Other users can reach out to the TestCafe community on GitHub or StackOverflow.

How to create a Minimal Working Example when you submit an issue

Modern software breaks in increasingly complex ways. Often, software issues are hard to reproduce — let alone investigate. TestCafe is no different.

That’s why it’s important to include a Minimal Working Example (MWE) with your TestCafe bug report. A good MWE ensures the issue is easy to reproduce and troubleshoot.

A Minimal Working Example should:

  • Be simple and easy to follow. Convoluted scenarios are hard to reproduce.
  • Not contain code that does not help reproduce the issue. Remove actions that do not affect the outcome.
  • Include a complete set of relevant data: the URL of the test page, the list of launch options, and the steps you follow to launch the tests.

Good Practices

  • The test page URL should point to a public web page.

    Note

    If the resources in your example require a password, or another form of authentication, you need to explicitly allow the DevExpress staff to remotely access these resources for the purposes of research, testing, and debugging. Send a written permission to support@devexpress.com.

    import { Selector } from 'testcafe';

fixture `Fixture`
  .page('http://example.com');

test('test', async t => {
  await t
    .click('body')
    .expect(Selector('h1').text).eql('Example Domain');
});

  • The repository should contain all the information and files necessary to reproduce the issue. Any user should be able to follow your instructions.

    I uploaded the demo to a [github repository](link). Follow the steps below to reproduce the issue:
- Clone/download the repository.
- Run the following commands:
    yarn install
    yarn webpack --mode development 
- Start the web server: 
    yarn serve dist 
- Run the test:
    yarn testcafe chrome tests/**/*.test.js

Practices to Avoid

Examples that contain incomplete information slow down debugging. If your bug report doesn’t include all the necessary details, the project’s maintainers spend more time asking questions, and less time dealing with the issue at hand.

Common mistakes people make when they compile bug reports:

  • The bug report does not include the test page URL. The example below references the url variable, but does not define it in code.

    fixture `Add to card`
  .page(url);

test('test', async t => {
    await t.click('body');
});

  • The example repository does not include the files referenced in the test code. The example below imports the getCookie helper and ExamplePage page model. If the repository lacks these files, the example cannot be run.

    import { getCookie } from '/helpers';
import { ExamplePage } './page-model';

fixture `Fixture`
    .page('http://example.com');

test('test', async t => {
  const cookies = await getCookie();

    await t.click(ExamplePage.login);
});

  • The bug report only contains English language instructions, and no test code.

    1. Click the first menu item
2. Open a modal popup to specify product count
3. Click the 'Buy' button

  • The example requires that you install additional software. Mock third-party services and applications to simplify the example, and make it easier to reproduce.

Related Questions

  • I cannot legally share the example source code / The application that I test displays sensitive information.

    Attempt to reproduce the issue without proprietary code. Mock or remove all private data.

  • My application is password-protected, and I cannot share the credentials on GitHub for security reasons.

    Share confidential information with TestCafe support staff at support@devexpress.com.

  • The issue is not page-dependent. Which page should I use for the test example?

    Create a test for the TestCafe example page.

  • I notified a member of the TestCafe team of an issue. Why haven’t I received a response?

    We do not recommend you contact members of the TestCafe team directly. If the recipient is absent or no longer part of the TestCafe team, the information you share may never come to our attention. Create a GitHub issue with your example instead.

  • My tests only fail when I run them on Docker.

    Containers and virtual machines have limited resources. TestCafe tests may fail if TestCafe, the browser, or the application does not have enough resources to run smoothly. Try to increase the amount of resources allocated to the Docker image or increase the timeout values for Selectors and assertions. If you are sure that issue is with Docker, send us the complete Docker image and its sources.

  • My tests run well on the local machine, but fail as unstable on CI.

    It is difficult to determine why your tests fail on CI because your tests’ performance depends on your CI settings (environment settings, memory configuration, and so on). To begin troubleshooting, increase timeout values and make sure your web server correctly processes requests. If you’re stuck, send the copy of the complete TestCafe debug log to support@devexpress.com.

    set DEBUG=testcafe:*,hammerhead:*
testcafe chrome index.js 2> testcafe.log

Working with TestCafe

Can my tests reference third-party libraries?

Yes — both on the server side and the client side.

Server side

TestCafe tests are Node.js scripts that can incorporate other Node libraries. Add an import statement to import a module.

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

Client side

TestCafe can inject front-end JavaScript libraries into your web application. See Inject Client Scripts for more information.

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

Can I store TestCafe settings in a configuration file?

You can store your TestCafe settings in a dedicated configuration file. TestCafe supports two configuration file formats — JSON and JavaScript.

On startup, TestCafe looks for a configuration file (.testcaferc.js or .testcaferc.json) in the current working directory. You can specify a non-standard configuration file path with the --config-file command line option.

Read the configuration file guide for more information.

How do I access environment variables?

The TestCafe configuration file can reference environment variables. Read the Access Environment Variables in Tests recipe for more information.

How do I reference elements with dynamic IDs?

Many JavaScript frameworks generate dynamic IDs for page elements. Selector queries that reference these dynamic IDs are likely to fail.

To identify elements with a dynamic id attribute, create Selectors based on the element’s class, content, tag name, or position.

See the Select Elements With Dynamic IDs example for details.

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

Check your firewall settings. Make sure that your firewall does not block the framework’s network activity. TestCafe communicates with the network over two different ports in the [0 - 65535] range. The framework selects two unoccupied network ports on launch. But you can specify port numbers yourself.

Create a firewall rule that keeps two ports in the [0 - 65535] range open. Specify these ports with the --ports command line option or the createTestCafe Test Runner function when you launch the framework.

Specify proxy server settings. If the machine that runs tests needs a proxy to access the internet, specify proxy settings when you launch TestCafe. Use the --proxy command line option or the useProxy API method.

Check X11 (Linux users only). TestCafe relies on X11 to launch most Linux browsers. If you use the Xvbf window server, you can only run browsers in headless mode. If your setup doesn’t include X11 or Xvbf, you can only run tests on cloud farms and in headless Google Chrome.

My TestCafe test yields an unexpected error. What can cause that?

JavaScript errors. TestCafe tests fail when a page yields a JavaScript error. Check your browser’s console for error messages. Fix the errors or request TestCafe to ignore JavaScript errors during test runs.

Browser extensions. Browser extensions may interfere with test execution. That’s why TestCafe launches browsers with an empty user profile. If you enabled the userProfile option earlier, disable it.

Third-party modules. In rare cases, third-party modules can interfere with test execution. If your current TestCafe installation is local, install the framework globally and launch the test from a directory that doesn’t contain third-party Node modules.

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

Local TestCafe installations only detect local TestCafe plugins. If your current TestCafe installation is local, install the plugin locally:

npm install --save-dev {pluginName}

If your current TestCafe installation is global, install the plugin globally:

npm install -g {pluginName}

My tests fail because TestCafe cannot locate a page element. Why does this happen?

TestCafe uses Selector queries to locate page elements. Follow the steps below to diagnose Selector failure:

  1. View the test report. Locate the Selector query that failed.
  2. Insert the t.debug() action before the failing Selector declaration. The t.debug method pauses the test for troubleshooting purposes.
  3. Run the test and wait until TestCafe stops test execution at the breakpoint.
  4. Inspect the action target with the browser’s development tools to ensure that it meets the interaction requirements.

The following tips and tricks may also help:

  • Some web applications hide page elements when the window’s dimensions are too small. Run the test in full screen mode to resolve the issue. Adjust window size with the t.maximizeWindow and t.resizeWindow methods.
  • Update TestCafe to the latest version. You may have encountered a bug that has already been fixed.

My tests fail because TestCafe cannot resolve a network request. What are the possible reasons?

If the TestCafe proxy does not receive the webpage within two minutes, TestCafe throws the following exception:

Failed to load the page at https://www.example.com.
Increase the value of the "pageRequestTimeout" variable, 
enable the "retryTestPages" option, or use quarantine mode 
to perform additional attempts to execute this test.

If you believe that this error is unwarranted, enable quarantine mode. The quarantine mode option forces TestCafe to repeat tests that fail until they yield conclusive results.

If the error persists, continue your investigation. Here are some of the reasons that this error may occur:

The Web server is not responding

Confirm the successful resolution of the website’s domain name. Check if the web application is online and able to receive incoming requests.

If the server is unstable, and you cannot fix it, enable one of the following options to retry failed page requests:

Unstable or improperly configured network connection

Your network configuration may cause issues with server connection.

  • Check your network settings.
  • Check the stability of your network equipment.
  • Check your proxy settings, or try a different proxy server.
  • Use a VPN.
  • Connect to a different network.

Lack of container or CI resources

Your browser may be unable to access the page because it lacks necessary system ressources.

If you run TestCafe in a container or on a CI server, use the following steps to diagnose the 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 one of these solutions fixes your tests, assign more resources to the TestCafe framework.

  • 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 provider with better hardware and lower loads.

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

TestCafe cannot open the page because the browser cannot establish a secure connection. What should I do?

If your computer belongs to multiple networks (for example, if you use a VPN), TestCafe may incorrectly detect the host IP. As a result, the browser can display the following error message:

<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