superwstest

library3.0.0jsnpmunverified

SuperWSTest (v3.0.0) extends supertest with WebSocket testing capabilities, allowing you to test WebSocket endpoints alongside HTTP endpoints using the same request-like API. It integrates seamlessly with supertest and provides methods like .ws(), .expectText(), .expectJson(), and .close(). The package ships TypeScript types, supports both local and remote servers, auto-closes connections via server.close, and offers scoped instances for parallel test isolation. Unlike raw ws integration, it provides a supertest-compatible fluent API with built-in message filtering and expectations.

testing

npm install superwstest

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SUPERWSTEST

superwstest

testingjavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import request from 'superwstest'

✗ import * as request from 'superwstest'

Default export is the main request function. Importing as namespace is uncommon but works.

request (CommonJS)

✓ const request = require('superwstest').default

✗ const request = require('superwstest')

CommonJS (require) needs .default because superwstest is an ES module. In TypeScript with esModuleInterop, just require may work.

request.scoped

✓ import request from 'superwstest'; const scoped = request.scoped()

✗ import { scoped } from 'superwstest'

scoped() is a method on the default export, not a named export.

Tests a WebSocket echo server using SuperWSTest's fluent API: connect, expect initial message, send, expect echo, close.

import http from 'node:http'; import WebSocket from 'ws'; import request from 'superwstest'; 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'); }); describe('WebSocket tests', () => { beforeEach((done) => server.listen(0, 'localhost', done)); afterEach((done) => server.close(done)); it('should echo messages', async () => { await request(server) .ws('/ws') .expectText('hello') .sendText('world') .expectText('echo world') .close() .expectClosed(); }); }); if (process.env.RUN_TESTS !== 'true') { // prevent accidental test run }

Debug

Known issues

gotchaWhen testing a remote server, connections are NOT automatically closed. Use request.closeAll() in an afterEach to avoid hanging connections.

fix

Add afterEach(() => request.closeAll()); in your test suite for remote servers.

affects: >=1.0.0

gotchascoped() creates an isolated request instance. Forgetting to use scoped when running tests in parallel (Jest workers) may cause closeAll to interfere with other test suites.

fix

Use const request = baseRequest.scoped(); and afterEach(() => request.closeAll()); for each describe block.

affects: >=1.0.0

deprecatedIn v2, .expectText() had a different signature. The second argument (options) was added in v3, but default behavior changed slightly.

fix

Upgrade to v3 and review the options parameter in .expectText() and .expectJson().

affects: >=2.0.0 <3.0.0

breakingIn v3, CommonJS (require) users must use .default: const request = require('superwstest').default. Plain require returns an object.

fix

Use require('superwstest').default, or switch to ES module imports.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: request(...).ws is not a function

Using .ws() on a supertest request object that hasn't been augmented by superwstest, or incorrect import.

fix

Ensure you import default from 'superwstest', not from 'supertest' alone. Use import request from 'superwstest' and then request(server).ws(...).

Error: server.close is not a function

Passing a closed server or a non-Net.Server object (e.g., a URL string) to request(). After server.close() is called, the server is destroyed.

fix

Recreate the server in beforeEach, not before the test suite. For remote servers, use a URL string instead of a server object.

Timeout - Async callback was not invoked within the 5000 ms timeout specified by jest.setTimeout

WebSocket connection hangs because server isn't listening or path doesn't exist. Or await missing on async calls.

fix

Ensure server.listen is called before test, and add await before request(...).ws(...). Also check WebSocket path matches server.

expect(received).toBeDefined() - Expected the WebSocket to be defined but it is undefined

The WebSocket connection failed silently (e.g., wrong protocol, server rejected).

fix

Check server's websocket path and options. Add .expectConnection() or ensure server is listening.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

supertestoptionalpeer dependency required for HTTP request proxy (get, post, etc.)

@types/supertestoptionalpeer dependency for TypeScript users to type supertest methods

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/davidje13/superwstest ↗

packagesuperwstest ↗

homepagehttps://github.com/davidje13/superwstest#readme ↗