TestCafe v2015.1   |   Documentation
The documentation on this webpage describes TestCafe v2015.1. This product is no longer available and has been replaced by TestCafe Studio. TestCafe Studio is our new cross-platform IDE for end-to-end web testing.
To learn more about TestCafe Studio, please visit www.devexpress.com/testcafestudio

TESTCAFE METHODS

Utilize the methods listed in this section to determine the available fixtures and workers, and use this information to execute your tests.

listAvailableBrowsers

Returns an array of strings identifying the available browsers.

TestCafe.listAvailableBrowsers();

return value: Array of String.

["Google Chrome", "Mozilla Firefox", "Internet Explorer"]

The strings returned by this method are the same as those specified in the TestCafe Settings or in the TestCafe Constructor. You can analyze the array returned to select the browsers that will run the tests. Then transmit the filtered (or unchanged) list to the runTests method to use these browsers for test execution.

listConnectedWorkers

Returns an array of strings identifying the connected remote workers.

TestCafe.listConnectedWorkers();

return value: Array of String.

[ "Google Chrome 64 bit", "My iPhone", "Surface" ]

To learn how to connect remote workers when running TestCafe in a Continuous Integration system, refer to the Continuous Integration tutorial.

The strings returned by this method are the same as those specified in the URLs used to connect workers. You can analyze the array returned to select the workers that will run the tests. Then transmit the filtered or unchanged list to the runTests method to use these workers for test execution.

listDirectory

Obtains information about fixtures at a specified path.

TestCafe.listDirectory(path, callback(error, directoryInfo))

path: An empty string specifies the root test directory set in the TestCafe Settings or in the TestCafe Constructor. If you need to obtain data from a directory within the root folder, specify a string with the target directory name. To access folders at deeper nesting levels, pass an array of strings corresponding to the folder structure you wish to navigate.

error: null if the information is successfully obtained. Otherwise, a string with an error code.

directoryInfo: An object that contains fixture and test information in the specified directories.

When you run tests using the runTests method, you need to specify which fixtures or tests are to be executed. This can be done in one of the following ways.

  • Use default settings so that TestCafe will run all fixtures in the root test folder and its nested directories. In this instance, it is not necessary to use the listDirectory function.
  • Specify individual fixtures or tests to be executed. In this case, you will need to use the listDirectory method to obtain fixture and test information.

Below is a basic example of how to call the listDirectory method to obtain information about the root tests directory.

var TestCafe = require('testcafe');
var testCafe = new TestCafe();
testCafe.listDirectory("", function processDirectory(error, directoryInfo) {
    console.log(directoryInfo);
});

Sample output listing.

{ dirs:
   [ { name: 'DevExpress', path: 'DevExpress' },
     { name: 'TestCafe', path: 'TestCafe' } ],
  buildErrs: null,
  fixtures:
   [ { uid: 'e48c0dbe-c316-4405-a255-6602cc4cb29e',
       name: 'TestCafe Example Page',
       fileName: 'testcafe_example_page.test.js',
       page: 'http://testcafe.devexpress.com/Example',
       tests: [Object] } ] 
}

Note that the buildErrs field above displays a null value. When TestCafe retrieves fixture information, it pre-builds each JavaScript file and checks for errors. If errors are found, they will be reflected in this field. The following code line illustrates how you can output the content of this field to the Console.

The following code shows how to log the buildErrs field only .

testCafe.listDirectory("", function processDirectory(error, directoryInfo) {
    console.log(directoryInfo.buildErrs);
});

The code below illustrates sample output for a build error.

[{
    fixtureUid: '1fd5ffa3-ae83-4854-b945-4bd8203ad075',
    fixture: {
        fileName: 'testcafe_example_page.test.js',
        path: [],
        name: 'testcafe_example_page.test.js',
        page: 'http://testcafe.devexpress.dev/',
        sharedJs: '',
        tests: []
    },
    code: 'FIXTURE_FILE_ERR_FIXTURE_IS_UNDEFINED',
    filename: 'D:\\TestCafe-13.1\\tests\\testcafe_example_page.test.js'
}]

Similarly, you can log and learn about the structure of tests in a specific fixture. This example uses JSONPath to access a fixture by its name.

var jsonPath = require('JSONPath');
testCafe.listDirectory('', function processDirectory(error, directoryInfo) {
    console.log(jsonPath.eval(directoryInfo, "$.fixtures[?(@.name=='TestCafe Example Page')].tests"));
});

Sample output listing:

[
    [{
        uid: 'ee1ee8a9-1dac-476b-8536-6f36a35cf873',
        name: 'act.type samples'
    }, {
        uid: '4a15e24b-3200-4af0-98f4-a0c8724615c8',
        name: 'act.click, array parameter, ok() assertion'
    }, {
        uid: 'a812203d-c4e4-4370-90c8-24e90d12df8d',
        name: 'Video Example'
    }]
]

runTests

Runs tests. You can use this method to run individual tests (by using their UIDs), a group of tests (fixtures or folders), as well as all the tests from the specified fixture or folder, and all tests against all fixtures and subfolders in the test folder.

TestCafe.runTests(options[, callback(errors, taskUid, workers)])

