gabarito

gabarito

Gabarito is a javascript testing framework intended for use in both browser and node-js environments. It brings some characteristics from various xUnit tests framework as well as some ideas from YUITest framekwork.

TL;DR

Writing a test file.

// test.js

var isNode = typeof exports !== "undefined" && global.exports !== exports;
var gabarito = isNode? require("gabarito"): window.gabarito;
var assert = gabarito.assert;

var test = {

    // the test name
    name: "some test",

    // runs before every test clause
    before: function () {
    },

    // runs after every test clause
    after: function () {
    },

    // every other function property is a test clause...

    "a test clause": function () {
        assert.isTrue(true);
    },

    anotherTestClause: function () {
        assert.isFalse(false);
    },

    failingTestClause: function () {
        throw new Error("Just throw an error");
    }

};

// adds the test into gabarito
gabarito.add(test);

// tells gabarito to verify added tests
gabarito.verify();

The test runner.

// runner.js

var gabarito = require("gabarito");
var runner = new gabarito.plumbing.Runner();

// files loaded for the test to be run
runner.addFile("./test.js");

// console reporter so we see things happening on the console output
runner.addReporter(new gabarito.plumbing.ConsoleReporter());

// junit reporter so we have a nice junit-xml to integrate with our favorite CI
runner.addReporter(new gabarito.plumbing.JUnitXmlReporter("results.xml"));

// environments in which the tests will be run
runner.addEnvironment(new gabarito.plumbing.NodeEnvironment());
runner.addEnvironment(new gabarito.plumbing.PhantomEnvironment());

// run load files and environments and runs the tests
runner.run(function (results) {
    console.log(results);
});

Running.

$ node runner.js

Async testing

Gabarito passes a context object for every test. To tell gabarito to wait for an async continuation, the stay method should be called (with an optional timeout value). In order to continue the test, the go must be called. One also may use the going method which wraps the callback function calling the go method internally.

var test = {
    name: "async test",

    "an async test": function (context) {
        var callback = function (result) {
            context.go(function () {
                assert.isObject(result);
            });
        };

        doSomethingAsync(callback);
        context.stay();
    },

    "another async test": function (context) {
        var callback = context.going(function (result) {
            assert.isObject(result);
        });

        doSomethingAsync(callback);
        context.stay();
    }
};

The before and after methods also receives the context object in order to do some async preparations.

Asserts

Gabarito comes with a built-in assertion library. The full documentation can be seen on the API-Docs for assert and assert that.

// classic style
assert.areEqual("a", someVar);

// that style
assert.that(someVar).isEqualTo("a");

Spying

Gabarito also comes with a built-in spy library. It helps to verify method calls checking it's behavior and values.

var divide = gabarito.spy(function (a, b) {
    if (b === 0) {
        throw new TypeError("Cannot divide by 0");
    }

    return a / b;
});

divide(4, 2);

divide.
    verify().
    args(4, 2).
    returning(2);
// passes

divide(4, 2);

divide.
    verify()
    args(3, 1);
// throws

If you pass values to the args/returning/throwing/withThis, a value matcher will be used.

There are a few built-in matchers to be used: ANY, ANY_ARGS, ARRAY, FUNCTION, NUMBER, OBJECT

divide.
    verify().
    args(gabarito.matcher.NUMBER, gabarito.matcher.NUMBER).
    withThis(gabarito.matcher.ANY).
    returning(gabarito.matcher.NUMBER);

For custom type matchers, the type matcher may be used to check for types.

var MyType = function () {};
someMethod(new MyType());

someMethod.
    verify().
    args(gabarito.matcher.type(MyType));

If you need a custom matcher, for... whatever reason, you may build one using the matcher method.

divide.
    verify().
    args(
        gabarito.matcher(function (a) { return a === 4; }),
        gabarito.matcher(function (b) { return b === 2; }));

Varargs may be checked with the args matcher.

divide.
    verify().
    args(gabarito.matcher.args(function (args) {
        return args[0] === 4 && args[1] === 2;
    });

If you need to grab a specific value for futher use, you can use the grabber matcher. This matcher always passes.

var grabber = gabarito.matcher.grabber();

divide.
    verify().
    args(grabber, gabarito.matcher.ANY);

assert.that(grabber.grab()).isEqualTo(4);

For var args, the args grabber matcher can be used.

var grabber = gabarito.matcher.argsGrabber();

divide.
    verify().
    args(grabber);

assert.that(grabber.grab()).isEqualTo([4, 2]);