API testplane

With the Testplane API, you can use it in your scripts or build tools.

To do this, you must include the testplane module and create its instance:

const Testplane = require("testplane");

const config = require("./testplane.conf.js");

const testplane = new Testplane(config);

Then you will have access to the following parameters and methods:

Name	Type	Description
config	Object or String	A testplane config object or a path to the configuration file, relative to the working folder.
events	Object	testplane Events that you can subscribe to.
errors	Object	Errors that testplane can return.
intercept	Function	A function that allows you to subscribe to testplane event interception.
init	Method	Initializes the testplane instance, loads all plugins, etc.
run	Method	Runs tests located at the specified paths.
addTestToRun	Method	Adds a test to the current run.
readTests	Method	Returns an object of type TestCollection.
isFailed	Method	Returns true or false depending on whether there was an error or test failure during the test run.
isWorker	Method	Returns true if the method was called from a testplane worker.
halt	Method	Forcibly terminates the test run in case of a critical error.

config

A testplane config object or a path to the configuration file, relative to the working folder: process.cwd().

events

testplane Events that you can subscribe to.

Example of using the testplane.events object in a testplane plugin:

testplane.on(testplane.events.INIT, async () => {
    console.info("Processing INIT event...");
});

errors

Testplane can return errors of the following types:

• CoreError
• CancelledError
• ClientBridgeError
• HeightViewportError
• OffsetViewportError
• AssertViewError
• ImageDiffError
• NoRefImageError

CoreError

The CoreError is returned in the case of a failed calibration of an empty page (about:blank) in the browser.

The error includes the following message:

Could not calibrate. This could be due to calibration page has failed to open properly

CancelledError

The CancelledError is returned in case of emergency termination by the halt command.

The error includes the following message:

Browser request was cancelled

ClientBridgeError

The ClientBridgeError is returned in case of a failed JavaScript code injection on the client side (browser). Testplane performs code injection using the execute command of WebDriverIO.

The error includes the following message:

Unable to inject client script

HeightViewportError

The HeightViewportError is returned when trying to capture a screenshot of an area whose bottom bound does not fit into the viewport.

The error includes the following message:

Can not capture the specified region of the viewport.
The region bottom bound is outside of the viewport height.
Alternatively, you can test such cases by setting "true" value to option "compositeImage" in the config file
or setting "false" to "compositeImage" and "true" to option "allowViewportOverflow" in "assertView" command.
Element position: <cropArea.left>, <cropArea.top>; size: <cropArea.width>, <cropArea.height>.
Viewport size: <viewport.width>, <viewport.height>.

The message advises the testplane user on what settings to configure in testplane to be able to capture the screenshot of the specified area.

OffsetViewportError

The OffsetViewportError is returned when trying to capture a screenshot of an area whose left, right, or top bounds go beyond the viewport.

The error includes the following message:

Can not capture the specified region of the viewport.
Position of the region is outside of the viewport left, top or right bounds.
Check that elements:
- does not overflow the document
- does not overflow browser viewport
Alternatively, you can increase browser window size using
"setWindowSize" or "windowSize" option in the config file.
But if viewport overflow is expected behavior then you can use
option "allowViewportOverflow" in "assertView" command.

The message advises the testplane user on what settings to configure in testplane to be able to capture the screenshot of the specified area.

AssertViewError

The AssertViewError is returned in case of a failed attempt to capture a screenshot.

The error can contain one of the following messages, depending on the cause of the failure:

duplicate name for "<state>" state

element ("<selector>") still not existing after <this.options.waitforTimeout> ms

element ("<this.selector>") still not existing after <this.options.waitforTimeout> ms

ImageDiffError

The ImageDiffError is returned from the assertView command if a difference (diff) is found when capturing and comparing the screenshot with the reference screenshot.

The error includes the following message:

images are different for "<stateName>" state

Additionally, the ImageDiffError contains the following data:

Property	Description
stateName	the name of the state for which the screenshot was taken
currImg	link to the actual image
refImg	link to the reference image
diffOpts	settings for detecting the diff
diffBounds	bounds of areas with diffs on the image
diffClusters	clusters with diffs on the image

Read more about diffBounds and diffClusters in the looks-same package documentation.

exports.handleImageDiff = (currImg, refImg, state, opts) => {
    const {tolerance, antialiasingTolerance, canHaveCaret, diffAreas, config} = opts;
    const {buildDiffOpts, system: {diffColor}} = config;
    buildDiffOpts.ignoreCaret = buildDiffOpts.ignoreCaret && canHaveCaret;

    const diffOpts = {
        current: currImg.path, reference: refImg.path,
        diffColor, tolerance, antialiasingTolerance, ...buildDiffOpts
    };

    return Promise.reject(ImageDiffError.create(state, currImg, refImg, diffOpts, diffAreas));
};

NoRefImageError

The NoRefImageError is returned from the assertView command if testplane does not find the reference screenshot on the filesystem when capturing and comparing the screenshot.

The error includes the following message:

can not find reference image at <refImg.path> for "<stateName>" state

Additionally, the NoRefImageError contains the following data:

Property	Description
stateName	the name of the state for which the screenshot was taken
currImg	link to the actual image
refImg	link to the reference image

intercept

A function that allows you to subscribe to testplane event interception.

