Class: Report

Report()

The core of the refutable library, the report object contains info about passing and failing conditions.

Constructor

new Report()

No constructor arguments supported. Contracts may need to be set up inside callbacks _after_ creation, hence this convention.
Source:

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.
Source:
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
Name Type Description
depth integer How many levels to descend. Default = 3.
path string Circular reference path prefix. Default = '$'.
Source:
Returns:
Type
string

getCount() → {number}

Number of checks performed.
Source:
Returns:
Type
number

getDetails(n) → {object}

Returns detailed report on a specific check
Parameters:
Name Type Description
n integer check number, must be <= getCount()
Source:
Returns:
Type
object

getDone() → {boolean}

Tells whether the report is finished, i.e. done() was called & no pending async checks.
Source:
Returns:
Type
boolean

getFailCount() → {number}

Number of checks failing.
Source:
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()
Source:
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
Source:
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>
Source:
Returns:
chainable
Type
Report

last() → {boolean}

Whether the last check was a success. This is just a shortcut for foo.getDetails(foo.getCount).pass
Source:
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
Source:
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
Source:
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.
Source:
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.
Source:
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
Source:
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()
Source:
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
 )