Manual WebSocket

Table of Contents:

1. Example

2. Motivation

3. Documentation

   1. The big picture

   2. Global scope

   3. Public API

      1. Global object

         1. mws.track (method)
         2. mws.untrack (method)
         3. mws.readyState (object with constants)
         4. mws.trackedConnections (object with methods)
            1. mws.trackedConnections.getAll (method)
            2. mws.trackedConnections.getByUrl (method)
            3. mws.trackedConnections.when (method)
         5. mws.when (method)
         6. mws.bus (event emitter)
         7. mws.busEvent (object with constants)

      2. Instance of ManualWebSocketConnection

         • WebSocket methods
         • ability to change readyState by hand
         • connection.addServerScenario (method)

4. How to use it in your project

   1. Setup using module - Cypress example
   2. Setup without module - raw html

Example:

• https://github.com/baal-cadar/manual-web-socket-example

Motivation:

There are many ways for stubbing http responses, for example in cypress we can use cy.route(). But there is no out of the box way to stub WebSocket communication.

Manual WebSocket is built to serve that purpose.

Check repository https://github.com/baal-cadar/manual-web-socket-example for working example.

Documentation

The big picture

1. Replace native WebSocket constructor with ManualWebSocketConnection
2. Tell ManualWebSocket which addresses to track
3. When new WebSocket(addr) is executed:
   1. Check if addr is marked to be tracked
      1. If yes - create ManualWebSocketConnection instance
      2. If not - create WebSocket instance

ManualWebSocket object gives you access to tracked connections, so you can manipulate them with no need to make any changes in your application code. Also can act as a server, creating fake communication channel.

Global scope:

window.ManualWebSocket = window.MWS = window.mws;

Public API:

1. Global object:

1. mws.track

Add addresses you want to be tracked.

Can be used multiple times, each time it will add new addresses to the tracked list.

Be aware that track will not close nor replace active connection. Just next time when WebSocket will be created using given address, it will be marked as tracked.

public track: (addresses: Array<string | RegExp>): void

Example:

mws.track([address1, address2, ...]);

/* address can be string or RegExp */
mws.track(["wss://127.0.0.1:777", /other\.domain/]);

2. MWS.untrack

Remove addresses you want don't want to be tracked next time.

Be aware that untrack will not close nor replace active connection. Just next time when WebSocket will be created using given address, it won't be marked as tracked.

public untrack: (addresses: Array<string | RegExp>): void

Example:

mws.untrack([address1, address2]);

/* address can be string or RegExp */
mws.untrack(["wss://127.0.0.1:777", /other\.domain/]);

3. MWS.readyState

WebSocket ready state constants:

enum ReadyState {
  CONNECTING = 0,
  OPEN = 1,
  CLOSING = 2,
  CLOSED = 3
}

Example:

connection.readyState = mws.readyState.OPEN;

/**
 * By the way - setting a new state will trigger proper callbacks
 * For example `OPEN` will trigger `onOpen` and callbacks registered with `.on('open', ...)`
 */

4. MWS.trackedConnections

Container with all tracked connections. Exposes public interface:

public getAll(): ManualWebSocket[]
public getByUrl(url: string): ManualWebSocket | undefined
public when(url: string): Promise<ManualWebSocket>

1. trackedConnections.getAll - returns list of all active tracked connections

     public getAll(): ManualWebSocket[]

   Example:

   mws.trackedConnections.getAll().forEach(connection => {
     console.log(connection.url);
   });

2. trackedConnections.getByUrl - returns connection with given url (explicit)

   public getByUrl(url: string): ManualWebSocket | undefined

   Example:

   const connection = mws.trackedConnections.getByUrl("wss://127.0.0.1:777");

3. trackedConnections.when - returns a promise that will resolve into a valid connection. If connection already exists, will resolve immediately

   public when(url: string): Promise<ManualWebSocket>

   Example:

   const promise = mws.trackedConnections.when("wss://127.0.0.1:777")
   
   // or
   mws.trackedConnections.when("wss://127.0.0.1:777").then(connection => {...})

5. MWS.when

Alias to mws.trackedConnections.when

6. MWS.bus

Event emitter. Will trigger callbacks upon ManualWebSocket creation - if you need to do some private business.

Example:

mws.bus.on(mws.busEvent.MANUAL_WEBSOCKET_CREATED, connection => {
  console.log("from bus");
});

// or just simply
mws.bus.on("MANUAL_WEBSOCKET_CREATED", connection => {
  console.log("from bus");
});

7. MWS.busEvent

List of events that you can subscribe to on mws.bus.

Currently there is only one event

• MANUAL_WEBSOCKET_CREATED : will run given callback with created connection (see example above)

Example:

console.log(mws.busEvent);

2. Instance of ManualWebSocketConnection:

1. connection.addServerScenario

Prepare server response for given message. Use connection.send() to trigger scenario.

public addServerScenario(clientMessage: string, callback: Function): void

Example:

const message = "some message";
connection.addServerScenario(message, (connection, message) => {
  connection.receiveMessage(messageThatServerWouldGenerate);
});

connection.send(message);

How to use it in your project?

1. Setup using module - Cypress example:

1. Install package

yarn add manual-web-socket --dev

2. Require in test

const manualWebSocket = require("manual-web-socket");

3. Inject script at the top of header section in onBeforeLoad stage. Use getScript and place it manually

cy.visit("/", {
  onBeforeLoad(win) {
    var script = win.document.createElement("script");
    script.innerText = manualWebSocket.getScript();
    win.document.head.appendChild(script);
  }
});

4. Now you'll have access to ManualWebSocket object in win scope.

2. Setup without module - raw html:

1. Download manual-web-socket.raw.js file
2. Place it on top of <head> in your index.html