Result Cache

Save, log, retrieve, and share the results of plugin tests.

Synopsis

Potential reasons to use the result cache in your plugin:

To have plugin results appear in watch output, in your web browser.
To store results and emit log entries in one line of code.
To do all your plugins processing, have the results stored for you and then emit a single LOGINFO message to summarize the results.

Towards those goals, ResultCache provides some help. Here's how:

Each call to the result cache logs the call if emit is true. In the simple cases, call result_cache as many times as necessary. When finished, call result_cache with emit: true and a summary of the results will be logged.
Each call to result_cache logs a summary when loglevel is DEBUG or PROTOCOL.
At any time, summary results can be fetched with collate.
The hide option can suppress unwanted results from the summary.
The order of display can be set with the order value.

Usage

Use this plugin in yours:

exports.my_first_hook = function(next, connection) {
    var plugin = this;

    // run a test
    ......

    // store the results
    connection.result_cache.save(plugin, {pass: 'my great test' });

    // run another test
    .....

    // store the results
    connection.result_cache.save(plugin, {fail: 'gotcha!', msg: 'show this'});
}

Store the results in the transaction (vs connection):

    connection.transaction.result_cache.save(plugin, {...});

Don't show skip messages

    ;put this in config/result_cache.ini
    [plugin_name]
    hide=skip

Result Cache Functions

save

Store some information. Most calls to result_cache will append data to the lists in the connection. The following lists are available:

pass  - names of tests that passed
fail  - names of tests that failed
skip  - names of tests that were skipped (with a why, if you wish)
err   - error messages encountered during processing
msg   - arbitratry messages

human - a custom summary to return (bypass collate)
emit  - log an INFO summary

Examples:

result_cache.save(plugin, {pass: 'null_sender'});
result_cache.save(plugin, {fail: 'single_recipient'});
result_cache.save(plugin, {skip: 'valid_bounce'};
result_cache.save(plugin, {err: 'timed out looking in couch cushions'});
result_cache.save(plugin, {msg: 'I found a nickel!', emit: true});

In addition to appending values to the predefined lists, arbitrary results can be stored in the cache:

result_cache.save(plugin, {my_result: 'anything I want'});

When arbirary values are stored, they are listed first in the log output. Their display can be suppressed with the hide option to save or init.

collate

var summary = result_cache.collate(plugin);

Formats the contents of the result cache and returns them. This function is called internally by save after each update.