Adding renderers

Adding renderers to Tyrtle

Writing your own renderer for Tyrtle is dead easy.

The main part of it comes down to a few easy hooks:

• beforeRun, afterRun - executed before/after the entire run. Passed a reference to the Tyrtle instance.
• beforeModule, afterModule - executed before/after each module. Passed reference to the module and Tyrtle instance.
• beforeTest, afterTest - executed before/after each test. Passed a reference to the test, the module and Tyrtle instance.

Each of these is completely optional. If no hook is provided, then simply nothing will run at that time. Once you have a renderer, it can be applied by using Tyrtle.setRenderer (a static method on the class itself).

To help you write some useful output, the basic interface of the objects is this:

• Tyrtle
  • passes, the number of tests which have passed.
  • fails, the number of tests which have failed.
  • skips, the number of tests which have been skipped.
  • modules, an array of modules in this instance.
• Module
  • name, the name of this module
  • passes, fails, skips, as above, but only counting tests in this module.
  • tests, an array of tests in this module.
• Test
  • name, the name of this test
  • status, one of Tyrtle.PASS, Tyrtle.FAIL, Tyrtle.SKIP or null (meaning that the test has not yet run).
  • statusMessage, a string containing the message (eg: "Passed", "Failed: 4 does not equal 5").
  • runTime, execution time of this passing test in milliseconds. If this test failed, has been skipped or has not been run yet, this will be -1.
  • error, if this test failed because of an error (not a failed assertion), the error thrown is stored here.
  • exception, if this test failed because of a failed assertion, the AssertionError is stored here.

Example

Tyrtle.setRenderer({
    beforeModule : function (module, tyrtle) {
        console.log("--- " + module.name + " ---");
    },
    afterTest : function (test, module, tyrtle) {
        console.log(
            test.name + ": " + test.statusMessage
        );
    },
    afterRun : function (tyrtle) {
        console.log(tyrtle.passes + " out of " + (tyrtle.passes + tyrtle.fails + tyrtle.skips) + " passed.");
    },
});

Example output:

--- My first module ---
Some test: Passed
Some other test: Failed: 3 is not greater than 4
--- My second module ---
This test: Passed
2 out of 3 passed.

Advanced usage

Tyrtle renderers also are given the job of performing the variable substitution from failed assertions. This means that a renderer is able to add specific markup or formatting depending on the type of variable and the target environment.

For example, the packaged Node renderer adds special ANSI escape codes to perform basic syntax highlighting to help distinguish between, for example, 3 (a number) and '3' (a string). The packaged HTML renderer wraps some variable output in tags, adding event listeners to allow for console debugging even after the test has finished execution.

To override the default implementation, define a method on your renderer called templateString. This will be called with a string as the first argument, and then any number of further arguments, representing variables which could be substituted into the string.

The templating format is an opening bracket followed by a number and then a closing bracket. eg: {0} {1} {2}. The number corresponds to the variable arguments passed to templateString.

templateString must return a string.

The default implementation looks like this:

templateString = function (message) {
    var args = [].slice.call(arguments, 1);
    return message.replace(
        /\{([1-9][0-9]*|0)\}/g,
        function (str, p1) { // eg: str = "{3}", p1 = "3"
            var v = args[p1];
            return (v === null
                ? "NULL"
                : (typeof v === "undefined"
                   ? "UNDEFINED"
                   : (v.toString ? v.toString() : String(v))
                )
            );
        }
    );
}