Botium Connector for Bot Framework Direct Line 3 API
npm install botium-connector-directline3


![license]()
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!__
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
* __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
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_
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": "
"CONTAINERMODE": "directline3",
"DIRECTLINE3_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.
For finetuning the Activity object sent to your bot, you can use the UPDATE_CUSTOM logic hook. This example will add some custom values to the channelData:
#me
do some channel specific thingy ...
UPDATE_CUSTOM SET_ACTIVITY_VALUE|channelData|{"channelData1": "botium", "channelData2": "something else"}
The parameters are:
1. SET_ACTIVITY_VALUE
2. The path to the activity field
3. The value of the activity field
Another option for having full control over the activity is to use the DIRECTLINE3_ACTIVITY_TEMPLATE capability. It is a JSON structure used as a template when sending an activity to the bot.
```
...
"DIRECTLINE3_ACTIVITY_TEMPLATE": {
"channelData": {
"my-special-channel-data": "..."
}
}
...
Set the capability __CONTAINERMODE__ to __directline3__ to activate this connector.
_Note: it is advised to not add this secret to a configuration file but hand it over by environment variable BOTIUM_DIRECTLINE3_SECRET_
_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_
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.
Activity types to handle (either JSON array or comma separated list). All other activity types will be ignored.
Example: set to "message,event" (or [ "message", "event" ]) to also handle Bot Framework event activities with Botium
When using activity types other than _message_, this capability maps the activity type to the activity attribute to use as message text for Botium.
By default, for _event_ activities the _name_ attribute is used as message text, for other activity types the activity type itself.
JSON object holding the activity template used for sending activities to the bot. Can be used to hold for example channelData:
...
"DIRECTLINE3_ACTIVITY_TEMPLATE": {
"channelData": {
"kb": "demo"
}
},
...
Set to 'warning' if you want to suppress activity validation errors.
Send some activity upfront to start a session. Can be used to simulate the webchat/join event.
...
"DIRECTLINE3_WELCOME_ACTIVITY": {
"type": "event",
"name": "webchat/join",
"value": {
"language": "de-DE"
},
"channelData": {
"kb": "demo"
}
},
...