README.md

xassert - Extensible Assertions

Homepage

Just another assertion library inspired by Chai Assertion Library and Java Hamcrest with interesting features:

• Extensible
• No dependencies
• No complex property chains (e.g. is.not.equal)
• No property terminators (e.g. is.true) that could deliver false positives on a typographic error.
• Promises support
• Property assertion chaining
• Reusable assertions
• Meaningfully error messages (e.g. 'actual value did not match the given regular expression: /^abc$/')

Install

npm install xassert --save-dev
# or
npm install xassert

Usage

A simple example

const assert = require('xassert')
const result = 'banana'
assert(result).isEqualTo('banana')

Chaining

const assert = require('xassert')

assert(obj)
  .includesOwnProperty('id', it => it.matches(/[a-z0-9]{9}/)).andIt
  .includesOwnProperty('name', it => it.isEqualTo('john'))

Extensible

// CommonJS
const assert = require('xassert')
const { Assertion, AssertionError } = assert
// Or
import assert, { Assertion, AssertionError } from xassert

const banana = 'I am a banana!'
const apple = 'I am an apple'
// Add a new method
Assertion.prototype.isABanana = function isABanana () {
  if (this.actual !== banana) throw this.fire('{name} is not a banana', banana)
  return this
}

assert(banana).isABanana()
assert(() => assert(apple).isABanana()).throwsAn(AssertionError)

Reusable assertions

    const assert = require('xassert')
    // Reusable assertions on properties
    // Note that `assert.fn` is only a helper function for auto-completion in some IDE
    const isANumber = assert.fn(it => it.isANumber())
    const areNumbers = assert.fn(it => it.every(isANumber))
    const isString = assert.fn(it => it.isAString())
    const areStrings = assert.fn(it => it.every(isString))

    // Assertion on "things"
    const things = { colors: ['red', 'blue', 'yellow'], numbers: [1, 2] }
    assert(things)
      .named('things')
      .includesOwnProperty('numbers', areNumbers)
      .includesOwnProperty('colors', areStrings)

    // Even the whole assertion
    const areThings = assert.fn(it => it.named('things')
      .includesOwnProperty('numbers', areNumbers)
      .includesOwnProperty('colors', areStrings))

    areThings(assert(things))