Bedrock
, /\.__ _.-\
/~\, __ /~ \ ./ \
,/ /_\ _/ \ ,/~,_.~'"\ /_\_ /'\
/ \ /## \ / V#\/\ /~8# # ## V8 #\/8 8\
/~#'#"#""##V&#&# ##\/88#"#8# #" #\#&"##" ##\
j# ##### #"#\&&"####/###& #"#&## #&" #"#&#"#'\
/#"#"#####"###'\&##"/&#"####"### # #&#&##"#"### \
J#"###"#"#"#"####'\# #"##"#"##"#"#####&"## "#"&"##|\
Bedrock is a javascript BDD / TDD unit testing framework for Node.js.
It comprises a CLI test runner/reporter, assertion library and utilities including stubs and spies.
Installation
'bed-rock' is available as an npm package:
$ npm install bed-rock --save-dev
Add the following to scripts in package.json (with optional configuration flags):
'test' : 'bed-rock'
Run tests:
npm test
Bedrock will automatically load any files that match '*.spec.js'. This can be changed by passing a custom pattern (see configuration)
Configuration
Bedrock accepts several flags on startup. Note that bed-rock will need to be restarted if running in watch mode, if any of these flags are changed.
Set your test file extention (default spec)
--ext='my-test-ext'
Enable watch mode; Bedrock will automatically reload on file changes
--watch
Disable create of global window and document (DOM) objects
--nodom
Disable printing of the failure summary details
--nosumm
Usage
Bedrock exposes several core functions for composing tests:
context(description: string, tests: function)
a container for one or more tests (can be nested with other contexts)
test(description: string, assertions: function)
a container for a single test. Can contain one or more assertions. A spec whose expectations all succeed will be passing and a spec with any failures will fail
expect(subject: any)
creates an assertion for a test
expect(subject: any).not
creates an assertion for a test and reversed the evaluation logic
xcontext(description: string, tests: function)
a container for one or more tests (can be nested with other contexts) which will be ignored. NOTE: this overrides any nested focused tests (ftest) defined inside the context
xtest(description: string, assertions: function)
a container for a single test which will be ignored
ftest(description: string, assertions: function)
a container for a single test which will be focused. The presence of a single focused tests will cause any unfocused tests to be ignored.
spy(target: any, functionName: string)
a wrapper to spy on or stub an existing function or property of an object. See Spies & Stubs for more details
Basic example test file
var context = context; var test = test; var expect = expect; /* es6 importimport { context, test, expect } from 'bed-rock;*/ ;
Comprehensive example usage of all matchers can be found in 'example-matchers.js' in the root directory. Note that exactly half of these example tests fail; this is deliberate and designed to show how each matcher can be set-up to both pass and fail.
Hooks
These must be declared before any tests in a context. Prefer variable assignment and function calls within these hooks rather.
setup(function)
runs once before all tests in a context
setupEach(function)
runs before each test in a context
teardown(function)
runs once after all tests in a context
tearDownEach(function)
runs after each test in a context
Matchers
toBe(value: any)
subject and value are equal using '==='
toEqual(value: any)
subject and value are deeply equal
toBeDefined()
subject is defined
toBeUndefined()
subject is undefined
toBeNull()
subject is null
toBeNotNull()
subject is not null
toBeGreaterThan(target: number)
subject is greater than a target
toBeLessThan(target: number)
subject is less than a target
toBeGreaterThanOrEqualTo(target: number)
subject is greater than or equal to a target
toBeLessThanOrEqualTo(target: number)
subject is less than or equal to a target
toBeBetweenInclusive(minimumThreshold: number, maximumThreshold: number)
subject is between the minimumThreshold and maximumThreshold including these boundaries
toBeBetweenExclusive(minimumThreshold: number, maximumThreshold: number)
subject is between the minimumThreshold and maximumThreshold excluding these boundaries
toBeCloseToInclusive(target: number, delta: number)
subject is within the delta of the target, including boundaries
toBeCloseToExclusive(target: number, delta: number)
subject is within the delta of the target, excluding boundaries
toBeTypeOf(name: string)
subject is of type name
toRespondTo(name: string)
subject has property or function of name
toHaveLength(length: number)
subject (Array, Map, Set or String) has length
toHaveKey(key: any)
subject (Map or Object) contains key
toContain(item: any)
subject (Array, Set, Map, String) contains the item
toBeFalsey()
subject evaluates to false in a boolean context
toBeTruthy()
subject evaluates to true in a boolean context
toBeStringContaining(text: string, caseSensitive: boolean)
subject (string) contains text with optional case sensitivity (default false)
toBeStringMatching(regexPattern: RegEx)
subject (string) matches the regexPatern
toThrow(message: string)
subject throws message. NOTE: function should be passed by name, NOT executed e.g. expect(myThrowingFunction).toThrow('My error Message'); To pass arguments to a function that is expected to throw, use the with() function.
toThrowError(errorType: any, errorMessage: string)
subject throws an error of errorType with errorMessage. NOTE: function should be passed by name, NOT executed e.g. expect(myThrowingFunction).toThrow('My error Message'); To pass arguments to a function that is expected to throw an error, use the with() function.
with(arguments: any)
pass arguments to a function that is expected toThrow or toThrowError. The call to with() should come immediately following the expectation containing the function name e.g. expect(myThrowingFunction).with(1).toThrow('My error Message');
toHaveBeenCalled(callCount: Number)
subject (Spy) was called callCount times
toHaveBeenCalledWith(...args: [])
subject's (Spy) call history contains at least one call with specified args
toHaveBeenCalledWithFirst(...args: [])
subject's (Spy) first call arguments equal specified args
toHaveBeenCalledWithLast(...args: [])
subject's (Spy) last call arguments equal specified args
Spies and Stubs
Bedrock combines the notion of spies and stubs:
spy(target: any, functionName: string)
a wrapper to spy on or stub an existing function or property of an object
andReturn(value: any)
stubs the spy target's attribute to return the value
andFake(function: Function)
stubs the spy target's attribute to call the function
reset()
resets a spy, cleaing the call cound and call history
restore()
restores the spy target's original function call or value
getCallCount()
returns the spy's call count. Prefer toHaveBeenCalled() matcher
getCallHistory()
returns an array of the spy's call history. Prefer toHaveBeenCalledWith() matcher
## Future development
- Async matchers (promise resolution)