socket.io-unit

Unit testing for socket.io servers.

Install

yarn add socket.io-unit

How to use

First you need to make sure that all your socket.io server endpoints have and acknowledgement callback as the last parameter, and that it's always called. Example:

socket.on('createFile', function(fileName, contents, cb) {
	if (something) {
		let filePath = path.join(os.tmpdir(), fileName);
		fs.writeFileSync(filePath, contents);
		cb({status: true, path: filePath});

		socket.emit('some-event', 10);
	}
	else {
		cb({status: false, message: 'Failed for some reason'});
	}
});

Then as the second parameter for socket.io-unit you should pass a function that handles the acknowledgement, returning either a resolved or rejected Promise:

const SocketioUnit = require('socket.io-unit');
let URL	= 'https://localhost:3000';

let so = new SocketioUnit(
	URL,
	// result is something like: {status: true|false, message: '', ...}
	(result) => {
		if (result.status === true) {
			return Promise.resolve(result);
		}
		else {
			return Promise.reject(result.message);
		}
	}
);

Now you can connect clients with the .connect() method:

let testClient1 = await so.connect();
let testClient2 = await so.connect();
let testClient3 = await so.connect();

Each object contains Promise based versions of the usual on, emit and disconnect methods of a socket.io client instance:

let eventData = await testClient1.on('some-event');

let ackData = await testClient2.emit('createFile');

await testClient3.disconnect();

Check test-server.js for a server example, and test/BasicTest.js for examples using the Mocha test framework.

API

static disconnectAll() -> Promise

Disconnect all socket.io-unit connected clients.

static getAllClients() -> [testClient1, testClient2, ...]

Return all socket.io-unit connected clients.

• url: server url.
• handlerFunction: Function that handles the server acknowledgement.
• timeout: how much time to wait for the server connection.
• parameters: options.

.connect() -> Promise

Return a Promise which resolves with a socket.io-client object.

.connectMany(n = 2) -> [Promise1, Promise2, ..., Promise n]

n * .connect.

.emit() -> Promise

Promise based version of the emit method.

// server
socket.on('ev', function(arg1, arg2, cb) {
	cb({status: true, data: 'some data'});
});

// client
let result = await testClient1.emit('ev');
assert.ok(result.status);
assert.equal('some data', result.data);

Note that in order for it to work you need to define a proper handler function in the constructor.

.on() -> Promise

Promise based verison of the on method. If successful the promise will resolve with an array that contains the values emitted by the server, example:

// server
socket.emit('someEvent', 'hi');
socket.emit('secondEvent', 'foo', 'bar');

// client
let data = await testClient1.on('someEvent');
assert.equal('hi', data[0]);

let [foo, bar] = await testClient1.on('secondEvent');

assert.equal('foo', foo);
assert.equal('bar', bar);

.disconnect() -> Promise

Promise based verison of the disconnect method. The promise being resolved doesn't guarantee that the server has acknowledged the disconnection.

Tests

First start the test server with yarn run server then run yarn run test. The default used port is 8080, you can change that with the SOCKET_PORT env var:

• SOCKET_PORT=2000 yarn run server.
• SOCKET_PORT=2000 yarn run test.

Use yarn run lint to run the linter.

License

The MIT License