Botium Connector for Websocket Endpoint

This is a Botium connector for testing your chatbot published on a Websocket endpoint.

Did you read the Botium in a Nutshell articles? Be warned, without prior knowledge of Botium you won't be able to properly use this library!

How it works

Botium connects to your Websocket endpoint by transforming the Botium internal message representation to match your communication protocol in both directions (user to bot, bot to user).

It can be used as any other Botium connector with all Botium Stack components:

• Botium CLI
• Botium Bindings
• Botium Box

Requirements

• Node.js and NPM
• a bot published on a Websocket endpoint
• a project directory on your workstation to hold test cases and Botium configuration

Install Botium and Websocket Connector

When using Botium CLI:

> npm install -g botium-cli
> npm install -g botium-connector-websocket
> botium-cli init
> botium-cli run

When using Botium Bindings:

> npm install -g botium-bindings
> npm install -g botium-connector-websocket
> botium-bindings init mocha
> npm install && npm run mocha

When using Botium Box:

Already integrated into Botium Box, no setup required

Connecting Websocket chatbot to Botium

Create a botium.json with the the URL of your Websocket installation in your project directory:

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "Botium Project Websocket",
      "CONTAINERMODE": "websocket",
      "WEBSOCKET_URL": "ws://127.0.0.1:2345",
      "WEBSOCKET_REQUEST_BODY_TEMPLATE": {
        "conversationId": "botium",
        "text": "{{msg.messageText}}"
      },
      "WEBSOCKET_RESPONSE_TEXTS_JSONPATH": "$.text"
    }
  }
}

To check the configuration, run the emulator (Botium CLI required) to bring up a chat interface in your terminal window:

> botium-cli emulator

Botium setup is ready.

Using a Proxy

The connector checks for the HTTPS_PROXY and HTTP_PROXY environment variables.

How to start sample

There is a simple Echo-bot included, see samples/echoserver folder. You have to start it before running the samples:

> npm install && npm run echoserver

Now you can start the included Botium samples:

> cd ./samples/echo
> npm install && npm test

Supported Capabilities

Set the capability CONTAINERMODE to websocket to activate this connector.

WEBSOCKET_URL

Websocket endpoint URL, starting with ws:// or wss://

WEBSOCKET_HEADERS_TEMPLATE

Websocket HTTP Headers

WEBSOCKET_HANDSHAKE_TIMEOUT

Default: 10000 (10 sec)

Opening handshake timeout

WEBSOCKET_START_BODY_TEMPLATE

Initial "session setup" message sent from Botium to the Websocket server, right after connecting.

WEBSOCKET_REQUEST_BODY_RAW

If set to true, the request body is sent as plain string, otherwise JSON formatting is applied.

If not given, this is automatically set to true if the WEBSOCKET_REQUEST_BODY_TEMPLATE capabilitiy is given

WEBSOCKET_REQUEST_BODY_TEMPLATE

Mustache template for converting the Botium internal message structure to the Websocket payload as required for your communication protocol.

The Mustache view contains the Botium internal message structure in the msg field, see Botium Wiki. Example:

...
"WEBSOCKET_REQUEST_BODY_TEMPLATE": {
   "conversationId": "botium",
   "text": "{{msg.messageText}}"
},
...

WEBSOCKET_RESPONSE_RAW

If set to true, the response body is handles as plain string, otherwise JSON parsing is applied.

If not given, this is automatically set to true if the WEBSOCKET_RESPONSE_TEXTS_JSONPATH capabilitiy is given. The WEBSOCKET_RESPONSE_*-JSONPath expressions are only possible if this capability is set to false.

WEBSOCKET_RESPONSE_TEXTS_JSONPATH

JSONPath expression to extract the message text from the Websocket response.

WEBSOCKET_RESPONSE_BUTTONS_JSONPATH

JSONPath expression to extract button texts from the Websocket response.

WEBSOCKET_RESPONSE_MEDIA_JSONPATH

JSONPath expression to extract media attachments from the Websocket response.

WEBSOCKET_REQUEST_HOOK

tbd

WEBSOCKET_RESPONSE_HOOK

tbd

WEBSOCKET_RESPONSE_IGNORE_EMPTY

tbd

Current Restrictions

• Only JSON data supported