https://github.com/spazmodius/gwt
Super simple Given-When-Then tests in Node.js
https://github.com/spazmodius/gwt
module node testing
Last synced: about 2 months ago
JSON representation
Super simple Given-When-Then tests in Node.js
- Host: GitHub
- URL: https://github.com/spazmodius/gwt
- Owner: spazmodius
- Created: 2019-02-19T00:39:27.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2020-01-30T17:42:24.000Z (over 6 years ago)
- Last Synced: 2025-01-23T11:23:48.886Z (over 1 year ago)
- Topics: module, node, testing
- Language: JavaScript
- Homepage:
- Size: 21.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Spaz's Given-When-Then
***Super simple Given-When-Then testing in Node.js***
## Install and Usage
`npm install spazmodius/gwt -D`
Example:
```js
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](https://www.npmjs.com/package/colors) package is available,
then console output will be colored appropriately.
Installing this package _does not_ automatically install [colors](https://www.npmjs.com/package/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 **given**s,
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 **given**s,
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`.