Skip to content
Test WebSocket connections with Cypress
TypeScript JavaScript
Branch: master
Clone or download
dsebastian Merge pull request #2 from lensesio/docs/added-rxjs-info
docs: ✏️ Added rxjs dependency reference
Latest commit b90e92a Nov 22, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples feat: 🎸 Initial Release Nov 21, 2019
src feat: 🎸 Initial Release Nov 21, 2019
.gitignore feat: 🎸 Initial Release Nov 21, 2019
.travis.yml feat: 🎸 Initial Release Nov 21, 2019 feat: 🎸 Initial Release Nov 21, 2019 docs: ✏️ Added rxjs dependency reference Nov 22, 2019
package.json fix: 🐛 Github link Nov 21, 2019
release.config.js feat: 🎸 Initial Release Nov 21, 2019
tsconfig.json feat: 🎸 Initial Release Nov 21, 2019
tslint.json feat: 🎸 Initial Release Nov 21, 2019


Test your WebSocket endpoints using Cypress.

Build Status
Commitizen friendly semantic-release License: Apache 2 TypeScript

Table of Contents


Cypress comes out of the box with a great set of tools, that allow both UI and API integration tests to be written. Unfortunatelly the cy.request() command is limited to REST endpoints only, so this library is here to help with those cases when WebSockets need to be called/tested as part of more complex integration/E2E tests.


npm i -D @lensesio/cypress-websocket-testing
# or
yarn add -D @lensesio/cypress-websocket-testing

You also need to add rxjs to the project.

npm i -D rxjs



@lensesio/cypress-websocket-testing extends Cypress' cy command.

Add this line to your project's cypress/support/commands.js:

import { addStreamCommands } from '@lensesio/cypress-websocket-testing';

Then, in your test, you can use both commands that come with this lib. and cy.streamRequest.

// For common cases:
cy.streamRequest(config, options).then(results => {
// When in need of a bit more flexibility => {
          reduce((acc , val) => acc.concat([val]), [])
          next: (results) => {
          error: (err) => {},
          complete: done


As the library is written in Typescript, you can pass the type of the message to the command and to the config/options object. ( make sure that you already configured your Cypress tests to work with TS )

First, add @lensesio/cypress-websocket-testing to the cypress/tsconfig.json file

  "compilerOptions": {
    "types": [

Then to use in TypeScript tests:

// For full set of config values, check rxjs documentation
const config: WebSocketSubjectConfig<IMessage> = {
  url: "ws://localhost:8080/"

let options: Partial<StreamRequestOptions<IMessage>>;

cy.streamRequest<IMessage>(config, options).then((results?: IMessage[]) => {
})<IMessage>(config).then(subject => {
          reduce((acc: IMessage[], val: IMessage) => acc.concat([val]), [])
          next: (results?: IMessage[]) => {
          error: (err: any) => {},
          complete: done

Note: There are some type conflicts when extending/adding operators to in tests directly. (due to issues with Cypress including an old rxjs version as a dependency). Best way is to extend by building a custom command with it and use that instead.


  • config

A WebSocketSubjectConfig object. See official docs for more information. Is passed as is to the underlying webSocket subject.

  • options:StreamRequestOptions (only for streamRequest command. Although optional, at least the takeWhileFn should be set)

Usage cy.streamRequest(config, options).

Option Default Description
streamTimeout defaultCommandTimeout Time to wait for the stream to complete. (if is greater than Cypress defaultCommandTimeout, you need to use the cy.wrap as a workaround. Investigating alternative ways)
retryDelay 4000 How long to way until a new connection attempt is made.
retryAttempts 5 How many times to retry the connection before completing.
startUpMessage any A message to be sent on connection open.
takeWhileFn ()=>false Function that will tell the stream when to close. If not set, it will close on the first message received in order to avoid having an open connection.
retryUntilFn ()=>true Function that will tell the stream how to check the results, and retry if the result is false.

Running the examples

In order to try this project locally, you need to npm install in both the root and the examples/ folder. After, build the library using npm run build in the root folder, then go to examples/ , start the websocket server npm start and cypress using npm run test:local.


PRs are welcome. Be sure to add

  • Tests
  • Reason for the PR

When committing, remember to use `npm run commit`, in order to start commitizen.


  • [] Find a fix for the cy.wrap workaround.
  • [] Improve error handling.
  • [] Add more examples for command.


Apache 2.0

You can’t perform that action at this time.