These CanaryTest
class methods are for those who need more complex or customized behavior from Canary. They are not relevant to the majority of users.
silent
Set a test and all its children to run silently. This means that they will not output any log messages.
The log
method of a CanaryTest
instance can be used to log a message only if the test has not been set to run silently.
Note that when the concise
flag of the doReport
function is set, it will cause all tests to run silently.
Examples:
canary.test("Example silent test", function(){
this.silent();
});
verbose
Set a test and all its children to run verbosely. This means they will output even more detailed logs than usual.
The logVerbose
method of a CanaryTest
instance can be used to log a message only when the test is set to run verbosely.
Note that when the verbose
flag of the doReport
function is set, it will cause all tests to run verbosely that were not otherwise set to run silently.
Examples:
canary.test("Example verbose test", function(){
this.verbose();
});
shouldSkip
Check whether any flags have been set that will cause this test to be skipped, such as by using the todo
or ignore
methods.
Returns: true
is marked to be skipped false
when it is not so marked.
unignore
Un-ignore a test that was previously marked as being ignored.
Examples:
const someTest = canary.test("Example test", function(){
this.ignore();
});
someTest.unignore(); // Nevermind!
getTitle
Get an identifying title for this test. A test's title is its name, preceded by the name of its parent test, preceded by its parent's name, and so on.
Returns: A string, representing a title that can be used to identify this test.
getName
Get the name provided for this test.
Returns: The test's name as a string.
hasTag
Determine whether this test has a certain tag or not.
Arguments: ({string} tag)
Returns: true
when the test has the tag and false
when it does not.
getTags
Get a list of tags that have been added to this test.
Returns: An array of tags.
getTestTotal
Recursively get the number of CanaryTest
instances in a test tree.
Note that if this method is called for a test group, and the group has not already been expanded, then this method will cause it to be expanded. (As though the expandGroups
method was called.)
Returns: The total number of tests in this test tree.
getStatusString
Get a string representing the status of this test.
Returns: "skipped"
if the test was marked as skipped or was never attempted, "passed"
if the test completed successfully, or "failed"
if the test was unsuccessful.
durationSeconds
Get the length of time taken to run this test, in seconds.
Returns: The number of seconds it took to run the test, or undefined
if the test has not yet been completed.
durationMilliseconds
Get the length of time taken to run this test, in milliseconds.
Returns: The number of milliseconds it took to run the test, or undefined
if the test has not yet been completed.
addError
Add an error to the test's list of recorded errors.
The method requires an Error object and optionally accepts another argument indicating the test or callback where the error occurred.
Arguments: ({Error} error, {CanaryTest|CanaryTestCalback} location)
Returns: The newly-created CanaryTestError
instance.
abort
Abort the test and mark it as failed.
The method optionally accepts information about the error that resulted in the test being aborted. The first argument, if provided, must be an Error object, and the second argument can be used to indicate the test or callback where the error occured. (This is the same as with the error
method.)
Arguments: ({Error} error, {CanaryTest|CanaryTestCalback} location)
anyErrors
Get whether any errors were encountered while running this test.
Returns: true
when the test has recorded any errors and false
when it has not.
noErrors
Get whether this test was run without encountering any errors.
Returns: false
when the test has recorded any errors and true
when it has not.
getErrors
Get a list of errors that were encountered while attempting this test, if any.
Returns: An array of CanaryTestError
objects encountered while running this test.
addTest
Add a child test to a test group.
Note that if the test was previously added to another test group, it will be removed from that group as it is added to the new group.
Arguments: ({CanaryTest} test)
removeTest
Remove a child test from a parent group.
Arguments: ({CanaryTest} test)
Returns: true
if the test was in fact a child and was removed and false
if it was not.
orphan
Remove a test from its parent group.
Returns: true
if the test did in fact have a parent and was orphaned and false
if it did not.
getParent
Get the CanaryTest
instance which is the parent of this one.
Returns: The CanaryTest
instance to which this test has been added, or undefined
if the test does not have a parent.
getChildren
Get a list of the tests that are children of this test group.
Returns: An array of CanaryTest
instances which are children of this test group.
applyFilter
Applies a filter function recursively to a test group and all of its children. Tests for which no ancestors or descendants satisfy the filter will be marked, then skipped when tests are run.
This method is leveraged by doReport
in order to enforce the filtering criteria that are passed to it.
Arguments: ({function} filter)
Returns: true
if this test or any of its descendants satisfied the filter and false
if not.
expandGroups
Recursively run all the body functions assigned to test groups, but not to ordinary tests. This has the effect of elaborating the structure of the test tree without actually running tests.
Group expansion is put off until tests are actually needed in order to make the startup performance impact of including tests in an application source file close to nonexistent, even in the case of testing code errors that could potentially cause hangups, since extremely little work is done at the time of declaration.