Chakram

Module: chakram

chakram

Chakram Module

Example

var chakram = require("chakram");

Members

staticmodule:chakram.addSchema

Exposes tv4's add schema method. Allows the registration of schemas used for schema validation.
Example
chakram.addSchema('http://example.com/schema', { ... });

staticmodule:chakram.addSchemaFormat

Exposes tv4's add format method. Allows add custom format for schema validation.
Example
chakram.addSchemaFormat('decimal-digits', function (data, schema) {
    if (typeof data === 'string' && !/^[0-9]+$/.test(data)) {
        return null;
    }
    return "must be string of decimal digits";
});

staticmodule:chakram.getSchemaMap

Exposes tv4's get schemaMap method. Allows to check the mapping schema object.
Example
chakram.getSchemaMap();

staticmodule:chakram.schemaBanUnknown

Option for turning on tv4's "ban unknown properties" mode.
Example
chakram.schemaBanUnknown = true;

staticmodule:chakram.schemaCyclicCheck

Option for turning on tv4's option to check for self-referencing objects.
Example
chakram.schemaCyclicCheck = true;

Methods

staticmodule:chakram.addMethod(name, plugin)

plugins.js, line 118
Add a new method assertion to Chakram. Methods should be used when the assertion requires parameters.
Name Type Description
name String The plugin's name, used as an identifier
plugin function A function which should accept one or more arguments. The first argument will be a ChakramResponse object, followed by any arguments passed into the assertion.
Example
chakram.addMethod("statusRange", function (respObj, low, high) {
    var inRange = respObj.response.statusCode >= low && respObj.response.statusCode <= high;
    this.assert(inRange, 'expected '+respObj.response.statusCode+' to be between '+low+' and '+high, 'expected '+respObj.response.statusCode+' not to be between '+low+' and '+high);
});
var twohundred = chakram.get("http://httpbin.org/status/200");
return expect(twohundred).to.have.statusRange(0, 200);

staticmodule:chakram.addProperty(name, plugin)

plugins.js, line 97
Add a new property assertion to Chakram. Properties should be used over methods when there is no arguments required for the assertion.
Name Type Description
name String The plugin's name, used as an identifier
plugin function A function which should accept one argument; a ChakramResponse object
Example
chakram.addProperty("httpbin", function (respObj) {
    var hostMatches = /httpbin.org/.test(respObj.url);
    this.assert(hostMatches, 
        'expected '+respObj.url+' to contain httpbin.org', 
        'expected '+respObj.url+' to not contain httpbin.org');
});
var httpbin = chakram.get("http://httpbin.org/status/200");
return expect(httpbin).to.be.at.httpbin;

staticmodule:chakram.addRawPlugin(name, plugin)

plugins.js, line 77
Add a raw chai plugin to Chakram. See Chai's documentation for more details.
Name Type Description
name String The plugin's name, used as an identifier
plugin function A Chai plugin function, function should accept two arguments, the chai object and the chai utils object
Example
chakram.addRawPlugin("unavailable", function (chai, utils) {
    utils.addProperty(chai.Assertion.prototype, 'unavailable', function () {
        var statusCode = this._obj.response.statusCode;
        this.assert(statusCode === 503, 
            'expected status code '+statusCode+' to equal 503', 
            'expected '+statusCode+' to not be equal to 503');
    });
});
var unavailableReq = chakram.get("http://httpbin.org/status/503");
return expect(unavailableReq).to.be.unavailable;

staticmodule:chakram.all(promiseArray){Promise}

chakram.js, line 59
Returns a promise which is fulfilled once all promises in the provided array are fulfilled. Identical to Q.all.
Name Type Description
promiseArray Array.<Promise> An array of promises to wait for
Returns:
Type Description
Promise

staticmodule:chakram.clearRequestDefaults()

methods.js, line 184
Clears any previously set default options.

staticmodule:chakram.del(url, data, params){Promise}

methods.js, line 166
Alias for chakram.delete. Perform HTTP DELETE request.
Name Type Description
url string fully qualified url
data Object optional a JSON serializable object (unless json is set to false in params, in which case this should be a buffer or string)
params Object optional additional request options, see the popular request library for options
Returns:
Type Description
Promise Promise which will resolve to a ChakramResponse object

staticmodule:chakram.delete(url, data, params){Promise}

methods.js, line 153
Perform HTTP DELETE request
Name Type Description
url string fully qualified url
data Object optional a JSON serializable object (unless json is set to false in params, in which case this should be a buffer or string)
params Object optional additional request options, see the popular request library for options
Returns:
Type Description
Promise Promise which will resolve to a ChakramResponse object

staticmodule:chakram.expect(value, message){chakram-expectation}

chakram.js, line 38
Chakram assertion constructor. Extends chai's extend method with Chakram's HTTP assertions. Please see chai's API documentation for details on the default chai assertions and the ChakramExpectation documentation for the Chakram HTTP assertions.
Name Type Description
value * The variable to run assertions on, can be a ChakramResponse promise
message string A custom assertion message passed to Chai
Returns:
Type Description
chakram-expectation A Chakram expectation object
Example
var expect = chakram.expect;
it("should support chakram and chai assertions", function () {
    var google = chakram.get("http://google.com");
    expect(true).to.be.true;
    expect(google).to.have.status(200);
    expect(1).to.be.below(10);
    expect("teststring").to.be.a('string');
    return chakram.wait();
});

