SuperWSTest

Provides a supertest-compatible API
for testing WebSockets.

If supertest is installed, this package also exposes supertest's API for
convenience when testing servers which provide both HTTP and WebSocket URLs.

Install dependency

``bash
npm install --save-dev superwstest
`

You can also optionally install supertest for access to .get, .post, etc.:

`bash
npm install --save-dev superwstest supertest
`

Usage

$3

`javascript
import http from 'http';
import WebSocket from 'ws';

const server = http.createServer();
const wss = new WebSocket.Server({ server });

wss.on('connection', (ws) => {
ws.on('message', (message) => { ws.send(echo ${message}); });
ws.send('hello');
});

export default server;
`

$3

`javascript
import request from 'superwstest';
import server from './myServer';

describe('My Server', () => {
beforeEach((done) => {
server.listen(0, 'localhost', done);
});

afterEach((done) => {
server.close(done);
});

it('communicates via websockets', async () => {
await request(server)
.ws('/path/ws')
.expectText('hello')
.sendText('foo')
.expectText('echo foo')
.sendText('abc')
.expectText('echo abc')
.close()
.expectClosed();
});
});
`

As long as you add server.close in an afterEach, all connections
will be closed automatically, so you do not need to close connections
in every test.

$3

If you have installed supertest, all the HTTP checks are also available
by proxy:

`javascript
import request from 'superwstest';
import server from './myServer';

describe('My Server', () => {
beforeEach((done) => server.listen(0, 'localhost', done));
afterEach((done) => server.close(done));

it('communicates via HTTP', async () => {
await request(server)
.get('/path')
.expect(200);
});
});
`

$3

You can also test against a remote webserver by specifying the URL
of the server:

`javascript
import request from 'superwstest';

describe('My Remote Server', () => {
afterEach(() => {
request.closeAll(); // recommended when using remote servers
});

it('communicates via websockets', async () => {
await request('https://example.com')
.ws('/path/ws')
.expectText('hello')
.close();
});
});
`

The server URL given should be http(s) rather than ws(s); this will
provide compatibility with native supertest requests such as post,
get, etc. and will be converted automatically as needed.

Note that adding request.closeAll() to an afterEach will
ensure connections are closed in all situations (including test
timeouts, etc.). This is not needed when testing against a local
server because the server will close connections when closed.

If you need to scope the request instance (to avoid closeAll
interfering with other tests running in parallel in the same
process), you can use .scoped() (note that this is not
typically required when using Jest since parallel execution is
performed using separate processes):

`javascript
import baseRequest from 'superwstest';