The first argument is the event to intercept, and the second is the event handler.

For example:

testplane.intercept(testplane.events.TEST_FAIL, ({ event, data }) => {
    return {};
});

Read more about event interception in the section "About Event Interception".

init

Initializes the testplane instance, loads all plugins, etc.

Example Call

await testplane.init();

run

Runs tests located at the specified paths.

Returns true if the test run was successful and false if it was not.

Example Call

const success = await testplane.run(testPaths, options);

Call Parameters

All parameters of the testplane.run() method are optional.

Parameter Name	Type	Description
testPaths	String[] or TestCollection	Paths to tests relative to the working folder (process.cwd()) or an object of type TestCollection returned by the readTests method. If paths are not specified, all tests will be run.
options	Object	Object with run options.
options.reporters	String[]	Reporters for the test run results.
options.browsers	String[]	Browsers in which to run the tests.
options.sets	String[]	Sets in which to run the tests.
options.grep	RegExp	A regular expression pattern that specifies tests to run.

addTestToRun

Adds a test to the current run. Returns false if the current run is already finished or cancelled. Otherwise, returns true.

Example Call

const success = testplane.addTestToRun(test, browser);

Call Parameters

All parameters are required.

Parameter Name	Type	Description
test	Test	The test to run.
browserId	String	The browser in which to run the test.

readTests

An asynchronous method that returns an object of type TestCollection.

Example Call

await testplane.readTests(testPaths, options);

Call Parameters

Parameter Name	Type	Description
testPaths	String[]	Paths to tests relative to the working folder (process.cwd()).
options	Object	Object with test reading mode settings.
options.browsers	String[]	Read tests only for the specified browsers.
options.silent	Boolean	Disable event generation while reading tests. Default: false.
options.ignore	String or Glob or String[] or Glob[]	Patterns specifying paths on the filesystem to exclude when searching for tests.
options.sets	String[]	Sets in which to read tests.
options.grep	RegExp	A regular expression pattern that specifies tests to read.

isFailed

Returns true or false depending on whether there was an error or test failure during the test run. Might be useful in plugins to determine the current status of testplane.

Example Call

const failed = testplane.isFailed();

isWorker

Returns true if the method was called from a testplane worker. Returns false if the method was called from the testplane master process.

Might be useful in plugins to distinguish the execution context.

Example Call

// Implementation of some plugin
module.exports = testplane => {
    if (testplane.isWorker()) {
        // This code will be executed only in testplane workers
    } else {
        // This code will be executed only in the testplane master process
    }
};

halt

Forcibly terminates the test run in case of a critical error. If the process cannot gracefully shut down within the specified timeout, it will be forcibly terminated unless the timeout is explicitly set to 0.

Example Call

testplane.halt(error, [timeout=60000ms]);

Call Parameters

Parameter Name	Type	Description
error	Error	The critical error that requires stopping testplane.
timeout	Number	Optional parameter. Timeout for shutting down the testplane process. Default: 60000 ms.

Test Collection

An object of type TestCollection is returned by the testplane.readTests method and is also passed as an argument to the handler of the AFTER_TESTS_READ event.

getBrowsers

Returns a list of browsers for which tests are available in the collection.

Example Call

const browsers = testCollection.getBrowsers();

mapTests

Builds a mapping of tests for the specified browser.

Example Call

const tests = testCollection.mapTests(browserId, (test, browserId) => {
    // ...
});

If the browser is not specified (i.e., a callback is passed as the first argument), the mapping will be built for all browsers.

sortTests

Sorts tests for the specified browser.

Example Call

testCollection.sortTests(browserId, (currentTest, nextTest) => {
    // ...
});

If the browser is not specified (i.e., a callback is passed as the first argument), the sorting will be applied to all browsers.

eachTest

Iterates through the tests for the specified browser.

Example Call

testCollection.eachTest(browserId, (test, browserId) => {
    // ...
});

If the browser is not specified (i.e., a callback is passed as the first argument), the iteration will occur for tests in all browsers.

eachTestByVersions

Iterates through the tests and browser versions for the specified browser.

Utilizes the presence of the browserVersion property for each test.

Example Call

testCollection.eachTestByVersions(browserId, (test, browserId, browserVersion) => {
    // ...
});

disableAll

Disables all tests or tests for the specified browser. Returns a reference to the test collection instance.

Example Calls

disableAll();

or

disableAll(browserId);

If the browser is not specified, all tests will be disabled.

enableAll

Enables all tests or tests for the specified browser. Returns a reference to the test collection instance.

Example Calls

enableAll();

or

enableAll(browserId);

If the browser is not specified, all tests will be enabled.

disableTest

Disables the specified test in all browsers or only in the specified browser. Returns a reference to the test collection instance.

Example Calls

disableTest(fullTitle);

or

disableTest(fullTitle, browserId);

The test is identified by its full title: fullTitle.

enableTest

Enables the specified test in all browsers or only in the specified browser.

enableTest(fullTitle);

or

enableTest(fullTitle, browserId);

getRootSuite

Returns the root suite for the specified browser. Returns undefined if there are no tests for the specified browser in the collection.

Example Call

const rootSuite = getRootSuite(browserId);

eachRootSuite

Iterates through all root suites in the collection that have tests.

Example Call

eachRootSuite((root, browserId) => {
    // ...
});