Stubnet

Stubnet is a testing library for creating fake TCP servers that can be connected to in automated tests, which will behave in a defined manner. Server behavior is defined as a sequential set of steps of data received and sent.

###Example Test (tap)

var test    = require('tap').test;
var stubnet = require('stubnet');
var net     = require('net');

test('basic connection', function (t) {

	stubnet()
		.listenTo({port: 50000, done: onReady})
		.expectConnection()
		.expectData('hello')
		.thenSend('hi there')
		.expectDisconnect()
		.start(onFinish);

	function onReady() {
		var socket = new net.Socket();
		socket.connect(50000, 'localhost', function () {
			t.pass('net.connect');
			socket.write('hello', function () {
				t.pass('net.send "hello"');
			});
			socket.on('data', function (data) {
				t.equal(data.toString(), 'hi there');
				socket.end(function () {
					t.pass('net.end');
				});
			});
		});
	}

	function onFinish(failed) {
		if (failed) {
			t.fail(failed);
		} else {
			t.pass('test complete');
		}
		t.end();
	}

});

##Usage

####stubnet()

Returns a Builder instance, a chainable class for defining the steps of the server process.

####builder.listenTo(options)

Note, this must be the first step that you define, as it informs the server where to listen for connections.

• options

  • arguments: Optional array of arguments to pass to server.listen()
  • port: The port number to listen on. Required unless defined in the arguments option.
  • bind: The address to bind to (Defaults to 0.0.0.0).
  • secure: Optional. If defined, stubnet will create a tls server with the options defined.
  • pass: Callback to invoke when the server starts successfully and is ready for connections.
  • fail: Callback invoked if the server fails to start. Will receive the socket error as the first argument.
  • done: Callback invoked in both success and failure conditions. Will receive the error as the first argument if one occurred.

####builder.expectConnection([options | callback])

Note, you must define at least one expectConnection condition. Failure to do so will cause the server to abort with an 'Unexpected connection' message.

• options (optional)

  • timeout: Number of milliseconds to wait for a connection before failing the test.
  • pass: Callback to invoke when the connection is received.
  • fail: Callback invoked if no connection is received before the timeout occurs.
  • done: Callback invoked in both success and failure conditions. Will receive an AssertionError as the first argument if the step failed

• callback: A done callback function may optionally be provided in place of options.

####builder.expectData(data, [options | callback])

####builder.expectDataFrom(index, data, [options | callback])

The expectData step scan the socket data buffer until either all of the expected data is seen, or the buffer contains a mismatched value. Matched data is then removed from the data buffer.

• index: If multiple connections are being made, expectDataFrom may be used to identify which connection (order of connecting, zero-based).

• data may be any acceptable input for a Buffer, including strings, integer arrays, or pre-made buffers.

• options (optional)

  • timeout: Number of milliseconds to wait for the data to fully arrive.
  • pass: Callback to invoke when the matching data is received.
  • fail: Callback invoked if the data does not match, or the complete data is not received before the timeout occurs. Receives an equality AssertionError as the first argument.
  • done: Callback invoked in both success and failure conditions. Will receive an AssertionError as the first argument if the step failed

• callback: A done callback function may optionally be provided in place of options.

####builder.thenSend(data, [options | callback]) ####builder.thenSendTo(index, data, [options | callback])

When this step evaluates it will send the provided data to the socket. The step passes when the send buffer is fully drained to the system kernal.

• index: If multiple connections are being made, thenSendTo may be used to identify which connection (order of connecting, zero-based).

• data may be any acceptable input for a Buffer, including strings, integer arrays, or pre-made buffers.

• options (optional)

  • pass: Callback to invoke when the data is sent.
  • fail: Callback invoked if an error occurred while sending the data. Will receive the error as the first argument.
  • done: Callback invoked in both success and failure conditions. Will receive the error as the first argument if one occurred.

• callback: A done callback function may optionally be provided in place of options.

####builder.expectNoData([options | callback]) ####builder.expectNoDataFrom(index, [options | callback])

Step to confirm that no further data has been received from the socket before moving on to the next step.

• index: If multiple connections are being made, expectNoDataFrom may be used to identify which connection (order of connecting, zero-based).

• options (optional)

  • pass: Callback to invoke if the data buffer is empty.
  • fail: Callback invoked if the data buffer is NOT empty. Receives an equality AssertionError as the first argument.
  • done: Callback invoked in both success and failure conditions. Will receive an AssertionError as the first argument if the step failed

• callback: A done callback function may optionally be provided in place of options.

####builder.expectDisconnect([options | callback]) ####builder.expectDisconnectBy(index, [options | callback])

Waits for the socket to close from the other side.

• index: If multiple connections are being made, expectDisconnectBy may be used to identify which connection (order of connecting, zero-based).

• options (optional)

  • timeout: Number of milliseconds to wait for the socket to close before failing the test.
  • pass: Callback to invoke when the connection is received.
  • fail: Callback invoked if no connection is received before the timeout occurs.
  • done: Callback invoked in both success and failure conditions. Will receive an AssertionError as the first argument if the step failed.

• callback: A done callback function may optionally be provided in place of options.

####builder.thenClose([index],[options | callback])

Step to confirm that no further data has been received from the socket before moving on to the next step.

• index: If multiple connections are being made, the connection index (order of connecting, zero-based) may be used to identify which connection to close.

• options (optional)

  • pass: Callback to invoke when the connection closes.
  • fail: Callback invoked if the connection closure times out, or another error occurs.
  • done: Callback invoked in both success and failure conditions. Will receive the error as the first argument if one occurred.

• callback: A done callback function may optionally be provided in place of options.

####builder.start([options | callback])

Start the server. This function returns a runner object.

• options (optional)

  • pass: Callback to invoke when all steps have completed successfully.
  • fail: Callback invoked if any of the steps have failed. Receives the same error that was provided to that step's fail function.
  • done: Callback invoked in both success and failure conditions. Will receive the error as the first argument if one occurred.

• callback: A done callback function may optionally be provided in place of options.

####runner.abort()

Aborts the run, stopping the server and triggering a failure condition on the current step.