describe('thing', () => {
const request = baseRequest.scoped();
afterEach(() => request.closeAll());
/ ... /
});
`

API

- [request(server[, options])](#requestserver-options)
- [request(...).ws(path[, protocols][, options])](#requestserverwspath-protocols-options)
- .set(header, value)
- .unset(header)
- .filterMessages(test)
- [.filterText([test])](#filtertexttest)
- [.filterJson([test])](#filterjsontest)
- [.filterBinary([test])](#filterbinarytest)
- [.expectText([expected[, options]])](#expecttextexpected-options)
- [.expectJson([expected[, options]])](#expectjsonexpected-options)
- [.expectBinary([expected[, options]])](#expectbinaryexpected-options)
- [.waitForText([expected[, options]])](#waitfortextexpected-options)
- [.waitForJson([expected[, options]])](#waitforjsonexpected-options)
- [.waitForBinary([expected[, options]])](#waitforbinaryexpected-options)
- .sendText(text)
- .sendJson(json)
- .sendBinary(data)
- [.send(data[, options])](#senddata-options)
- [.close([code[, reason]]](#closecode-reason)
- [.expectClosed([expectedCode[, expectedReason]])](#expectclosedexpectedcode-expectedreason)
- [.expectConnectionError([expectedStatusCode])](#expectconnectionerrorexpectedstatuscode)
- .expectUpgrade(test)
- .wait(milliseconds)
- .exec(fn)

$3

The beginning of a superwstest
(or supertest) test chain.
Typically this is immediately followed by .ws(...) or .get(...) etc.

options can contain additional configuration:

- shutdownDelay: wait up to the given number of milliseconds for
connections to close by themselves before forcing a shutdown when
close is called on the server. By default this is 0 (i.e. all
connections are closed immediately). Has no effect when testing
remote servers.

`javascript
request(server, { shutdownDelay: 500 }).ws(path)
`

- defaultExpectOptions: a set of options which are passed to all
expect* calls in the current chain (e.g. allows setting a timeout
for all expectations in the chain):

`javascript
request(server, { defaultExpectOptions: { timeout: 5000 } })
.ws(path)
.expectText('hello') // implicit { timeout: 5000 }
.expectText('hi', { timeout: 9000 }) // overrides default
`

- defaultWaitForOptions: a set of options which are passed to all
waitFor* calls in the current chain (e.g. allows setting a timeout
for all waits in the chain)

$3

Returns a Promise (eventually returning the WebSocket) with
additional fluent API methods attached (described below).

Internally, this uses ws, and the
protocols and options given are passed directly to the
WebSocket constructor.
For example, one way to set a cookie:

`javascript
request(myServer)
.ws('/path/ws', { headers: { cookie: 'foo=bar' } })
`

(you can also use .set('Cookie', 'foo=bar') to set cookies)

$3

Sets the header-value pair on the initial WebSocket connection. This can
also be called with an object to set multiple headers at once.

`javascript
request(server).ws('...')
.set('Cookie', 'foo=bar')
.set({ 'Authorization': 'bearer foo', 'X-Foo': 'bar' })
`

This function cannot be called after the connection has been established
(i.e. after calling send or expect*).

$3

Removes the header from the initial WebSocket connection.

`javascript
request(server).ws('...')
.unset('Cookie')
`

This function cannot be called after the connection has been established
(i.e. after calling send or expect*).

$3

Filters out any incoming messages which do not match the test function.
This can be used to ignore background messages which are not relevant to
the code being tested.

`javascript
request(server).ws('...')
.filterMessages(({ data, isBinary }) => {
if (isBinary) {
return true; // allow all binary messages
} else {
return String(data) !== 'ping'; // allow all text messages except "ping"
}
})
`

The data passed to the test function will always be a NodeJS Buffer.
If multiple filters are specified, they are AND-ed together.

This function cannot be called after the connection has been established
(i.e. after calling send or expect*).

$3

Filters out any incoming messages which do not match the test function.
This can be used to ignore background messages which are not relevant to
the code being tested. Implicitly excludes all binary messages.

`javascript
request(server).ws('...')
.filterText((message) => message !== 'ping')
`

If multiple filters are specified, they are AND-ed together.

This function cannot be called after the connection has been established
(i.e. after calling send or expect*).

$3

Filters out any incoming messages which do not match the test function.
This can be used to ignore background messages which are not relevant to
the code being tested. Implicitly excludes all binary messages and text
messages which cannot be parsed as JSON.

`javascript
request(server).ws('...')
.filterJson((message) => message.type !== 'system')
`

If multiple filters are specified, they are AND-ed together.

This function cannot be called after the connection has been established
(i.e. after calling send or expect*).

$3

Filters out any incoming messages which do not match the test function.
This can be used to ignore background messages which are not relevant to
the code being tested. Implicitly excludes all text messages.

`javascript
request(server).ws('...')
.filterBinary((message) => message[0] === 1)
`

The message parameter will always be a Uint8Array.
If multiple filters are specified, they are AND-ed together.

This function cannot be called after the connection has been established
(i.e. after calling send or expect*).

$3

Waits for the next message to arrive then checks that it matches the given
text (exact match), regular expression, or function. If no parameter is
given, this only checks that the message is text (not binary).

`javascript
request(server).ws('...')
.expectText('hello') // exact text
.expectText(/^hel*o$/) // RegExp matching
.expectText((actual) => actual.includes('lo')) // function
.expectText() // just check message is text
`

When using a function, the check will be considered a failure if it
returns false. Any other value (including undefined and null)
is considered a pass. This means you can use (e.g.) Jest expectations
(returning no value):

`javascript
request(server).ws('...')
.expectText((actual) => {
expect(actual).toContain('foo');
})
`

A second parameter can be given with additional options:

- timeout: wait up to the given number of milliseconds for a message
to arrive before failing the test (defaults to infinity).

`javascript
request(server).ws('...')
.expectText('hello', { timeout: 1000 })
.expectText(undefined, { timeout: 1000 })
`

Note that for the most reliable tests, it is recommended to stick with
the default (infinite) timeout. This option is provided as an escape
hatch when writing long flow tests where the test timeout is
unreasonably large for detecting an early failure.

These options can also be configured for the whole chain in the
request call.

$3

Waits for the next message to arrive, deserialises it using JSON.parse,
then checks that it matches the given data
(deep equality)
or function.
If no parameter is given, this only checks that the message is valid JSON.

`javascript
request(server).ws('...')
.expectJson({ foo: 'bar', zig: ['zag'] }) // exact match
.expectJson((actual) => (actual.foo === 'bar')) // function
.expectJson() // just check message is valid JSON
`

When using a function, the check will be considered a failure if it
returns false. Any other value (including undefined and null)
is considered a pass. This means you can use (e.g.) Jest expectations
(returning no value):

`javascript
request(server).ws('...')
.expectJson((actual) => {
expect(actual.bar).toBeGreaterThan(2);
})
`

A second parameter can be given with additional options:

- timeout: wait up to the given number of milliseconds for a message
to arrive before failing the test (defaults to infinity).

`javascript
request(server).ws('...')
.expectJson({ foo: 'bar' }, { timeout: 1000 })
.expectJson(undefined, { timeout: 1000 })
`

Note that for the most reliable tests, it is recommended to stick with
the default (infinite) timeout. This option is provided as an escape
hatch when writing long flow tests where the test timeout is
unreasonably large for detecting an early failure.

These options can also be configured for the whole chain in the
request call.

$3

Waits for the next message to arrive then checks that it matches the given
array / buffer (exact match) or function. If no parameter is given,
this only checks that the message is binary (not text).

When providing a function, the data will always be a Uint8Array.

`javascript
request(server).ws('...')
.expectBinary([10, 20, 30])
.expectBinary(new Uint8Array([10, 20, 30]))
.expectBinary((actual) => (actual[0] === 10)) // function
.expectBinary() // just check message is binary
`

When using a function, the check will be considered a failure if it
returns false. Any other value (including undefined and null)
is considered a pass. This means you can use (e.g.) Jest expectations
(returning no value):

`javascript
request(server).ws('...')
.expectBinary((actual) => {
expect(actual[0]).toBeGreaterThan(2);
})
`

A second parameter can be given with additional options:

- timeout: wait up to the given number of milliseconds for a message
to arrive before failing the test (defaults to infinity).

`javascript
request(server).ws('...')
.expectBinary([10, 20, 30], { timeout: 1000 })
.expectBinary(undefined, { timeout: 1000 })
`

Note that for the most reliable tests, it is recommended to stick with
the default (infinite) timeout. This option is provided as an escape
hatch when writing long flow tests where the test timeout is
unreasonably large for detecting an early failure.

These options can also be configured for the whole chain in the
request call.

$3

Waits for the next message which matches the given text (exact match),
regular expression, or function; discarding all non-matching messages.
If no parameter is given, this only waits for a text message (not
binary).

`javascript
request(server).ws('...')
.waitForText('100%') // exact text
.waitForText(/^done$/) // RegExp matching
.waitForText((actual) => actual.includes('complete')) // function
.waitForText() // just wait for text
`

For details on using a function matcher, see
expectText.

This method is intended for situations where you need to skip past
"progress" messages (e.g. a file upload reporting the upload
percentage). If you just need to check a single message, use
expectText instead. If you need to
ignore irrelevant messages, use filterText
instead.

A second parameter can be given with additional options:

- timeout: wait up to the given number of milliseconds before failing
the test (defaults to infinity).

`javascript
request(server).ws('...')
.waitForText('hello', { timeout: 1000 })
.waitForText(undefined, { timeout: 1000 })
`

These options can also be configured for the whole chain in the
request call.

$3

Waits for the next message which can be deserialised using JSON.parse
and matches the given data
(deep equality)
or function; discarding all non-matching messages. If no parameter is
given, this only waits for a message which is valid JSON.

`javascript
request(server).ws('...')
.waitForJson({ done: true }) // exact text
.waitForJson((actual) => actual.done) // function
.waitForJson() // just wait for valid JSON
`

For details on using a function matcher, see
expectJson.

This method is intended for situations where you need to skip past
"progress" messages (e.g. a file upload reporting the upload
percentage). If you just need to check a single message, use
expectJson instead. If you need to
ignore irrelevant messages, use filterJson
instead.

A second parameter can be given with additional options:

- timeout: wait up to the given number of milliseconds before failing
the test (defaults to infinity).

`javascript
request(server).ws('...')
.waitForJson({ done: true }, { timeout: 1000 })
.waitForJson(undefined, { timeout: 1000 })
`

These options can also be configured for the whole chain in the
request call.

$3

Waits for the next message which matches the given array / buffer
(exact match) or function; discarding all non-matching messages.
If no parameter is given, this only waits for a binary message (not
text).

When providing a function, the data will always be a Uint8Array.

`javascript
request(server).ws('...')
.waitForBinary([100])
.waitForBinary(new Uint8Array([100]))
.waitForBinary((actual) => (actual[0] === 100)) // function
.waitForBinary() // just wait for binary
`

For details on using a function matcher, see
expectBinary.

This method is intended for situations where you need to skip past
"progress" messages (e.g. a file upload reporting the upload
percentage). If you just need to check a single message, use
expectBinary instead. If you need
to ignore irrelevant messages, use
filterBinary instead.

A second parameter can be given with additional options:

- timeout: wait up to the given number of milliseconds before failing
the test (defaults to infinity).

`javascript
request(server).ws('...')
.waitForBinary([100], { timeout: 1000 })
.waitForBinary(undefined, { timeout: 1000 })
`

These options can also be configured for the whole chain in the
request call.

$3

Sends the given text. Non-strings are converted using String before
sending.

`javascript
request(server).ws('...')
.sendText('yo')
`

$3

Sends the given JSON as text using JSON.stringify.

`javascript
request(server).ws('...')
.sendJson({ foo: 'bar' })
`

$3

Sends the given data as a binary message.

`javascript
request(server).ws('...')
.sendBinary([10, 20, 30])
.sendBinary(new Uint8Array([10, 20, 30]))
`

$3

Sends a raw message (accepts any types accepted by
WebSocket.send,
and options is passed through unchanged).

`javascript
request(server).ws('...')
.send(new Uint8Array([5, 20, 100])) // binary message

