Botium Connector for Bot Framework Direct Line 3 API

This is a Botium connector for testing your Microsoft Bot Framework chatbots.

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 ?

The Direct Line API 3.0, part of the Microsoft Bot Framework, enables Botium to talk to a chatbot deployed and running with the Microsoft Bot Framework.

The Direct Line version number does not correspond to the Microsoft Bot Framework version number. So this connector actually supports Microsoft Bot Framework v3 as well as v4.

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 Microsoft Bot Framework chatbot, and user account with administrative rights
• a project directory on your workstation to hold test cases and Botium configuration

Install Botium and Directline3 Connector

When using Botium CLI:

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

When using Botium Bindings:

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

When using Botium Box:

Already integrated into Botium Box, no setup required

Connecting Microsoft Bot Framework to Botium

You have to connect the Direct Line channel (with version 3.0) in Azure Portal and obtain the secret - see here for instructions.

Open the file botium.json in your working directory and add the secret:

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "directline3",
      "DIRECTLINE3_SECRET": "<directline secret>"
    }
  }
}

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, you can begin to write your BotiumScript files.

Supported Capabilities

Set the capability CONTAINERMODE to directline3 to activate this connector.

DIRECTLINE3_SECRET *

The secret for accessing your chatbot from the Azure Portal.

Note: it is advised to not add this secret to a configuration file but hand it over by environment variable BOTIUM_DIRECTLINE3_SECRET

DIRECTLINE3_DOMAIN

If not using the default Direct Line endpoint, e.g. if you are using a region-specific endpoint, put its full URL here

DIRECTLINE3_WEBSOCKET

true or false Wether to use Websocket connection or HTTP polling. Usually, using Websockets is prefered, but sometimes this is not possible (maybe with blocking proxies).

DIRECTLINE3_POLLINGINTERVAL

in milliseconds HTTP Polling interval

DIRECTLINE3_BUTTON_TYPE and DIRECTLINE3_BUTTON_VALUE_FIELD

Default type: event

Default field: name

Activity fields to use for simulating button clicks by the user. Depending on your implementation, you maybe have to change the activity type or the field to use - see here for some ideas.

Usually, the activity type is event, and the button value is submitted in the name field, but using those capabilities you can adapt it to your implementation.

Note: if you want to disable this, then set DIRECTLINE3_BUTTON_TYPE to "message" and DIRECTLINE3_BUTTON_VALUE_FIELD to "text", to make the button clicks appear as normal user text input

DIRECTLINE3_GENERATE_USERNAME

Default: false

Botium simulates conversations with username me. Depending on your implementation, running multiple conversations with the same username could make them fail (for example, session handling).

Setting this capability to true will generate a new username (uuid) for each conversation.

Open Issues and Restrictions

• Media Attachments currently cannot be sent, as Node.js environment is not fully supported by DirectLine