Checks a given object against a given set of specifications to keep you from writing boilerplate tests.
Checks a given object against a given set of specifications to keep you from writing boilerplate tests.
const test = require('node:test')
// or: const test = require('tape')
// or: const test = require('tap')
const spok = require('spok')
// this would be returned from a function you are testing
const object = {
one : 1
, two : 2
, three : 3
, four : 4
, helloWorld : 'hello world'
, anyNum : 999
, anotherNum : 888
, anArray : [ 1, 2 ]
, anotherArray : [ 1, 2, 3 ]
, anObject : {}
}
// custom specification
function hasThreeElements(a) {
return a.length === 3
}
test('my object meets the specifications', (t) => {
spok(t, object, {
$topic : 'spok-example'
, one : spok.ge(1)
, two : 2
, three : spok.range(2, 4)
, four : spok.lt(5)
, helloWorld : spok.startsWith('hello')
, anyNum : spok.type('number')
, anotherNum : spok.number
, anArray : spok.array
, anotherArray : hasThreeElements
, anObject : spok.ne(undefined)
})
})
npm install spok
Since Node.js 16.x it includes a built-in test runner.
Spok support this out of the box as follows:
assert module to assert the valuest: TestContext to print diagnostic messages that detail the assertions
madSee ./example/node-test.js and ./example/node-test-nested.jsfor a full examples.
spok detects if colors should be used in the output in order to avoid breaking TAP compatibility when needed as follows:
FORCE_COLOR env var is set to 1|true colors are ALWAYSNO_COLOR env var is set to 1|true colors are NEVER usednode --test mytest.js and FORCE_COLOR is not set then colorse are disablednode mytest.js and NO_COLOR is not set then colors are enabledt which mirrors the assert module and also prints results and the
diagnostics message to the console, thus spok uses t to perform assertionsSee ./example/tape.js and ./example/tape-nested.jsfor a full examples.
Spok can be used out of the box with expect, for instance when running tests with
cypress.io.
Simply create a custom assert function and pass it to spok. The main difference to running
tests with tape is that if a single property in the compared object doesn't match the test
fails immediately.
import spok from 'spok'
const t = spok.adapters.chaiExpect(expect)
spok(t, meta, {
err: null,
fee: 5000,
status: {
Ok: null,
},
})
spok(t, meta, {
err: null,
fee: 4000,
status: {
Ok: null,
},
})
deepEqual?deepEqual works great for most cases, but in some cases you need more control, i.e.
By default spok prints the specification that a particular assertion satisified, i.e. satisfies: spok.range(2, 4).
You can turn that off via spok.printSpec = false.
On the other hand if you want more details about the satisified spec do spok.printDescription = true instead to get
spok to print things like satisfies: spok.range(2, 4) 2 <= value <= 4.
Specs and descriptions are printed in gray so you can focus on the actual values of the test output.
Table of Contents generated with DocToc
spok provides a few common specification functions. However you can write your own functions as well, just return true
if specification was satisfied and false if not (see example above).
If you write a specification function that would be useful to others please add it along with a test and provide a PR.
spok.* comparison function names are derived from bash comparison
operators to make them easier to remember.
Checks the given specifications against the object.
When the tests are run the actual values are printed to verify visually while each provided specification is validated and a test failure caused if one of them fails.
Parameters
t Object which has assertion functions equal and deepEqual (to compare objects) - use
tap, tape, assert, Node.js TestContext or any other library that has those and thus is compatibleobj Object the object to verify the specifications againstspecifications Object the specifications to verifyVersion of spok that is less strict about the relation of the
specification type, namely it allows overriding the type manually or
derives it from the supplied parameter.
Use ONLY when you cannot adjust the types, so plain spok works.
Specififies that the given number is within the given range, i.e. min<= x <=max.
var spec = {
x: spok.range(1, 2) // specifies that x should be >=1 and <=2
}
Parameters
Specififies that a number is greater than the given criteria.
var spec = {
x: spok.gt(1) // specifies that x should be >1
}
Parameters
n Number criteriaSpecififies that a number is greater or equal the given criteria.
var spec = {
x: spok.ge(1) // specifies that x should be >=1
}
Parameters
n Number criteriaSpecififies that a number is less than the given criteria.
var spec = {
x: spok.lt(1) // specifies that x should be < 1
}
Parameters
n Number criteriaSpecififies that a number is less or equal the given criteria.
var spec = {
x: spok.le(1) // specifies that x should be <=1
}
Parameters
n Number criteriaSpecifies that the value is not equal another.
var spec = {
x: spok.ne(undefined) // specifies that x should be defined
}
Parameters
value Any criteriaSpecifies that the value is greater than zero
var spec = {
x: spok.gtz
}
Specifies that the value is greater or equal zero
var spec = {
x: spok.gez
}
Specifies that the value is less than zero
var spec = {
x: spok.ltz
}
Specifies that the value is less or equal zero
var spec = {
x: spok.lez
}
Specifies that the input is of a given type.
var spec = {
x: spok.type('number') // specifies that x should be a Number
}
Parameters
t String expected typeSpecifies that the input is an array.
var spec = {
x: spok.array // specifies that x should be an Array
}
Specifies that the input is an array with a specific number of elements
var spec = { x: spok.arrayElements(2) // specifies that x should be an Array with 2 elements }
Parameters
n Number number of elementsSpecifies that the input is an array with a number of elements in a given range
var spec = { x: spok.arrayElementsRange(2, 4) // specifies that x should be an Array with 2-4 elements }
Parameters
Specifies that the input of type number and isNaN(x) returns false.
var spec = {
x: spok.number // specifies that x should be a Number
}
Specifies that the input is a string.
var spec = {
x: spok.string // specifies that x should be a String
}
Specifies that the input is a function.
var spec = {
x: spok.function // specifies that x should be a function
}
Specifies that the input is an object and it is not null.
var spec = {
x: spok.definedObject // specifies that x is a non-null object
}
Specifies that the string starts with the specified substring.
NOTE: only available with node.js which has an ES6 startsWith function
var spec = {
x: spok.startsWith('hello') // specifies that x should start with 'hello'
}
Parameters
what String substring the given string should start withSpecifies that the string ends with the specified substring.
NOTE: only available with node.js which has an ES6 endsWith function
var spec = {
x: spok.endsWith('hello') // specifies that x should start with 'hello'
}
Parameters
what String substring the given string should start withSpecifies that the string needs to match the given regular expression.
var spec = {
x: spok.test(/hello$/) // specifies that x should match /hello$/
}
Parameters
regex RegExp regular expression against which the string is checked via testSpecifies that a value is defined, i.e. it is neither null nor undefined.
var spec = {
x: spok.defined
}
Specifies that a value is notDefined, i.e. it is either null or notDefined.
var spec = {
x: spok.notDefined
}
MIT
FAQs
Checks a given object against a given set of specifications to keep you from writing boilerplate tests.
The npm package spok receives a total of 16,974 weekly downloads. As such, spok popularity was classified as popular.
We found that spok demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.