Cypress-SignalR-Mock

Easy way to publish messages from and to your SignalR hubs in Cypress E2E tests.

Table of Contents

• Features
• Compatibility
• Install
• Usage
• How does it work
• Contributing
• Credits

Features

• Provides Cypress commands to publish and verify messages from and to the SignalR hub!
• Full TypeScript support!
• Multiple hubs can be mocked at the same time!
• Provides mock support for all public HubConnection methods!
• Small footprint, easy install and very human!
• Also works for Vitest unit testing!

Compatibility

The below are not hard requirements, but the plugin is tested against these versions. It will most likely work with older versions.

• Cypress 10.0.0 or higher
• SignalR 6.0.0 or higher
• TypeScript 4.0.0 or higher
• RxJS 6.6.0 or higher
• Node 12.0.0 or higher

Install

Install with npm:

npm install --save-dev cypress-signalr-mock

Install with yarn:

yarn add cypress-signalr-mock --dev

Install with pnpm:

pnpm add -D cypress-signalr-mock

Usage

// 01. Import the plugin to where your signalR connections are created.
import {useCypressSignalRMock} from 'cypress-signalr-mock';

// 02. Call "useCypressSignalRMock" to create a mock for the SignalR hub connection, make sure to give it an unique hub name. 
// It will return null when Cypress is not running, and thus create the real SignalR connection.
const hubConnection = useCypressSignalRMock('testHub') ??
    new HubConnectionBuilder().withUrl(`http://localhost:3000/testhub`).build();

// 03. Activate the plugin in your cypress/support/index.[js/ts] file.
import 'cypress-signalr-mock';

// 04. Use 'hubPublish()' in your E2E tests to publish messages as if it's the server.
cy.hubPublish(
    'testHub', // The name of the hub
    'hello-world', // The name of the message type
    {
        message: 'Hello World!', // The message payload
    },
);

// 05. The listener will receive the message as normal.
hubConnection.on('hello-world', (data) => {
    console.log(data); // { message: 'Hello World!' }
});

useCypressSignalRMock() options

• debug - Enable debug logging. Default: false

useCypressSignalRMock("testHub", {
    debug: true,
});

• enableForVitest - Enable the plugin to also work for vitest unit testing. Default: false

useCypressSignalRMock("testHub", {
    enableForVitest: true,
});

How does it work

Normally, a plugin like this would replace the window.WebSocket object with a mock object. This is not ideal, as that same window.WebSocket object is also used by Cypress itself during runtime. Instead, the HubConnection class from the @microsoft/signalr package is mocked with the same signatures, while replacing the functionality with Subjects from Rx.js. This mimics the SignalR functionality of sending and receiving messages from the server, while not interfering in any way with Cypress itself.

Cypress Commands

From Server to Client

/**
 * Simulates a message sent from the Server => Client
 */
cy.hubPublish("hubName", "messageType", {
    value: "messagePayload"
});

// The listener will receive the message as normal.
progressHubConnection.on('hello-world', (data) => {
    console.log(data); // { value: "messagePayload" }
});

From Client to Server

/**
 * This command verifies that a specific messageType has been invoked (Client => Server):
 */
cy.hubVerifyInvokes(hubName, messageType, (invokes) => {
    // Do something
    expect(invokes.length).to.equal(5, `${action} not invoked`);
});

Limitations

• Multiple listeners for the same hub name are not supported

// This will NOT work
const progressHubConnection1 = useCypressSignalRMock('progress') ??
    new HubConnectionBuilder().withUrl(`http://localhost:3000/progress1`).build();

const progressHubConnection2 = useCypressSignalRMock('progress') ??
    new HubConnectionBuilder().withUrl(`http://localhost:3000/progress2`).build();

// This will work
const cypressMock = useCypressSignalRMock('progress');
const progressHubConnection1 = cypressMock ??
    new HubConnectionBuilder().withUrl(`http://localhost:3000/progress1`).build();

const progressHubConnection2 = cypressMock ??
    new HubConnectionBuilder().withUrl(`http://localhost:3000/progress2`).build();

• The hubConnection.on and hubConnection.stream cannot have the same message type name.

Contributing

Any contributions, ideas and feedback are very welcome!

Credits

Shout-out to @BassSlagter for his great work on the cypress-plugin-signalr plugin. His work and method was the major inspiration for Cypress-SignalR-Mock. His plugin is unfortunately not maintained anymore, so I decided to make a spiritual successor to it.