proclaim

A simple assertion library for server and client side JavaScript

Proclaim

A simple assertion library for server and client side JavaScript. Proclaim can be used with most test frameworks.

Browser Support: Android Browser 2.2–5, Edge 11, Firefox 3.6, Firefox 4–38, Google Chrome 14–43, Internet Explorer 6–11, Safari iOS 3–8.3, Safari 5–8

I've been frustrated by assertion libraries not working in all the browsers I test my code in (notably IE 6–8). Proclaim is an attempt to achieve the simplicity of Node.js assert with the extra assertions of Chai.

Proclaim implements all of the assertions in CommonJS Unit Testing 1.0 which means it works as a drop-in replacement for the Node.js assert module. It also implements most of Chai's assertions (see here for differences) so you should be able to switch quite easily.

You can use Proclaim on the server side with Node.js and npm:

$ npm install proclaim

On the client side, you can either install Proclaim through Bower/Component:

$ bower install proclaim
$ component install rowanmanning/proclaim

or by simply including proclaim.js in your page:

<script src="path/to/lib/proclaim.js"></script>

In Node.js or using Component, you can include Proclaim in your script by using require:

var proclaim = require('proclaim');
 
// Or if you prefer to use 'assert' terminology: 
var assert = require('proclaim');

Proclaim also works with AMD-style module loaders, just specify it as a dependency.

If you're just including with a <script>, proclaim is available as a global variable.

All assertions throw AssertionError if they fail.

Throw an assertion error.

proclaim.fail('foo', 'bar', 'Foo equals bar', '===');

Assert that value is truthy.

Assert that value is falsy.

Assert that actual == expected.

Assert that actual != expected.

Assert that actual === expected.

Assert that actual !== expected.

Assert that actual is deeply equal to expected.

Assert that actual is not deeply equal to expected.

Assert that fn throws an error. If expected is present then the thrown error will be tested as follows:

  • If expected is a function, assert that error intanceof expected
  • If expected is a string, assert that error.message === expected
  • If expected is a RegExp, assert that expected.test(error) === true

Assert that fn does not throw an error. If expected is present then the assertion is that an error can be thrown, but it does not pass the tests outlined in proclaim.throws.

Aliases: proclaim.notThrows

Assert that typeof actual === expected.

Aliases: proclaim.typeOf

Assert that typeof actual !== expected.

Aliases: proclaim.notTypeOf

Assert that actual instanceof expected.

Aliases: proclaim.instanceOf

Assert that !(actual instanceof expected).

Aliases: proclaim.notInstanceOf

Assert that value is an array.

Assert that value is not an array.

Assert that value is a boolean.

Assert that value is not a boolean.

Assert that value === true.

Assert that value === false.

Assert that value is a function.

Assert that value is not a function.

Assert that value === null.

Assert that value !== null.

Assert that value is a number.

Assert that value is not a number.

Assert that value is an object.

Assert that value is not an object.

Assert that value is a string.

Assert that value is not a string.

Assert that value === undefined.

Assert that value !== undefined.

Assert that actual matches the RegExp in expected.

Assert that actual does not match the RegExp in expected.

Assert that haystack contains needle. For strings and arrays, this asserts that indexOf returns a value other than -1. For objects, this method asserts that needle is the name of a property on haystack.

Assert that haystack does not contain needle. See proclaim.includes.

Aliases: proclaim.notInclude

Assert that value.length === expected.

Aliases: proclaim.lengthOf

Assert that actual < expected.

Aliases: proclaim.isBelow

Assert that actual <= expected.

Assert that actual > expected.

Aliases: proclaim.isAbove

Assert that actual >= expected.

Proclaim implements most of Chai's assertions, but is missing a few. The following Chai assertions are not present in proclaim:

  • throw - May implement, alias of throws
  • property - May implement
  • notProperty - May implement
  • deepProperty - May implement
  • notDeepProperty - May implement
  • propertyVal - May implement
  • propertyNotVal - May implement
  • deepPropertyVal - May implement
  • deepPropertyNotVal - May implement
  • operator - Unlikely to implement
  • closeTo - Unlikely to implement
  • sameMembers - May implement
  • sameDeepMembers - May implement
  • includeMembers - May implement
  • changes - Unlikely to implement
  • doesNotChange - Unlikely to implement
  • increases - Unlikely to implement
  • doesNotIncrease - Unlikely to implement
  • decreases - Unlikely to implement
  • doesNotDecrease - Unlikely to implement

If you're still using a 1.x or 2.x version of Proclaim, you're advised to upgrade to 3.x. The 1.x and 2.x branches will be maintained for the forseeable future, but it will not get any new features. You can view the 1.x source code here or view the 2.x source code here.

To contribute to Proclaim, clone this repo locally and commit your code on a separate branch.

Please write unit tests for your code, and check that everything works by running the following before opening a pull-request:

make ci

To test proclaim in-browser, just open up test/browser/test.html in-browser.

Proclaim is licensed under the MIT license.
Copyright © 2015, Rowan Manning