Usage

`javascript
var bench = require( '@stdlib/bench-harness' );
`

#### bench( name\[, options]\[, benchmark] )

Queues a benchmark to be run during a subsequent turn of the event loop. After running the benchmark, the function outputs benchmark results as Test Anything Protocol ([TAP][tap]) output.

`javascript
bench( 'Math.sin', function benchmark( b ) {
var x;
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
x = Math.sin( Math.random() );
if ( x !== x ) {
b.fail( 'should not return NaN' );
}
}
b.toc();
if ( x !== x ) {
b.fail( 'should not return NaN' );
}
b.pass( 'benchmark finished' );
b.end();
});
`

A benchmark function has the following signature:

`javascript
function benchmark( b ) {
// Benchmark code...
}
`

where b is a Benchmark instance. Synchronous benchmarks should, at minimum, have the following structure:

`javascript
function benchmark( b ) {
var x;
var i;

// [1] Start timing:
b.tic();

// [2] Loop containing code to time...
for ( i = 0; i < b.iterations; i++ ) {
// [3] Code to time...

// [4] A conditional verifying results to prevent certain compiler optimizations:
if ( x !== x ) {
b.fail( 'something went wrong!' );
}
}
// [5] Stop timing:
b.toc();

// [6] Another conditional verifying results to prevent certain compiler optimizations:
if ( x !== x ) {
b.fail( 'something went wrong!' );
}
// [7] End the benchmark:
b.end();
}
`

Asynchronous benchmarks should have a structure similar to the following:

`javascript
function benchmark( b ) {
var i = 0;

// [1] Start timing:
b.tic();

// [2] Asynchronous code to time:
return next();

function next( error ) {
if ( error ) {
return b.fail( error.message );
}
i += 1;

// [3] Exit condition:
if ( i <= b.iterations ) {
// Asynchronous task...
return;
}
// [4] Stop timing:
b.toc();

// [5] End the benchmark:
b.end();
}
}
`

For both synchronous and asynchronous benchmarks, calling b.end() is mandatory, as failing to do so will cause the harness to hang. For example, the following benchmark will never complete.

`javascript
function benchmark( b ) {
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
// Synchronous task...
}
b.toc();
}
`

Avoid making assertions within timed code, as doing so will significantly affect raw performance numbers. For example, avoid the following:

`javascript
function benchmark( b ) {
var x;
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
x = Math.sin( Math.random() );
b.equal( x, x, 'does not return NaN' ); // Avoid doing this!
}
b.toc();
b.equal( x, x, 'does not return NaN' ); // This is fine.
b.end();
}
`

Additionally, ensure that all setup code executes before calling b.tic() and that all cleanup code executes after calling b.toc(). For example, avoid the following:

`javascript
function benchmark( b ) {
var x;
var y;
var i;

// Start timing:
b.tic();

// Setup code:
x = new Array( b.iterations ); // Should be before b.tic()!
for ( i = 0; i < b.iterations; i++ ) {
x[ i ] = Math.random();
}
// Code to be timed...
for ( i = 0; i < b.iterations; i++ ) {
y = Math.sin( x[ i ] );
if ( y !== y ) {
b.fail( 'should not return NaN' );
}
}
// Verify results:
b.equal( x, x, 'does not return NaN' ); // Should be after b.toc()!

// Stop timing:
b.toc();

b.end();
}
`

The function accepts the following options:

- iterations: number of iterations. If null, the number of iterations is determined by trying successive powers of 10 until the total time is at least 0.1 seconds. Default: null.
- repeats: number of repeats. Default: 3.
- timeout: number of milliseconds before a benchmark is considered failed. Exceeding a timeout does not, however, end the benchmark. Ending a long running benchmark requires manual intervention. Default: 300000 (5 minutes).
- skip: boolean indicating whether to skip a benchmark.

By default, the harness will automatically determine an iteration number for each benchmark such that a benchmark runs for a length of time sufficient to accurately compute benchmark results. To require a specific number of iterations, set the iterations option.

`javascript
var opts = {
'iterations': 1e6
};

bench( 'require a specific number of iterations', opts, function benchmark( b ) {
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
// Code to be benchmarked...
}
b.toc();
b.end();
});
`

To ensure that benchmark results are reproducible, the harness runs each benchmark function multiple times. To specify a repetition number, set the repeats option.

