Manual WebSocket

Table of Contents:

1. Example
1. Motivation
1. Documentation

1. The big picture
1. Global scope
1. Public API

1. Global object

1. mws._track_ (method)
1. mws._untrack_ (method)
1. mws._readyState_ (object with constants)
1. mws._trackedConnections_ (object with methods)
1. mws.trackedConnections._getAll_ (method)
1. mws.trackedConnections._getByUrl_ (method)
1. mws.trackedConnections._when_ (method)
1. mws._when_ (method)
1. mws._bus_ (event emitter)
1. mws._busEvent_ (object with constants)

1. Instance of ManualWebSocketConnection
- WebSocket methods
- ability to change readyState by hand
- connection._addServerScenario_ (method)

1. How to use it in your project
1. Setup using module - Cypress example
1. 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
1. Tell ManualWebSocket which addresses to track
1. When new WebSocket(addr) is executed:
1. Check if addr is marked to be tracked
1. If yes - create ManualWebSocketConnection instance
1. 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.

---

$3

``js
window.ManualWebSocket = window.MWS = window.mws;
`

---

Public API:

$3

#### 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.

`js
public track: (addresses: Array): void
`

Example:

`js
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.

`js
public untrack: (addresses: Array): void
`

Example:

`js
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:

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

Example:

`js
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:

`js
public getAll(): ManualWebSocket[]
public getByUrl(url: string): ManualWebSocket | undefined
public when(url: string): Promise
`

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

`js
public getAll(): ManualWebSocket[]
`

Example:

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

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

`js
public getByUrl(url: string): ManualWebSocket | undefined
`

Example:

`js
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

`js
public when(url: string): Promise
`

Example:

`js
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:

`js
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:

`js
console.log(mws.busEvent);
`

---

$3

#### 1. connection._addServerScenario_

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

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

Example:

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

connection.send(message);
`

How to use it in your project?

$3

1. Install package

`js
yarn add manual-web-socket --dev
`

2. Require in test

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

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

`js
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.

$3

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