options: Object. Specifies which tests to run, and which registered browsers and connected workers to use.

{
    sourceType: 'dir' | 'fixture' | 'test' | 'group',
    source: 'TestCafe/Example' | '3818c372-684b-4f26-a12b-a6b5d7eaca3a' | ['ASPxCallback', 'ASPxGridview/Tests', 'ASPxHtmlEditor/ToolbarItemsTests/DropdownMenu'], 
    browsers: ['Internet Explorer', 'Chrome'],
    workers: ['iPad'],
    quarantineMode: false | true,
    reportFormat: 'junit' | 'nunit' | 'json',
    reportPath: 'TestCafe/reports/report1.xml',
    takeScreenshotOnFails: false | true,
    failOnJsErrors: false | true
}

sourceType: String. Specifies whether to run all tests in a directory, in a fixture, a group of tests or a specific test.
By default, if the sourceType parameter is empty, it is identified automatically. Specify this parameter when you wish to run tests from the specific fixture or folder that has the same name (specified in the source parameter). In this case, with the omitted source type, tests will be run according to the following priority: folder->fixture. To run tests against all fixtures in your tests folder, omit the sourceType and source parameters.

source: String. If the sourceType parameter value is 'dir', specify the directory path relative to the tests root folder. If sourceType is 'fixture' or 'test', specify the relative path in the format 'DirectoryName/FixtureName/TestName' or corresponding Uid, which can be obtained using the listDirectory method. If the sourceType parameter is 'group', specify an array with square brackets. The array can contain folders, fixtures, tests and their combinations. A path to a fixture or to a test should be specified in the following format: DirectoryName/FixtureName/TestName.
Without specifying the sourceType, set the source parameter value to the name of a specific fixture or folder you wish to run tests from. If in the test folder there is a folder or a fixture with the same name, tests will be run according to the following priority: folder->fixture. To run tests against all fixtures in your tests folder, omit the sourceType and source parameters.

browsers: Array of String. Specifies which registered browsers to use when testing. You can initialize this field using the listAvailableBrowsers method.

workers: Array of String. Specifies which connected workers to use when testing. You can initialize this field using the listConnectedWorkers method.

quarantineMode: Boolean. true to enable the quarantine mode for tests that fail. The quarantine mode allows you to isolate unstable tests. When a test fails, it gets into the quarantine where it will be run five more times. If the test fails in all attempts, it is marked as failed. If any of the test runs are successful, the test will be marked as unstable and will be added to a specific list of unstable tests in the test task report.

reportFormat: String. Specifies the format in which a test report should be saved - JUnit ('junit'), NUnit ('nunit') or JSON ('json') (by default). See Test Run Reports for examples.

reportPath: String. Specifies the path where the report file should be saved, and the file name. The path can be absolute or relative from the folder that contains the node.js application.

Note that there is also a global report storage. Its location is specified by the reportsPath option of the TestCafe constructor.

Regardless of the reportPath and reportFormat options passed to runTests, reports are additionally saved to the global storage in the JSON format. If screenshots are taken during the test run, they are saved to the global storage only.

takeScreenshotOnFails: Boolean. true to take a screenshot of the tested page whenever an assertion fails or an error occurs. Screenshots are saved to the test report.

failOnJsErrors: Boolean. true to fail a test whenever a JavaScript error occurs on a tested web page.

Important note

You can also handle the taskComplete and taskUpdated events to save test execution results in the specified format.

The following is a simple example that runs a specific test on all registered browsers and connected workers, and saves execution results in the JUnit format.

var jsonPath = require('JSONPath');

testCafe.listDirectory('', processDirectory);

function processDirectory(error, directoryInfo) {
    var jsonPathQuery = "$.fixtures[?(@.name=='TestCafe Example Page')].tests[?(@.name=='act.type samples')].uid";
    var testUid = jsonPath.eval(directoryInfo, jsonPathQuery);
    runTest(testUid);
}

function runTest(testUid) {
    var runOptions = {
        sourceType: 'test',
        source: testUid,
        workers: testCafe.listConnectedWorkers(),
        browsers: testCafe.listAvailableBrowsers(),
        quarantineMode: true,
        reportFormat: 'junit',
        reportPath: '/Report.xml'
    };
    testCafe.runTests(runOptions);
}

Using the optional callback parameter, you can check whether or not the task has actually started, which task identifiers were used, and which workers were able to run. If a task fails to run, you can also determine the error type, log an error message and close the process with an error code. Consider the following example, which tries to run a fixture that does not exist.

var runOptions = {
    sourceType: 'fixture',
    source: 'invalid_value',
    browsers: testCafe.listAvailableBrowsers()
};
testCafe.runTests(runOptions, function (errors, taskUid, workers) {
    if (errors != null) {
        console.log(errors);
        process.exit(1);
    }
});

You will get the following output.

The "invalid_value" test target is empty or not found.

The following is comprehensive information on callback function parameters.

errors: Array of String. Lists errors that occurred when trying to launch the task. null if the task has been started successfully.
taskUid: String. Identifies the task being executed. The same identifiers are used in the taskComplete and taskUpdated events. null if the task has not started.
workers: Array of String. Identifies workers and browsers in which the tests are being executed. null if the task has not started.