`javascript
var opts = {
'repeats': 5
};

bench( 'repeat a benchmark multiple times', opts, function benchmark( b ) {
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
// Code to be benchmarked...
}
b.toc();
b.end();
});
`

To skip a benchmark, set the skip option.

`javascript
var opts = {
'skip': true
};

bench( 'skipped benchmark', opts, function benchmark( b ) {
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
// Code to be benchmarked...
}
b.toc();
b.end();
});
`

To fail benchmarks which take longer than a specified amount of time to complete, set a timeout option (in milliseconds).

`javascript
var opts = {
'timeout': 5000 // 5 seconds
};

bench( 'async benchmark', opts, function benchmark( b ) {
var i = 0;
b.tic();
return next();

function next( error ) {
if ( error ) {
return b.fail( error.message );
}
i += 1;
if ( i <= b.iterations ) {
// Asynchronous task...
return;
}
b.toc();
b.end();
}
});
`

#### bench.onFinish( clbk )

Sets a listener which is invoked once the harness finishes running all benchmarks.

`javascript
function onFinish() {
console.log( 'Done!' );
}

bench.onFinish( onFinish );
`

#### bench.createStream( \[options] )

Returns a results [stream][nodejs-stream].

`javascript
var stdout = require( '@stdlib/streams-node-stdout' );

var stream = bench.createStream();

// Direct all results to stdout:
stream.pipe( stdout );

var opts = {
'iterations': 1,
'repeats': 1
};

bench( 'beep', opts, function benchmark( b ) {
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
b.equal( 3.14, 3.14, 'should be equal' );
}
b.toc();
b.end();
});
`

`text
TAP version 13


beep

The results stream can be combined with any [Writable][nodejs-writable-stream] stream (e.g., network connection, file, stdout, etc).

The function accepts the same options as [@stdlib/streams/node/transform][@stdlib/streams/node/transform]. For example, by default, the method returns a stream which produces [TAP][tap] output as text. To return an object stream,

`javascript
var opts = {
'objectMode': true
};

var stream = bench.createStream( opts );
stream.on( 'data', onRow );

function onRow( row ) {
console.log( JSON.stringify( row ) );
}

opts = {
'iterations': 1,
'repeats': 1
};

bench( 'beep', opts, function benchmark( b ) {
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
b.equal( 3.14, 3.14, 'should be equal' );
}
b.toc();
b.end();
});
`

`text
{"type":"benchmark","name":"beep","id":0}
{"id":0,"ok":true,"name":"should be equal","operator":"equal","actual":3.14,"expected":3.14,"benchmark":0,"type":"assert"}
{"ok":true,"operator":"result","iterations":1,"elapsed":0.00283753,"rate":352.41918147120913,"benchmark":0,"type":"result"}
{"benchmark":0,"type":"end"}
`

#### bench.createHarness( \[options]\[, clbk] )

Creates a benchmark harness with a new pending stack and state.

`javascript
var harness = bench.createHarness();

harness( 'beep', function benchmark( b ) {
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
// Synchronous task...
}
b.toc();
b.end();
});
`

To trigger an action when a harness finishes running all benchmarks, provide a callback function.

`javascript
var harness = bench.createHarness( onFinish );

function onFinish() {
harness.close();
}

harness( 'beep', function benchmark( b ) {
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
// Synchronous task...
}
b.toc();
b.end();
});
`

The method accepts the following options:

- autoclose: boolean indicating whether to automatically close a harness after running all benchmarks.

By default, a harness does not automatically close. To automatically close a harness once a harness finishes running all benchmarks, set the autoclose option to true.

`javascript
var harness = bench.createHarness({
'autoclose': true
});

harness( 'beep', function benchmark( b ) {
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
// Synchronous task...
}
b.toc();
b.end();
});
`

*

$3

A harness has the following properties and methods...

#### harness.createStream( \[options] )

Returns a results [stream][nodejs-stream].

`javascript
var stdout = require( '@stdlib/streams-node-stdout' );

var harness = bench.createHarness();
var stream = harness.createStream();

// Direct all results to stdout:
stream.pipe( stdout );

var opts = {
'iterations': 1,
'repeats': 1
};

harness( 'beep', opts, function benchmark( b ) {
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
b.equal( 'beep', 'beep', 'should be equal' );
}
b.toc();
b.end();
});
`

`text
TAP version 13


beep

The method accepts the same options as [@stdlib/streams/node/transform][@stdlib/streams/node/transform].

