https://devexpress.github.io/testcafe

Automated browser testing for the modern web development stack.

TestCafe is a pure node.js solution for testing web apps. It takes care of all the stages: starting browsers, running tests, gathering test results and generating reports. TestCafe doesn’t need browser plugins - it works in all popular modern browsers out-of-the-box.

• Features
• Getting Started
• Documentation
• Contributing
• Stay in Touch
• License
• Author

Everything is included in a single module installed with one command.

npm install -g testcafe

No native parts to compile, no browsers plugins to install.

TestCafe automatically starts browsers, runs tests and gathers results. You only type a single command to begin testing.

testcafe chrome tests/

When testing is finished, TestCafe aggregates test results from different browsers and outputs them into one comprehensive report.

You can write TestCafe tests in ES2016 using the latest JavaScript features like async/await.

Test API consists of over two dozen methods that can emulate all actions one could possibly do with a webpage. Chained syntax allows for code that is easy to write and read.

import { expect } from 'chai';

fixture `Example page`
    .page('https://devexpress.github.io/testcafe/example');

test('Emulate user actions and perform a verification', async t => {
    await t
        .click('#send-button')
        .typeText('#input', 'Peter Parker')
        .wait(1000);

    expect(await t.eval(() => getSomethingOnTheClient())).to.be.true;
});

Additionally, TestCafe automatically generates source maps for easy debugging. To debug your test code, start a debugging session in an IDE that supports source maps.

TestCafe allows you to access webpage elements using standard CSS selectors or custom selectors that run client JavaScript code. You can call a custom selector as a regular function within your test. It will execute your code on the client and pass the returned value back to the test. This allows you to determine the state of each element on the tested page or select a proper element to perform an action on.

import { Selector } from 'testcafe';

const getElementById = Selector(id => document.querySelector(`#${id}`));

fixture `Example page`
    .page('https://devexpress.github.io/testcafe/example');

test('Type the developer name, obtain the header text and check it', async t => {
    await t
        .typeText('#developer-name', 'John Smith')
        .click('#submit-button');

    const articleHeader = await getElementById('article-header');
    const headerText = articleHeader.innerText;

    expect(headerText).to.equal('Thank you, John!');
});

Write tests without boilerplate code.

• TestCafe automatically waits for page loads and XHRs to complete, as well as for DOM elements to become visible. You do not need to write custom code for that.
• Test runs are isolated, which means that they do not share cookies, local or session storages. There is nothing to clean up between test runs.

TestCafe automatically generates full-detailed reports that provide a test run summary and comprehensive information about errors. Automatic page screenshots, fancy call sites and call stacks free of TestCafe internals allow you to easily detect error causes.

Use one of built-in reporters to output test results or create your own one to produce custom reports.

TestCafe is easy to set up on popular Continuous Integration platforms as it allows you to test against various browsers: local, remote or cloud (e.g., Sauce Labs). You can also create a custom browser provider to add support for a browser or a cloud platform of your choice.

Ensure that Node.js and npm are installed on your computer, then run a single command:

npm install -g testcafe

For more information, see Installing TestCafe.

To create a test, create a new .js file anywhere on your computer. This file must have a special structure: tests must be organized into fixtures. Thus, begin by declaring a fixture using the fixture function.

fixture `Getting Started`

In this tutorial, you will create a test for the https://devexpress.github.io/testcafe/example sample page. Specify this page as a start page for the fixture by using the page function.

fixture `Getting Started`
    .page('https://devexpress.github.io/testcafe/example');

Then, create the test function where you will place test code.

fixture `Getting Started`
    .page('https://devexpress.github.io/testcafe/example');

test('My first test', async t => {
    // Test code
});

You can simply run the test from a command shell by calling a single command where you specify the target browser and file path.

testcafe chrome test1.js

TestCafe will automatically open the chosen browser and start test execution within it.

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

For more information on how to configure the test run, see Command Line Interface.

While the test is running, TestCafe is gathering information about the test run and outputing the report right into a command shell.

For more information, see Reporters.

Every test should be capable of interacting with page content. To perform user actions, TestCafe provides a number of actions: click, hover, typeText, setFilesToUpload, etc. They can be called in a chain.

The following fixture contains a simple test that types a developer name into a text editor and then clicks the Submit button.

fixture `Getting Started`
    .page('https://devexpress.github.io/testcafe/example');

test('My first test', async t => {
    await t
        .typeText('#developer-name', 'John Smith')
        .click('#submit-button');
});

All test actions are implemented as async functions of the test controller object t. This object is used to access test run API. To wait for actions to complete, use the await keyword when calling these actions or action chains.

TestCafe allows you to observe the page state. For this purpose, it offers special kinds of functions that will execute your code on the client: Selector used to get direct access to DOM elements and ClientFunction used to obtain arbitrary data from the client side. You call these functions as regular async functions, that is you can obtain their results and use parameters to pass data to them.

For example, clicking the Submit button on the sample web page opens a "Thank you" page. To get access to DOM elements on the opened page, the Selector function can be used. The following example demonstrates how to access the article header element and obtain its actual text.

import { Selector } from 'testcafe';

// Declare the parameterized Selector function
// to get access to a DOM element identified by the `id` attribute
const getElementById = Selector(id => document.getElementById(id));

fixture `Getting Started`
    .page('https://devexpress.github.io/testcafe/example');

test('My first test', async t => {
    await t
        .typeText('#developer-name', 'John Smith')
        .click('#submit-button');

    // Use the Selector function to get access to the article header
    const articleHeader = await getElementById('article-header');

    // Obtain the text of the article header
    const headerText = articleHeader.innerText;
});

For more information, see Selecting Page Elements.

A functional test also should check the result of actions performed. For example, the article header on the "Thank you" page should address a user by the entered name. To check if the header is correct, you have to add an assertion to the test.

You can use assertions from Node's built-in assert module or from any third-party assertion library. Before calling assertions, make sure an assertion library is installed into your project.

The following test demonstrates how to use an assertion from Chai Assertion Library. Before running the test, install the assertion library by calling the npm install --save-dev chai command.

import { expect } from 'chai';
import { Selector } from 'testcafe';

// Declare the parameterized selector function
// to obtain text content of an element identified by the `id` attribute
const getElementById = Selector(id => document.getElementById(id));

fixture `Getting Started`
    .page('https://devexpress.github.io/testcafe/example');

test('My first test', async t => {
    await t
        .typeText('#developer-name', 'John Smith')
        .click('#submit-button');

    // Use the Selector function to get access to the article header
    const articleHeader = await getElementById('article-header');

    // Use the assertion to check if the actual header text is equal to the expected one
    expect(articleHeader.innerText).to.equal('Thank you, John Smith!');
});

• Test API
• Using TestCafe
• Extending TestCafe
• Recipes

Please use our issues page to report a bug or request a feature.

For general purpose questions and discussions, use the discussion board.

For more information on how to help us improve TestCafe, please see the CONTRIBUTING.md file.

• Blog
• Twitter

MIT

Developer Express Inc. (https://devexpress.com)