Using Canary

Canary's API is the interface used to write and to run automated JavaScript tests. It is built on the CanaryTest class. You can acquire an instance to be shared by the automated tests in your package by using the CanaryTest.Group function. By convention, this instance should be referred to as canary.

const canary = require("canary-test").Group("My Canary Instance");
import CanaryTest from "canary-test";
const canary = CanaryTest.Group("My Canary Instance");

You can add tests and groups of tests to your shared Canary instance using the test, group, and series methods.

canary.test("Example test", function(){
    assert(2 + 2 === 4);
});

You can run the tests that have been attached to this shared instance by calling its doReport method. With the default options, this method will log detailed status messages, then it will immediately terminate the process upon completion. The process will exit with an error status code if any test failed, or with a success status code if no tests failed.

canary.doReport();

The Test Class

The CanaryTest class is the default exported value of the canary-test package. Although most of the work done with Canary will be using the methods of instances of this class, it should not normally be necessary to instantiate a CanaryTest yourself.

assert(canary instanceof CanaryTest);

There are also functions available for creating disconnected test groups and series in a similar way, specifically CanaryTest.Group and CanaryTest.Series:

const someGroup = CanaryTest.Group("Some group");
assert(someGroup.isGroup);
const someSeries = CanaryTest.Series("Some series");
assert(someSeries.isSeries);

The library also utilizes CanaryTestCallback and CanaryTestError classes. These classes can be referred to with CanaryTest.Callback and CanaryTest.Error, respectively. These classes are mainly for internal use and, normally, it will not be necessary to work with them directly.

List of Attributes

Here is an exhaustive list of documented CanaryTest methods and other instance attributes. Attributes not documented here are liable to change often and without notice; it is not recommended to rely on undocumented implementation details.