1. Intro

In contrast to HTTP requests, WebSockets are much more quick, but also much more complicated to develop and maintain. Since there is no predefined way to check the sequence of messages, and if it even was, frquently you just don't know the exact order of them!

This application is created to solve this problem. WS Teste Engine is a tool, an HTML5 based framework for unit testing of online systems with WebSockets. To test a system, you just need to provide simple controlling code in JavaScript and run WS Testing Engine!

2. JS data files description

Any test in WS Testing Engine consists of flows (which may be considered as unit tests). And each flow may be an array or a dictionary with unit objects. If flow object is a list, all its units are run in the order of their indices by default. If flow object is a dictionary, all its units must provide next unit. Any flow object must have name as a string at 0 key, and entry unit object at 1 key. Each flow begins when previous one ends (obviously, excluding the first one).

Unit object structure:
{
    name: string,
    enter: function () {},
    task: function (ws, ref) {},
    condition: function (data) {},
    key: string,
    val: any type,
    finalise: function (ws) {},
}

All the fields are not strictly necessary. However, task may be skipped only in one case only (when a unit is entry poing of a flow; only enter returning string key of other unit must present this way), so, don't forget to add it.

Function named task of each unit is run only if previous unit object succeeded. To assert it, condition, key and val are used. So, initially task of a unit object is run, then the Controller object waits for appropriate message. But if there is no result, after specific amount of time the unit object and its flow will be failed.

Function named task can return nothing or a single dictionary or an array of dictionaries to be send as JSON (in the second case multiple messages will be sent). Also, it can set value to ref.next to change next unit.

A unit object can follow these patterns for assertion:

  • If condition is specified, it will get parsed JSON as data argument and must return bool for going to next unit or failing (if flow object is an array), or an integer or string for going to specific unit object. String or integer result will override next unit specified by task function in ref.next.

  • If both key and val are specified, then expression data[key]==val will be used to assert. Also, val may be an array, then if any of its value equals to data[key], then assertion is true.

  • If key only is specified, the value of data[key] will be used as bool.

Function named finalise is called on unit objects success. Its result is handled the same as the result of task function.

3. Other parameters

You can manage WS Testing Engine behavior widely using provided GUI. The list below describes it. By the way, most of these parameters can be set from JS data file with args object.

  • Of course, you have to provide server address (args.server from code) for WebSockets connection and JS data file. This file may be loaded from the Internet (you have to put the url and click button) or from your computer (just choose the file).

  • You can set waiting time (args.waiting_time): amount of time before unit fails if has no appropriate messafe. The value 1000 means one second.

  • You can set delay (args.delay): amount of time before between one units end and another units begin. The value 1000 means one second.

  • You can use "print messages content" checkbox. If it is set, you will see sent and received messages and come other comments.

  • You can use "split flows connections" checkbox (args.split). If it is set, each flow gets a new WebSockets connection.

4. Example files

There are plenty files ready to use and investigate WS Test Engine on practice: