TESTCAFE METHODS

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.

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.

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'
    }]
]

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.

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.