This package has been deprecated

Author message:

Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

ws-testbed

ws-testbed is a WebSocket test bed for experimenting with WebSocket connections, running on Node.js, and is working on a plugin basis. Registered plugins can open and close WebSocket connections, as well as receive and send messages over established connections.

Example (echo server)

This program uses the test bed directly:

var testbed = new WebSocketTestbed();
 
testbed.on("connected", function(connectedEvent) {
  var connection = connectedEvent.connection;
 
  connection.on("received", function(receivedEvent) {
    connection.send(receivedEvent.data);
  });
});
 
testbed.serve({
  port: 30500
});

This program can be found in the examples directory.

Capabilities

WebSocket Provider

The test bed internally uses the ws library to provide WebSocket functionality. The exposed interfaces are reduced and simplified to enable simple, unified testing applications.

For example, an error event on a connection is not directly forwarded to the user, but expressed as a typical closed event - as if the connection was simply closed.

Plugin Container

Plugins are extensions to the test bed that can access the test bed as well as other plugins. A plugin provides a name and a way to set control values, and receives the reference to the test bed and a way to set monitor values.

Control values are exposed to allow other plugins or integrating applications to set parameters. The simplest usage is the internal configuration plugin, which stores and restores control values as configuration in JSON files.

Monitor values allow plugins to tell about internal states, which other plugins could interpret for monitoring purposes.

Provided Plugins

The test bed comes with a few standard plugins, allowing quick starts. They are exposed through require("ws-testbed").plugins.

intern:client

A plugin that establishes outgoing connections. Control values specify the destination and others, such as the reconnect timeout.

intern:server

A plugin that creates servers. Control values specify the server port.

intern:configuration

A plugin that can load and save control values using JSON. The plugin comes with a simple configuration store that uses a file as storage.

API in a Nutshell

See the generated documentation for details.

WebSocketTestbed

Constructor

var WebSocketTestbed = require("ws-testbed").WebSocketTestbed;
var testbed = new WebSocketTestbed();

Methods

connect(url[, options]): Requests to connect to given URL. Fires connecting event and then connected when connected. Returns the created Connection instance.

getConnectedConnections(): Returns an array of connection objects that are currently connected.

serve(options): Requests to open a server with given options. Simplest options are { port: (number) }. Fires serving event. Returns the created Server instance.

loadPlugin(pluginExports): Requests to load a plugin, described by given exports object. This object must provide methods as defined by the PluginExports interface. See the internal plugins for examples. Fires pluginLoaded event. Returns the created Plugin instance if successfull or false otherwise.

getPlugins(): Returns an array of plugin objects that are currently loaded.

Events (EventEmitter)

connecting (event): An outgoing connection is established. Event contains url, options and connection. This event is only informative, nearly nothing can be done with the connection object, other than registering for event handler.

connected (event): A connection was successfully established (either incoming or outgoing). Event contains connection. It is advised to prefer this event over connecting, because any connection will be notified.

serving (event): A server is created. Event contains server.

pluginLoaded (event): A plugin was loaded. Event contains plugin.

Connection

Connection objects are not created by the user, they are always provided by the test bed.

Methods

close(): Requests to close the connection. Will fire closed event.

send(data): Requests to send given data. Fires sending event and sent when data has been sent over the socket.

Events (EventEmitter)

closed: When the connection is no longer usable. This event is the last event to be received from a connection, and the only one if an outgoing connection could not be established.

received (event): When data has been received. Event contains data.

sending (event): When data is requested to be sent. Event contains data.

sent (event): Data has been sent over the socket. Event contains data.

Server

Connection objects are not created by the user, they are always provided by the test bed.

Methods

close(): Requests to close the server. Will fire closed event.

Events (EventEmitter)

closed: When the server is no longer usable. This event is the last event to be received from a server.

Plugin

Plugin objects are not created by the user, they are always provided by the test bed.

Methods

getName(): Returns the unique name of the plugin as provided by the PluginExports.

unload(): Requests to unload this plugin. Will fire unloaded event.

getControl(): Returns the ValueStore instance representing the control values. This plugin should register for changes while anything else is allowed to modify the values.

getMonitor(): Returns the ValueStore instance representing the monitor values. This plugin should provide the state values while anything else is allowed to register for changes.

Events (EventEmitter)

unloaded: When the plugin has been unloaded. This event is the last event to be received from a plugin. Plugins should register a handler on their own plugin to clean up any resources.

ValueStore

A ValueStore object wraps an arbitrary data structure according to a description and fires events when the data is changed.

Methods

getDescriptions(): Returns a data structure that describes the layout of the data. For control and monitor values, these descriptions were provided by the PluginExports. See below for the structure layout.

getValues(): Returns an object according to the descriptions. The returned object is a copy of the current state.

setValues(values): Sets the new values according to given parameter. The provided values should have the same layout as specified by the descriptions. Missing members will be initialized by the default values according to descriptions, Unknown members will be dropped.

Events (EventEmitter)

valuesChanged: When the data was modified. Call getValues() to retrieve the current set.

PluginExports

An object implementing this interface is provided to WebSocketTestbed.loadPlugin(). It is an intialization object for the new plugin.

Methods

getName(): Returns a unique name for the plugin. An URL type of schema is recommended.

onLoading(testbed, plugin): This method is called when the plugin is being loaded into the test bed. The provided plugin argument refers to the plugin object for this plugin. During this function, WebSocketTestbed.getPlugins() will not return the plugin instance; A pluginLoaded event will follow after this function has returned.

getControlDescriptions(descHelper): Returns an object describing the control values. If the plugin exposes no control values, the return value must be {}. The provided plugin is an instance of DescriptionHelper, which can (and should) be used to build a compatible description.

getMonitorDescriptions(descHelper): Returns an object describing the monitor values. If the plugin provides no monitor values, the return value must be {}. The provided plugin is an instance of DescriptionHelper, which can (and should) be used to build a compatible description.

ValueDescriptions

A ValueDescriptions object has an arbitrary amount of members. The value of each member must be a single value description.

Use the DescriptionHelper to build single value descriptions or see the code for the layout.

Example:

{
    value1: { /* single value description */ },
    value2: { /* single value description */ }
}

DescriptionHelper

This helper is provided to work with single value descriptions. For an example use, see the internal plugins.

Methods

getBuilder(type): Returns a builder for a single value description. Supported types are: "string", "text", "number", "boolean", "array", "object".

DescriptionBuilder

This builder can be used to create compatible single value descriptions.

Methods

build(): Builds and returns the single value description as per type. Throws an error if insufficient values were provided.

withDisplay(value): Sets the display value of the description. The display value is the one that should be shown to users for this value. Returns this.

withDefault(value): Sets the default value in case it is not provided. For arrays, value is a boolean - if true, the array value will contain one (default) instance of the specified contained type. For objects, the default must be another ValueDescriptions object.

of(valueDescription): Only supported for arrays, this sets the contained type of the array. valueDescription is a single value description.

License

The project is available under the terms of the New BSD License.