Manual-web-socket NPM

Manual WebSocket

Table of Contents:

Example
Motivation
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)
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

Replace native WebSocket constructor with ManualWebSocketConnection
Tell ManualWebSocket which addresses to track
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>

trackedConnections.getAll - returns list of all active tracked connections

  public getAll(): ManualWebSocket[]

Example:

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

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");

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:

Install package

yarn add manual-web-socket --dev

Require in test

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

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);
  }
});