# Bedrock [](https://travis-ci.org/joemaidman/bedrock)
[](https://npmjs.org/package/bed-rock)
```
, /\.__ _.-\
/~\, __ /~ \ ./ \
,/ /_\ _/ \ ,/~,_.~'"\ /_\_ /'\
/ \ /## \ / 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](https://www.npmjs.com/package/bed-rock):
$ 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))
## 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](#spies-and-stubs) for more details
## Basic example test file
```js
var context = require('bed-rock').context;
var test = require('bed-rock').test;
var expect = require('bed-rock').expect;
/* es6 import
import { context, test, expect } from 'bed-rock;
*/
context("GIVEN the state of the world", () => {
let myTestSubject = 1;
context("WHEN some action(s) have been performed")
test('THEN I expect this outcome',() =>{
expect(myTestSubject).toEqual(1);
});
});
```
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)