Botium Connector for Microsoft Copilot

This is a Botium connector for testing your Microsoft Copilot 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?

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

Install Botium and Copilot Connector

When using Botium CLI:

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

When using Botium Bindings:

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

When using Botium Box:

Already integrated into Botium Box, no setup required

Connecting Microsoft Copilot to Botium

You have to use Copilot Secret in order to connect to Copilot chatbot. See here for instructions.

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

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "copilot",
      "COPILOT_SECRET": "<copilot 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.

Finetuning Copilot Activity

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 COPILOT_ACTIVITY_TEMPLATE capability. It is a JSON structure used as a template when sending an activity to the bot.

    ...
    "COPILOT_ACTIVITY_TEMPLATE": {
      "channelData": {
        "my-special-channel-data": "..."
      }
    }
    ...

Supported Capabilities

Set the capability CONTAINERMODE to COPILOT to activate this connector.

COPILOT_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_COPILOT_SECRET

COPILOT_DOMAIN

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

COPILOT_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).

COPILOT_POLLINGINTERVAL

in milliseconds HTTP Polling interval

COPILOT_BUTTON_TYPE and COPILOT_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 COPILOT_BUTTON_TYPE to "message" and COPILOT_BUTTON_VALUE_FIELD to "text", to make the button clicks appear as normal user text input

COPILOT_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.

COPILOT_HANDLE_ACTIVITY_TYPES

Default: "message"

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 Copilot event activities with Botium

COPILOT_ACTIVITY_VALUE_MAP

default: { 'event': 'name' }

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.

COPILOT_ACTIVITY_TEMPLATE

default: {}

JSON object holding the activity template used for sending activities to the bot. Can be used to hold for example channelData:

...
"COPILOT_ACTIVITY_TEMPLATE": {
  "channelData": {
    "kb": "demo"
  }
},
...

COPILOT_ACTIVITY_VALIDATION

default: 'error'

Set to 'warning' if you want to suppress activity validation errors.

COPILOT_WELCOME_ACTIVITY

default: empty

Send some activity upfront to start a session. Can be used to simulate the webchat/join event.

...
"COPILOT_WELCOME_ACTIVITY": {
  "type": "event",
  "name": "webchat/join",
  "value": {
    "language": "de-DE"
  },
  "channelData": {
    "kb": "demo"
  }
},
...