balefrost/promises-tests

Compliances tests for Promises/A+

Promises/A+ Compliance Test Suite

This suite tests compliance of a promise implementation with the Promises/A+ specification.

How To Run

The tests run in a Node.js environment; make sure you have that installed.

Adapters

In order to test your promise library, you must expose a very minimal adapter interface. These are written as Node.js modules with a few well-known exports:

• fulfilled(value): creates a promise that is already fulfilled with value.
• rejected(reason): creates a promise that is already rejected with reason.
• pending(): creates a tuple consisting of { promise, fulfill, reject }:
  • promise is a promise object that is currently in the pending state.
  • fulfill(value) moves the promise from the pending state to a fulfilled state, with fulfillment value value.
  • reject(reason) moves the promise from the pending state to the rejected state, with rejection reason reason.

The fulfilled and rejected exports are actually optional, and will be automatically created by the test runner using pending if they are not present. But, if your promise library has the capability to create already-fulfilled or already-rejected promises, then you should include these exports, so that the test runner can provide you with better code coverage and uncover any bugs in those methods.

From the CLI

This package comes with a command-line interface that can be used either by installing it globally with npm install promises-aplus-tests -g or by including it in your package.json's devDependencies and using npm's scripts feature. In the latter case, your setup might look something like

{
    "devDependencies": {
        "promises-aplus-tests": "*"
    },
    "scripts": {
        "test": "run-my-own-tests && promises-aplus-tests test/my-adapter"
    }
}

The CLI takes as its single argument the filename of your adapter file, relative to the current working directory.

Programmatically

The main export of this package is a function that allows you to run the tests against an adapter:

var promisesAplusTests = require("promises-aplus-tests");

promisesAplusTests(adapter, function (err) {
    // All done; output is in the console. Or check `err` for number of failures.
});