Note: benchmarks will not run until a destination stream has been created.

#### harness.close()

Closes a benchmark harness. Any pending benchmarks are cleared from the harness stack.

`javascript
var stdout = require( '@stdlib/streams-node-stdout' );

var harness = bench.createHarness();

var stream = harness.createStream();
stream.pipe( stdout );

var opts = {
'iterations': 5,
'repeats': 5
};

harness( 'early close', opts, function benchmark( b ) {
var i = 0;
b.tic();
setTimeout( next, 0 );
function next() {
i += 1;
if ( i <= b.iterations ) {
b.ok( true, 'should be truthy' );
return setTimeout( next, 10 );
}
b.toc();
b.end();
}
});

// Early close:
setTimeout( onTimeout, 50 );

function onTimeout() {
harness.close();
}
`

`text
TAP version 13


early close

`javascript
var stdout = require( '@stdlib/streams-node-stdout' );

var harness = bench.createHarness();

var stream = harness.createStream();
stream.pipe( stdout );

var opts = {
'iterations': 5
};

harness( 'force exit', opts, function benchmark( b ) {
var i = 0;
b.tic();
return next();
function next() {
i += 1;
if ( i <= b.iterations ) {
b.ok( true, 'should be truthy' );
return setTimeout( next, 10 );
}
b.toc();
b.end();
}
});

// Forcefully exit:
setTimeout( onTimeout, 20 );

function onTimeout() {
harness.exit();
}
`

`text
TAP version 13


force exit

Read-only property whose value is the harness exit code. If all benchmarks run successfully (i.e., no failing assertions), the exit code is 0; otherwise, the exit code is 1.

`javascript
var harness = bench.createHarness();

// Benchmarks only start running when results have a destination:
var stream = harness.createStream();

function onFinish() {
console.log( harness.exitCode );
// => 1
}

var opts = {
'iterations': 1,
'repeats': 1
};

harness( 'exit code', opts, function benchmark( b ) {
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
b.fail( 'failing assertion' );
}
b.toc();
b.end();
});
`

*

$3

A Benchmark instance has the following properties and methods...

#### b.name

Read-only property whose value is the benchmark name.

`javascript
var str = b.name;
// returns
`

#### b.iterations

Read-only property whose value is the number of iterations.

`javascript
var iter = b.iterations;
// returns
`

#### b.tic()

Starts a benchmark timer. In order to benchmark code, this method must always be called within a benchmark function.

`javascript
function benchmark( b ) {
var x;
var i;

// Start a timer:
b.tic();

for ( i = 0; i < b.iterations; i++ ) {
x = Math.sin( Math.random() );
if ( x !== x ) {
b.fail( 'should not return NaN' );
}
}
b.toc();
if ( x !== x ) {
b.fail( 'should not return NaN' );
}
b.end();
}
`

#### b.toc()

Stops a benchmark timer. In order to benchmark code, this method must always be called within a benchmark function.

`javascript
function benchmark( b ) {
var x;
var i;

b.tic();
for ( i = 0; i < b.iterations; i++ ) {
x = Math.sin( Math.random() );
if ( x !== x ) {
b.fail( 'should not return NaN' );
}
}
// Stop a timer:
b.toc();

if ( x !== x ) {
b.fail( 'should not return NaN' );
}
b.end();
}
`

#### b.end()

Explicitly ends a benchmark. In order to benchmark code, this method must always be called within a benchmark function.

`javascript
function benchmark( b ) {
var x;
var i;

b.tic();
for ( i = 0; i < b.iterations; i++ ) {
x = Math.sin( Math.random() );
if ( x !== x ) {
b.fail( 'should not return NaN' );
}
}
b.toc();

if ( x !== x ) {
b.fail( 'should not return NaN' );
}

// Explicitly end the benchmark:
b.end();
}
`

Warning: no assertions should follow a call to b.end(). Including assertions after b.end() may result in interleaved [TAP][tap] output or an output stream closing before a benchmark executes pending assertions.

#### b.comment( msg )

Writes a message without breaking [TAP][tap] output.

`javascript
b.comment( 'This is a comment.' );
`