// multipart message
.send('this is a fragm', { fin: false })
.send('ented message', { fin: true })
`

$3

Closes the socket. Arguments are passed directly to
WebSocket.close.

`javascript
request(server).ws('...')
.close() // close with default code and reason

request(server).ws('...')
.close(1001) // custom code

request(server).ws('...')
.close(1001, 'getting a cup of tea') // custom code and reason
`

$3

Waits for the socket to be closed. Optionally checks if it was closed
with the expected code and reason.

`javascript
request(server).ws('...')
.expectClosed()

request(server).ws('...')
.expectClosed(1001) // expected code

request(server).ws('...')
.expectClosed(1001, 'bye') // expected code and reason
`

$3

Expect the initial connection handshake to fail. Optionally checks for
a specific HTTP status code.

note: if you use this, it must be the only invocation in the chain

`javascript
request(server).ws('...')
.expectConnectionError(); // any error

request(server).ws('...')
.expectConnectionError(404); // specific error code

request(server).ws('...')
.expectConnectionError('Server sent an invalid subprotocol'); // specific error message
`

$3

Run a check against the Upgrade response. Useful for making arbitrary
assertions about parts of the Upgrade response, such as headers.

The check will be considered a failure if it returns false. Any other
value (including undefined and null) is considered a pass.
This means you can use (e.g.) Jest expectations (returning no value).

The parameter will be a
http.IncomingMessage.

`javascript
request(server).ws('...')
.expectUpgrade((res) => (res.headers['set-cookie'] === 'foo=bar'));

