Spaz's Given-When-Then

Super simple Given-When-Then testing in Node.js

Install and Usage

npm install spazmodius/gwt -D

Example:

const given = require('@spazmodius/gwt')
const crypto = require('crypto')
const { Buffer } = require('buffer')

given(5)
.when(crypto.randomBytes)
.then(({ returned }) => returned instanceof Buffer)
.then(({ returned }) => returned.length === 4)

Runnng the above script, which has 1 passing and 1 failing test, results in the output:

───────
Given 5
 When randomBytes
 Then returned.length===4
Failed! returned false
════════════════════════════════
Test Summary: 1 passed, 1 failed

Async Support

All functions that are provided to given(), when(), and then() may be async, or return a Promise.

Colored Output

If the colors package is available, then console output will be colored appropriately. Installing this package does not automatically install colors.

API

given( [description], [...values] )

given( [description], fn, [...args] )

Argument	Type	Optional	Description
description	string	✓	Description of this Given clause. If not specified, a description will be generated.
values	any	✓	Zero or more context values (or Promises).
fn	function		A function that returns a single context value or Promise.
args	any	✓	Arguments to be passed to fn.

Start a new test-case. May be followed by more .given(), or .when().

You may provide directly any number of values or Promises, which will become context values.

Note: because of the supported signatures, if the first of values is a string, then the description argument must be provided. You may pass undefined or '' to get the generated default.

Alternatively, provide a function, or async function, along with arguments; the return value of fn(...args) will become one context value.

All context values will be passed to the when action, as arguments in the same order that they appear in all the given()s.

.when( [description], action, [...more] )

Argument	Type	Optional	Description
description	string	✓	Description of this When clause. If not specified, a description will be generated.
action	function		Function that executes the action to test. May be async.
more	any	✓	More arguments to be passed to action.

Specify the action to test. Must be followed by .then().

The action() will be called with each of the context values, generated by the givens, and any more values. It can return a value or Promise, or throw an exception, and/or mutate context objects.

.then( [description], expectation, [...more] )

Argument	Type	Optional	Description
description	string	✓	Description of this Then clause. If not specified, a description will be generated.
expectation	function		Function that tests the results of the when action. May be async. It has signature (result, context, more...).
more	any	✓	Additional arguments to pass to expectation().

Test an expectation about the results of the when action. May be followed by more calls to .then().

expectation() will be called with these arguments:

• result
  An object that captures the result of executing the when action, with properties:
  • result.returned
    The action's returned or resolved value. If the action threw an error, reading this property will throw that error.
  • result.threw
    The error thrown by the action. if the action did not throw an error, this value is undefined.
• context
  An array of the arguments that were passed to the when action. These are the context values generated by the givens, and any more values provided to .when().
• more...
  Any more arguments provided to .then() will be passed through to expectation().

If expectation() returns true, or a Promise that resolves to true, then the test passes. Any other return or resolution value, or throwing an error, fails the test. In the case of failure, the return value or thrown error will be reported.

However, if expectation() returns or resolves to undefined, the test is inconclusive. This might occur if the expectation() makes assertions, but does not end with return true.