staticmodule:chakram.get(url, params){Promise}

methods.js, line 77
Perform HTTP GET request
Name Type Description
url string fully qualified url
params Object optional additional request options, see the popular request library for options
Returns:
Type Description
Promise Promise which will resolve to a ChakramResponse object

staticmodule:chakram.head(url, params){Promise}

methods.js, line 88
Perform HTTP HEAD request
Name Type Description
url string fully qualified url
params Object optional additional request options, see the popular request library for options
Returns:
Type Description
Promise Promise which will resolve to a ChakramResponse object

staticmodule:chakram.initialize(customChaiPlugin)

plugins.js, line 45
Initialise the chakram package with custom chai plugins. This is no longer recommended, instead use either addMethod, addProperty or addRawPlugin.
Name Type Description
customChaiPlugin ChaiPlugin repeatable One or multiple chai plugins
Deprecated
  • since 0.2.0
    Example
    var customProperty = function (chai, utils) {
    utils.addProperty(chai.Assertion.prototype, 'teapot', function () {
        var statusCode = this._obj.response.statusCode;
        this.assert(
            statusCode === 418, 
            'expected status code '+statusCode+' to equal 418', 
            'expected '+statusCode+' to not be equal to 418'
        );
    });
};
chakram.initialise(customProperty);

    staticmodule:chakram.options(url, params){Promise}

    methods.js, line 99
    Perform HTTP OPTIONS request
    Name Type Description
    url string fully qualified url
    params Object optional additional request options, see the popular request library for options
    Returns:
    Type Description
    Promise Promise which will resolve to a ChakramResponse object

    staticmodule:chakram.patch(url, data, params){Promise}

    methods.js, line 128
    Perform HTTP PATCH request
    Name Type Description
    url string fully qualified url
    data Object a JSON serializable object (unless json is set to false in params, in which case this should be a buffer or string)
    params Object optional additional request options, see the popular request library for options
    Returns:
    Type Description
    Promise Promise which will resolve to a ChakramResponse object

    staticmodule:chakram.post(url, data, params){Promise}

    methods.js, line 116
    Perform HTTP POST request
    Name Type Description
    url string fully qualified url
    data Object a JSON serializable object (unless json is set to false in params, in which case this should be a buffer or string)
    params Object optional additional request options, see the popular request library for options
    Returns:
    Type Description
    Promise Promise which will resolve to a ChakramResponse object

    staticmodule:chakram.put(url, data, params){Promise}

    methods.js, line 141
    Perform HTTP PUT request
    Name Type Description
    url string fully qualified url
    data Object a JSON serializable object (unless json is set to false in params, in which case this should be a buffer or string)
    params Object optional additional request options, see the popular request library for options
    Returns:
    Type Description
    Promise Promise which will resolve to a ChakramResponse object

    staticmodule:chakram.request(method, url, params){Promise}

    methods.js, line 24
    Perform HTTP request
    Name Type Description
    method string the HTTP method to use
    url string fully qualified url
    params Object optional additional request options, see the popular request library for options
    Returns:
    Type Description
    Promise Promise which will resolve to a ChakramResponse object
    Example
    var request = chakram.request("GET", "http://httpbin.org/get", {
    'auth': {'user': 'username','pass': 'password'}
});
expect(request).to.have.status(200);

    staticmodule:chakram.setRequestDefaults(defaults)

    methods.js, line 175
    Sets the default options applied to all future requests.
    Name Type Description
    defaults Object optional default request options, see the popular request library for options

    staticmodule:chakram.startDebug(debugFn)

    debug.js, line 28
    Actvates debugging. By default, will print request and response details to the console. Custom debugging functions can be specified.
    Name Type Description
    debugFn function A debug function which replaces the default log to console. Details of parameters can be found at https://github.com/request/request-debug.

    staticmodule:chakram.stopDebug()

    debug.js, line 15
    Deactivates debugging

    staticmodule:chakram.wait(){Promise}

    chakram.js, line 97
    Returns a promise which is fulfilled once all chakram expectations are fulfilled. This works by recording all chakram expectations called within an 'it' and waits for all the expectations to finish before resolving the returned promise.
    Returns:
    Type Description
    Promise
    Example
    it("should support auto waiting for tests", function() {
    var response = chakram.get("http://httpbin.org/get");
    expect(response).to.have.status(200);
    expect(response).not.to.have.status(404);
    return chakram.wait();
});

    staticmodule:chakram.waitFor(promiseArray){Promise}

    chakram.js, line 76
    Returns a promise which is fulfilled once all promises in the provided array are fulfilled. Similar to Q.all, however, instead of being fulfilled with an array containing the fulfillment value of each promise, it is fulfilled with the fulfillment value of the last promise in the provided array. This allows chaining of HTTP calls.
    Name Type Description
    promiseArray Array.<Promise> An array of promises to wait for
    Returns:
    Type Description
    Promise
    Example
    it("should support grouping multiple tests", function () {
    var response = chakram.get("http://httpbin.org/get");
    return chakram.waitFor([
        expect(response).to.have.status(200),
        expect(response).not.to.have.status(404)
    ]);
});