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 = 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)