Migration from TestCafe v0.x.y to v1.0.0

TestCafe v1.0.0 introduces minor changes to the framework’s behavior and programming interface. This document lists these changes and describes how to migrate to the new version.

Test Syntax Validation Disabled: All Input Files Are Executed

Previous versions performed test syntax validation within input script files before executing them. Only files that contained the fixture and test directives were executed.

Starting with v1.0.0, input script files are not validated. This means that TestCafe executes all the scripts you specify as test sources. If you use Glob patterns to specify input test files, please recheck these patterns to avoid unintended file matches.

The --disable-test-syntax-validation command line flag and the disableTestSyntaxValidation option for the runner.run API method that disabled test syntax validation were removed in v1.0.0.

What Has Improved

You can now load tests dynamically without additional customization. The following example illustrates how tests can be imported from an external library:

external-lib.js

export default function runFixture(name, url) {
    fixture(name)
        .page(url);

    test(`${url} test`, async t => {
        // ...
    });
}

test.js

import runFixture from './external-lib';

const fixtureName = 'My fixture';
const url = 'https://testPage';

runFixture(fixtureName, url);

Programming Interface: Multiple Method Calls Prohibited

Previous versions allowed you to call the runner.src, runner.browsers and runner.reporter methods several times to specify multiple test files, browsers or reporters.

const stream = fs.createWriteStream('report.json');

runner
    .src('/home/user/tests/fixture1.js')
    .src('fixture5.js')
    .browsers('chrome')
    .browsers('firefox:headless')
    .reporter('minimal')
    .reporter('json', stream);

Starting with v1.0.0, pass arrays to these methods to specify multiple values.

To use a reporter that writes to a file, add a { name, output } object to an array (see the runner.reporter description for details).

runner
    .src(['/home/user/tests/fixture1.js', 'fixture5.js'])
    .browsers(['chrome', 'firefox:headless'])
    .reporter(['minimal', { name: 'json', output: 'report.json' }]);

What Has Improved

The configuration file we implemented is consistent with the API and command line interface.

Custom Request Hooks: Asynchronous API

Request hook methods became asynchronous in TestCafe v1.0.0.

If the onRequest or onResponse method in your custom hook returns a Promise, TestCafe now waits for this Promise to resolve.

You should add the async keyword to the asynchronous onRequest and onResponse method declarations.

import { RequestHook } from 'testcafe';

class MyRequestHook extends RequestHook {
    constructor (requestFilterRules, responseEventConfigureOpts) {
        super(requestFilterRules, responseEventConfigureOpts);
        // ...
    }

    async onRequest (event) {
        // ...
    }

    async onResponse (event) {
        // ...
    }
}

What Has Improved

You can call asynchronous fs functions, invoke a child_process, or perform asynchronous network requests (to a database or any other server) from inside the hooks.

Custom Reporter Plugins: Asynchronous API

TestCafe v1.0.0 also introduces an asynchronous API for reporter plugins.

Similarly to request hooks, if any of the custom reporter’s methods (reportTaskStart, reportFixtureStart, reportTestDone or reportTaskDone) returns a Promise, this Promise is now awaited.

Since the reporter methods are now asynchronous, add the async keyword to their declarations.

async reportTaskStart (startTime, userAgents, testCount) {
    // ...
},

async reportFixtureStart (name, path, meta) {
    // ...
},

async reportTestDone (name, testRunInfo, meta) {
    // ...
},

async reportTaskDone (endTime, passed, warnings, result) {
    // ...
}

What Has Improved

Reporters can call asynchronous fs functions, invoke a child_process, or perform asynchronous network requests (to send an email, use REST API, connect to a database, etc).