request(server).ws('...')
.expectUpgrade((res) => {
expect(res.headers).toHaveProperty('set-cookie', 'foo=bar');
})
`

$3

Adds a delay of a number of milliseconds using setTimeout. This is
available as an escape hatch, but try to avoid using it, as it may
cause intermittent failures in tests due to timing variations.

`javascript
request(server).ws('...')
.wait(500)
`

$3

Invokes the given function. If the function returns a promise, this
waits for the promise to resolve (but ignores the result). The function
will be given the WebSocket as a parameter. This is available as an
escape hatch if the standard functions do not meet your needs.

`javascript
request(server).ws('...')
.exec((ws) => console.log('hello debugger!'))
`

*note: this differs from Promise.then because you can continue to
chain web socket actions and expectations.*

See the FAQ
for examples of how exec can be used to perform side operations
during a connection.

FAQ

$3

Your server is probably trying to indicate that you need to specify a
particular sub-protocol when connecting:

`javascript
request(myServer)
.ws('/path/ws', 'my-protocol-here')
`

You will need to check the documentation for the server library you are
using to find out which subprotocol is needed. If multiple sub-protocols
are needed, you can provide an array of strings.

$3

Older versions of this library bundled supertest by default because they
used some functionality from it. The latest version does not require any
functionality from supertest but remains API-compatible with it, and for
this reason supertest has become optional and not included by default
(reducing dependencies when testing WebSocket-only servers).

To restore the ability to use .get, .post, etc. simply run:

`shell
npm install --save-dev supertest
`

The presence of this package will detected automatically and the supertest
API will be available via superwstest as before.

$3

This project aims to be API-compatible with supertest wherever possible,
but does not support the ability to pass an express app directly into
request() (instead, the server must be started in advance and the server
object passed in). The recommended approach is:

`javascript
let server;

