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

const proclaim = require('proclaim');
proclaim.equal(true, false); // throws

• Install
• Usage
• Assertions
• Why?
• Differences Between Proclaim And Chai
• Contributing
• Support and Migration
• License

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 actual is deeply equal to expected, as determined by the strict equality operator ===.

Assert that actual is not deeply equal to expected, as determined by the strict not equal operator !==.

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 instanceof expected
• If expected is a string, assert that error.message === expected
• If expected is a RegExp, assert that expected.test(error) === true
• If expected is a function which error is not an instance of, assert that expected.call({}, 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 is NaN.

Assert that value is not NaN.

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.include.

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.

Assert that fn.length === expected.

Assert that Math.abs(actual - expected) < (0.5 * Math.pow(10, -precision)).

Assert that obj[property] is not enumerable.

Assert that obj[property] is enumerable.

Assert that fn.name === expected.

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.

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

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.

Browsers Proclaim currently supports: 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. We use Sauce Labs to automatically test against these browsers, however we're having issues with tunneling. You can view a browser support matrix here.

Proclaim major versions are normally supported for 6 months after their last minor release. This means that patch-level changes will be added and bugs will be fixed. The table below outlines the end-of-support dates for major versions, and the last minor release for that version.

If you're opening issues related to these, please mention the version that the issue relates to.

Proclaim is licensed under the MIT license.

Copyright © 2015, Rowan Manning