`text


This is a comment.

`javascript
b.skip( false, 'This is skipped.' );
b.skip( true, 'This is skipped.' );
`

`text
ok 1 This is skipped. # SKIP
ok 2 This is skipped. # SKIP
`

#### b.todo( value, msg )

Generates an assertion which should be implemented.

`javascript
b.todo( false, 'This is a todo.' );
b.todo( true, 'This is a todo.' );
`

`text
not ok 3 This is a todo. # TODO
---
operator: todo
TODO: include stack
...
ok 4 This is a todo. # TODO
`

While b.todo() assertions typically fail, they do not contribute to the failed assertion count. If a benchmark includes b.todo() assertions and no other failing assertions, the benchmark is considered successful.

#### b.fail( msg )

Generates a failing assertion.

`javascript
b.fail( 'This is a failing assertion.' );
`

`text
not ok 5 This is a failing assertion.
---
operator: fail
TODO: include stack
...
`

#### b.pass( msg )

Generates a passing assertion.

`javascript
b.pass( 'This is a passing assertion.' );
`

`text
ok 6 This is a passing assertion.
`

#### b.ok( value\[, msg] )

Asserts that a value is truthy.

`javascript
b.ok( [] );
`

`text
ok 7 should be truthy
`

To override the default message, provide a msg argument.

`javascript
b.ok( true, 'This asserts a value is truthy.' );
b.ok( false, 'This asserts a value is truthy.' );
`

`text
ok 8 This asserts a value is truthy.
not ok 9 This asserts a value is truthy.
---
operator: ok
TODO: include stack
...
`

#### b.notOk( value\[, msg] )

Asserts that a value is falsy.

`javascript
b.notOk( null );
`

`text
ok 10 should be falsy
`

To override the default message, provide a msg argument.

`javascript
b.notOk( false, 'This asserts a value is falsy.' );
b.notOk( true, 'This asserts a value is falsy.' );
`

`text
ok 11 This asserts a value is falsy.
not ok 12 This asserts a value is falsy.
---
operator: notOk
TODO: include stack
...
`

#### b.equal( actual, expected\[, msg] )

Asserts that actual is strictly equal to expected.

`javascript
var expected = [];
var actual = expected;

b.equal( actual, expected );
`

`text
ok 13 should be equal
`

To override the default message, provide a msg argument.

`javascript
var expected = [];
var actual = expected;

b.equal( actual, expected, 'This asserts two values are strictly equal.' );
b.equal( 1.0, 2.0, 'This asserts two values are strictly equal.' );
`

`text
ok 14 This asserts two values are strictly equal.
not ok 15 This asserts two values are strictly equal.
---
operator: equal
TODO: include stack
...
`

#### b.notEqual( actual, expected\[, msg] )

Asserts that actual is not strictly equal to expected.

`javascript
var expected = [];
var actual = [];

b.notEqual( actual, expected );
`

`text
ok 16 should not be equal
`

To override the default message, provide a msg argument.

`javascript
var expected = [];
var actual = [];

b.notEqual( 1.0, 2.0, 'This asserts two values are not equal.' );
b.notEqual( actual, expected, 'This asserts two values are not equal.' );
`

`text
ok 17 This asserts two values are not equal.
not ok 18 This asserts two values are not equal.
---
operator: notEqual
TODO: include stack
...
`

#### b.deepEqual( actual, expected\[, msg] )

Asserts that actual is deeply equal to expected.

`javascript
var expected = {
'a': 'b'
};
var actual = {
'a': 'b'
};

b.deepEqual( actual, expected );
`

`text
ok 19 should be deeply equal
`

To override the default message, provide a msg argument.

`javascript
var expected = {
'a': 'b'
};
var actual = {
'a': 'b'
};

b.deepEqual( actual, expected, 'This asserts two values are deeply equal.' );

actual.a = 'c';
b.deepEqual( actual, expected, 'This asserts two values are deeply equal.' );
`

`text
TODO
`

#### b.notDeepEqual( actual, expected\[, msg] )

Asserts that actual is not deeply equal to expected.

`javascript
var expected = {
'a': 'b'
};
var actual = {
'a': 'c'
};

b.notDeepEqual( actual, expected );
`

`text
ok 22 should not be deeply equal
`

To override the default message, provide a msg argument.

`javascript
var expected = {
'a': 'b'
};
var actual = {
'a': 'c'
};

b.notDeepEqual( actual, expected, 'This asserts two values are not deeply equal.' );

actual.a = 'b';
b.notDeepEqual( actual, expected, 'This asserts two values are not deeply equal.' );
`

`text
TODO
`