api-grandma-run.md

API: Running tests

Table of Contents

grandma.run({Object} options, {Function} callback) → {Object} task

The run command takes an options object and a callback. It will trigger a test to start.

options:

The following options are available for running a test:

• duration {string|number} - the amount of time that the test should run for. This is the minimum amount of time that grandma will continue starting new tests. However, the actual full run might be longer, if tests take a while to finish. This can be one of the following:
  • The number 0, which specifies that the tests should run indefinitely, without a time limit
  • A number in milliseconds
  • A string written as any combinartion of a number an ending of:
    • ms (milliseconds)
    • s (seconds)
    • m (minutes)
    • h (hours)
    • d (days)
    • w (weeks)
  • Example: '1h30m26s'
• rate {number} - the rate at which to start a new test, as a number per second. For example, 5 would indicate 5 tests runs per second. This value is not compatible with concurrent.
• concurrent {number} - the number of tests to run at once. When this value is used, a set amount of tests will start immediately, and when any test finished, it will be replaced with a new one. If rate is defined, this value will be ignored, and instead, the tests will run according to the rate value.
• timeout {string|number} - the amount of time to wait for each test before failing the test. The default is to wait indefinitely. This is set to a value similarly to duration. When a test times out, it will be reported as a failure with an errorCode of -1.
• threads {number} - the number of thread workers to run the tests in. This property is optional and defaults to 1. There is usually no reason to set it higher than that.
• output {stream} - a stream to write report data to. This can be any writable stream, such as a file stream, or a stream-like object, like a through stream.
• test {object} - an object defining the test to run. It has the following properties:
  • path {string} - a string path to the JavaScript file defining the test.
  • name {string} - the name of the test. This value can be set to any string.

callback:

A function. It takes a single parameter, error. If error is present, the test did not complete successfully. The error object will contain details as to what happened. If it is falsy, the test completed successfully and the results are ready to use.

Sample code:

Example that runs 20 tests per second for 5 minutes:

var fs = require('fs');
var path = require('path');
var grandma = require('grandma');

var output = fs.createWriteStream('path/to/report.log');

var options = {
    duration: '5m',
    rate: 20,
    output: output,
    test: {
        path: path.resolve('path/to/mytest.js'),
        name: 'mytest'
    }
};

function done(err) {
    if (err) {
        return console.error('something went wrong', err);
    }
    
    console.log('done!');
}

grandma.run(options, done);

Example that runs 10 concurrent tests for 1 day (24 hours):

var fs = require('fs');
var path = require('path');
var grandma = require('grandma');

var output = fs.createWriteStream('path/to/report.log');

var options = {
    duration: '1d',
    concurrent: 10,
    output: output,
    test: {
        path: path.resolve('path/to/mytest.js'),
        name: 'mytest'
    }
};

function done(err) {
    if (err) {
        return console.error('something went wrong', err);
    }
    
    console.log('done!');
}

grandma.run(options, done);