Constructor
new Report()
No constructor arguments supported.
Contracts may need to be set up inside callbacks _after_ creation,
hence this convention.
Methods
done() → {Report}
Locks the report object, so no modifications may be made later.
Also if onDone callback(s) are present, they are executed
unless there are pending async checks.
Returns:
this (chainable)
- Type
- Report
explain(target, options) → {string}
Stringify objects recursively with limited depth
and circular reference tracking.
Generally JSON.stringify is used as reference:
strings are escaped and double-quoted; numbers, boolean, and nulls are
stringified "as is"; objects and arrays are descended into.
The differences follow:
undefined is reported as ''.
Objects that have constructors are prefixed with class names.
Object and array content is abbreviated as "..." and "Circular"
in case of depth exhaustion and circular reference, respectively.
Functions are naively stringified.
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
target |
Any | Thingy to serialize. | |||||||||
options |
object |
Properties
|
Returns:
- Type
- string
getCount() → {number}
Number of checks performed.
Returns:
- Type
- number
getDetails(n) → {object}
Returns detailed report on a specific check
Parameters:
Name | Type | Description |
---|---|---|
n |
integer | check number, must be <= getCount() |
Returns:
- Type
- object
getDone() → {boolean}
Tells whether the report is finished,
i.e. done() was called & no pending async checks.
Returns:
- Type
- boolean
getFailCount() → {number}
Number of checks failing.
Returns:
- Type
- number
getGhost() → {string}
Return a string of failing/passing checks.
This may be useful for validating custom conditions.
Consecutive passing checka are represented by numbers.
A capital letter in the string represents failure.
See also toString()
Returns:
- Type
- string
Examples
// 10 passing checks
"r(10)"
// 10 checks with 1 failure in the middle
"r(5,N,4)"
// 10 checks including a nested contract
"r(3,r(1,N),6)"
// no checks were run - auto-fail
"r(Z)"
getPass(n) → {boolean}
Without argument returns whether the contract was fulfilled.
As a special case, if no checks were run and the contract is finished,
returns false, as in "someone must have forgotten to execute
planned checks. Use pass() if no checks are planned.
If a parameter is given, return the status of n-th check instead.
Parameters:
Name | Type | Description |
---|---|---|
n |
integer |
Returns:
- Type
- boolean
info(…message) → {Report}
Append an informational message to the report.
Non-string values will be stringified via explain().
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
message |
Any |
<repeatable> |
Returns:
chainable
- Type
- Report
last() → {boolean}
Whether the last check was a success.
This is just a shortcut for foo.getDetails(foo.getCount).pass
Returns:
- Type
- boolean
onDone(callback) → {Report}
Execute code when contract execution finishes.
Report object cannot be modified at this point,
and no additional checks my be present.
Parameters:
Name | Type | Description |
---|---|---|
callback |
function | first argument is report in question |
Returns:
this (chainable)
- Type
- Report
Example
report.onDone( r => { if (!r.getPass()) console.log(r.toString()) } )
onFail(callback) → {Report}
Execute code when contract execution finishes, if it failed.
Report object cannot be modified at this point,
and no additional checks my be present.
Parameters:
Name | Type | Description |
---|---|---|
callback |
function | first argument is report in question |
Returns:
this (chainable)
- Type
- Report
Example
report.onFail( r => console.log(r.toString()) );
run(contract) → {Report}
apply given function to a Report object, lock report afterwards.
If function is async (i.e. returns a Promise),
the report will only be done() after the promise resolves.
This is done so to ensure that all checks that await on a value
are resolved.
Parameters:
Name | Type | Description |
---|---|---|
contract |
Contract | The function to execute Additional parameters may be _prepended_ to contract and will be passed to it _after_ the Report object in question. |
Returns:
this (chainable)
- Type
- Report
Examples
Basic usage
const r = new Report().run( ok => ok.equal( 'war', 'peace', '1984' ) );
r.getPass(); // false
r.getDone(); // true
r.toString();
r(
!1. 1984
- war
+ peace
)
Passing additional arguments to callback.
// The contract body is the last argument.
new Report().run( { v: 4.2, colors: [ 'blue' ] }, (r, arg) => {
r.type( arg, 'object' );
r.type( arg.v, 'number' );
r.cmpNum( arg.v, '>=', 3.14 );
r.type( arg.colors, 'array' );
});
Async function
const r = new Report().run(
async ok => ok.equal( await 6*9, 42, 'fails but later' ) );
r.getPass(); // true
r.getDone(); // false
// ...wait for event loop to tick
r.getPass(); // false
r.getDone(); // true
runSync(contract) → {Report}
apply given function (contract) to a Report object.
Multiple such contrats may be applied, and the report is not locked.
Async function are permitted but may not behave as expected.
Parameters:
Name | Type | Description |
---|---|---|
contract |
Contract | The function to execute Additional parameters may be _prepended_ to contract and will be passed to it _after_ the Report object in question. |
Returns:
this (chainable)
- Type
- Report
Example
Basic usage
const r = new Report()
.runSync( ok => ok.equal( 'war', 'peace', '1984' ) )
.runSync( ok => ok.type ( [], 'array', 'some more checks' ) )
.done();
toJSON() → {Object}
returns a plain serializable object
Returns:
- Type
- Object
toString() → {string}
Returns serialized diff-like report with nesting and indentation.
Passing conditions are merked with numbers, failing are prefixed
with a bang (!).
See also getGhost()
Returns:
- Type
- string
Examples
// no checks run
const r = new Report();
r.toString();
r(
)
// pass
const r = new Report();
r.pass('foo bared');
r.toString();
r(
1. foo bared
)
// fail
const r = new Report();
r.equal('war', 'peace');
r.toString();
r(
!1.
^ Condition equal failed at <file>:<line>:<char>
- war
+ peace
)