beforeEach((done) => {
server = app.listen(0, 'localhost', done);
});

afterEach((done) => {
server.close(done);
});
`

There are several reasons for not supporting this feature:

- supertest's implementation
has a bug where it
does not wait for the server to start before making requests. This can lead
to flakey tests. For this reason it seems beneficial to discourage this
approach in general (for both WebSocket and non-WebSocket tests).
- It is not possible for this library to reliably know when a test has ended,
so it is not obvious when the auto-started server should be closed.
supertest
never closes these auto-started servers
(leading to
a large number of servers being spawned
during a test run), but even this approach is not viable for WebSocket
testing (typical web requests are short-lived, but websockets are long-lived
and any dangling connections will prevent the test process from terminating).

$3

Often when testing websockets, you will want to perform another action and
check for a reaction on the websocket. This can be achieved using exec:

`javascript
await request(server).ws('here')
.sendText('hello')
.expectText('session open')
.exec(async () => {
await myOtherOperation();
})
.expectText('something happened')
.close();
`

The recommended approach is to pull these out as helper functions, for example:

`javascript
const makeThing = (name) => () => request(server)
.post('blah')
.expect(200);

await request(server).ws('here')
.sendText('hello')
.expectText('session open')

.exec(makeThing('my first thing'))
.expectText('made "my first thing"')

.exec(makeThing('my second thing'))
.expectText('made "my second thing"')

.close();
`

If you need 2 websocket connections to interact with each other, you can use
Promise.all:

`javascript
await Promise.all([
request(server).ws('here')
.expectText('Welcome to the chat room')
.sendText('Hi all! I am foo')
.expectText('Hi foo, I am bar')
.close(),
request(server).ws('here')
.expectText('Welcome to the chat room')
.expectText('Hi all! I am foo')
.sendText('Hi foo, I am bar')
.close(),
]);
``