These CanaryTest
methods can be used to add callbacks in test groups. This becomes useful if a certain setup action must be done before running the tests in the group and a corresponding tear-down action after, or if such actions must be performed before and after every test in a group.
Test callbacks can optionally be assigned names. Descriptive callback names will make it easier to understand where errors occur, when they occur.
These methods return CanaryTestCallback
instances, which wrap the given callbacks and names together with some other relevant data. It should rarely if ever be necessary to store or handle the return values of these methods.
onBegin
Add a callback that is run when a test group is begun. More than one callback can be added in this way. The callbacks are run in the order they were added.
onBegin
callbacks run after onEachBegin
callbacks and before all others. They run before child tests but after evaluating a test group's body function. (Normally, the body function is responsible for adding the callback in the first place.)
If any onBegin
callback produces an error or otherwise aborts the test, any remaining onBegin
callbacks will be ignored.
Arguments: ({string} name, {function} callback)
or ({function} callback)
If the callback function returns a Promise
, then when the test is run Canary will wait to see if the promise is resolved or rejected before progressing with the test. (A resolved promise indicates that the callback ran without errors and a rejected promise is treated the same as an unhandled thrown error.)
The callback function is invoked with both this
and the first argument referring to the just-begun test group.
Returns: The new CanaryTestCallback
instance that was added to the test group.
Examples:
canary.group("Example test group", function(){
this.onBegin("Set up the tests", function(){
doSetupStuff();
});
this.test("First example test", function(){
assert("hello" === "hello");
});
this.test("Second example test", function(){
assert("world" === "world");
});
});
onEnd
Add a callback that is run when a test group is ended, regardless of whether the test group was successful or not. More than one callback can be added in this way. The callbacks are run in the order they were added.
onEnd
callbacks are run before onEachEnd
callbacks and after child tests and all other callbacks.
If any onEnd
callback produces an error or otherwise aborts the test, any remaining onEnd
and onEachEnd
callbacks will still be attempted.
Arguments: ({string} name, {function} callback)
or ({function} callback)
If the callback function returns a Promise
, then when the test is run Canary will wait to see if the promise is resolved or rejected before progressing with the test. (A resolved promise indicates that the callback ran without errors and a rejected promise is treated the same as an unhandled thrown error.)
The callback function is invoked with both this
and the first argument referring to the ended test group.
Returns: The new CanaryTestCallback
instance that was added to the test group.
Examples:
canary.group("Example test group", function(){
this.test("First example test", function(){
assert("hello" === "hello");
});
this.test("Second example test", function(){
assert("world" === "world");
});
this.onEnd("Clean up after the tests", function(){
doCleanUpStuff();
});
});
onSuccess
Add a callback that is run when a test group is completed without errors. More than one callback can be added in this way. The callbacks are run in the order they were added.
onSuccess
callbacks are run before onEachSuccess
, onEnd
, and onEachEnd
callbacks. They run after child tests and onEachBegin
and onBegin
callbacks.
In the case that an onSuccess
or onEachSuccess
callback produces an error that causes the test to fail as its completion is being handled, onFailure
and onEachFailure
callbacks will run after the failing onSuccess
or onEachSuccess
callback and the test will be marked as unsuccessful.
If any onSuccess
callback produces an error or otherwise aborts the test, any remaining onSuccess
and onEachSuccess
callbacks will be ignored.
Arguments: ({string} name, {function} callback)
or ({function} callback)
If the callback function returns a Promise
, then when the test is run Canary will wait to see if the promise is resolved or rejected before progressing with the test. (A resolved promise indicates that the callback ran without errors and a rejected promise is treated the same as an unhandled thrown error.)
The callback function is invoked with both this
and the first argument referring to the successful test group.
Returns: The new CanaryTestCallback
instance that was added to the test group.
Examples:
canary.group("Example test group", function(){
this.test("First example test", function(){
assert("hello" === "hello");
});
this.test("Second example test", function(){
assert("world" === "world");
});
this.onSuccess("Run after all tests passed", function(){
doSuccessStuff();
});
});
onFailure
Add a callback that is run when a test group is aborted. More than one callback can be added in this way. The callbacks are run in the order they were added.
onFailure
callbacks are run before onEachFailure
, onEnd
, and onEachEnd
callbacks. They run after child tests and onEachBegin
and onBegin
callbacks.
In the case that an onSuccess
or onEachSuccess
callback produces an error that causes the test to fail as its completion is being handled, onFailure
and onEachFailure
callbacks will run after the failing onSuccess
or onEachSuccess
callback and the test will be marked as unsuccessful.
If any onFailure
callback produces an error or otherwise aborts the test, any remaining onFailure
and onEachFailure
callbacks will still be attempted.
Arguments: ({string} name, {function} callback)
or ({function} callback)
If the callback function returns a Promise
, then when the test is run Canary will wait to see if the promise is resolved or rejected before progressing with the test. (A resolved promise indicates that the callback ran without errors and a rejected promise is treated the same as an unhandled thrown error.)
The callback function is invoked with both this
and the first argument referring to the failed test group.
Returns: The new CanaryTestCallback
instance that was added to the test group.
Examples:
canary.group("Example test group", function(){
this.test("First example test", function(){
assert("hello" === "hello");
});
this.test("Second example test", function(){
assert("world" === "world");
});
this.onFailure("Run after any tests failed", function(){
doFailureStuff();
});
});
onEachBegin
Add a callback that is run once as every test belonging to a group is begun. More than one callback can be added in this way. The callbacks are run in the order they were added. The callbacks apply only to immediate child tests and test groups; they are not applied recursively.
onEachBegin
callbacks run before all other callbacks. They run before child tests but after evaluating a test group's body function. (Normally, the body function is responsible for adding the callback in the first place.)
If any onEachBegin
callback produces an error or otherwise aborts the test, any remaining onEachBegin
and onBegin
callbacks will be ignored.
Arguments: ({string} name, {function} callback)
or ({function} callback)
If the callback function returns a Promise
, then when the test is run Canary will wait to see if the promise is resolved or rejected before progressing with the test. (A resolved promise indicates that the callback ran without errors and a rejected promise is treated the same as an unhandled thrown error.)
The callback function is invoked with both this
and the first argument referring to the begun test, not the test group to which the callback was added. The test group to which the callback was added (and of which the just-begun test is a child) can be referred to via the parent
property. For example, via this.parent
.
Returns: The new CanaryTestCallback
instance that was added to the test group.
Examples:
canary.group("Example test group", function(){
this.onEachBegin("Set up each test", function(){
doSetupStuff();
});
this.test("First example test", function(){
assert("hello" === "hello");
});
this.test("Second example test", function(){
assert("world" === "world");
});
});
onEachEnd
Add a callback that is run once as every test belonging to a group is ended, regardless of whether the test group was successful or not. More than one callback can be added in this way. The callbacks are run in the order they were added. The callbacks apply only to immediate child tests and test groups; they are not applied recursively.
onEachEnd
callbacks run after all other callbacks.
If any onEachEnd
callback produces an error or otherwise aborts the test, any remaining onEachEnd
callbacks will still be attempted.
Arguments: ({string} name, {function} callback)
or ({function} callback)
If the callback function returns a Promise
, then when the test is run Canary will wait to see if the promise is resolved or rejected before progressing with the test. (A resolved promise indicates that the callback ran without errors and a rejected promise is treated the same as an unhandled thrown error.)
The callback function is invoked with both this
and the first argument referring to the ended test, not the test group to which the callback was added. The test group to which the callback was added (and of which the ended test is a child) can be referred to via the parent
property. For example, via this.parent
.
Returns: The new CanaryTestCallback
instance that was added to the test group.
Examples:
canary.group("Example test group", function(){
this.test("First example test", function(){
assert("hello" === "hello");
});
this.test("Second example test", function(){
assert("world" === "world");
});
this.onEachEnd("Clean up after each test", function(){
doCleanUpStuff();
});
});
onEachSuccess
Add a callback that is run once as every test belonging to a group is completed without errors. More than one callback can be added in this way. The callbacks are run in the order they were added. The callbacks apply only to immediate child tests and test groups; they are not applied recursively.
onSuccess
callbacks are run before onEachSuccess
, onEnd
, and onEachEnd
callbacks. They run after child tests and onEachBegin
and onBegin
callbacks.
In the case that an onSuccess
or onEachSuccess
callback produces an error that causes the test to fail as its completion is being handled, onFailure
and onEachFailure
callbacks will run after the failing onSuccess
or onEachSuccess
callback and the test will be marked as unsuccessful.
If any onEachSuccess
callback produces an error or otherwise aborts the test, any remaining onEachSuccess
callbacks will be ignored.
Arguments: ({string} name, {function} callback)
or ({function} callback)
If the callback function returns a Promise
, then when the test is run Canary will wait to see if the promise is resolved or rejected before progressing with the test. (A resolved promise indicates that the callback ran without errors and a rejected promise is treated the same as an unhandled thrown error.)
The callback function is invoked with both this
and the first argument referring to the successful test, not the test group to which the callback was added. The test group to which the callback was added (and of which the successful test is a child) can be referred to via the parent
property. For example, via this.parent
.
Returns: The new CanaryTestCallback
instance that was added to the test group.
Examples:
canary.group("Example test group", function(){
this.test("First example test", function(){
assert("hello" === "hello");
});
this.test("Second example test", function(){
assert("world" === "world");
});
this.onEachSuccess("Run after every successful test", function(){
doSuccessStuff();
});
});
onEachFailure
Add a callback that is run once as any test belonging to a group is aborted. More than one callback can be added in this way. The callbacks are run in the order they were added. The callbacks apply only to immediate child tests and test groups; they are not applied recursively.
onEachFailure
are run before onEnd
, and onEachEnd
callbacks. They run after child tests and onEachBegin
, onBegin
, and onFailure
callbacks.
In the case that an onSuccess
or onEachSuccess
callback produces an error that causes the test to fail as its completion is being handled, onFailure
and onEachFailure
callbacks will run after the failing onSuccess
or onEachSuccess
callback and the test will be marked as unsuccessful.
If any onEachFailure
callback produces an error or otherwise aborts the test, any remaining onEachFailure
callbacks will still be attempted.
Arguments: ({string} name, {function} callback)
or ({function} callback)
If the callback function returns a Promise
, then when the test is run Canary will wait to see if the promise is resolved or rejected before progressing with the test. (A resolved promise indicates that the callback ran without errors and a rejected promise is treated the same as an unhandled thrown error.)
The callback function is invoked with both this
and the first argument referring to the failed test, not the test group to which the callback was added. The test group to which the callback was added (and of which the failing test is a child) can be referred to via the parent
property. For example, via this.parent
.
Returns: The new CanaryTestCallback
instance that was added to the test group.
Examples:
canary.group("Example test group", function(){
this.test("First example test", function(){
assert("hello" === "hello");
});
this.test("Second example test", function(){
assert("world" === "world");
});
this.onEachFailure("Run after any failed test", function(){
doFailureStuff();
});
});