Botium Core

Botium Core provides the underlying testing engine, but to interact with specific chatbot technologies (frameworks, APIs, SDKs, or cloud services), you must use Connectors.

Connectors act as the bridge between Botium and your chatbot. Each connector typically includes sample configurations and scripts to facilitate setup. You can find various connectors hosted on GitHub.

Botium Core can launch an inbound endpoint using an integrated HTTP server. This allows you to send input to a bot and wait for both synchronous and asynchronous responses.

To use this method:

1. Start your chatbot endpoint (e.g., node jokebot.js).
2. Run the Botium script using a configuration file that defines the inbound endpoint (e.g., BOTIUM_CONFIG=botium-inbound.json node botiumFluent.js).

# 1. Start the chatbot
node jokebot.js

# 2. Start the Botium script with the inbound config
BOTIUM_CONFIG=botium-inbound.json node botiumFluent.js

To execute the custom connector sample project, install the necessary dependencies using npm install and then run the test suite using npm test.

$ npm install
$ npm test

You can use a Redis-based inbound endpoint where the Botium CLI launches an inbound proxy and Botium Core connects to a shared Redis topic. This requires a running Redis server.

To use this method:

1. Start a local Redis server.
2. Launch the inbound proxy using the Botium CLI: botium-cli inbound-proxy.
3. Start your chatbot and connect it to the Botium CLI inbound endpoint (e.g., node jokebot.js).
4. Run the Botium script using a configuration file that targets the Redis endpoint (e.g., BOTIUM_CONFIG=botium-redis.json node botiumFluent.js).

# 1. Start Redis server

# 2. Start the inbound proxy via Botium CLI
botium-cli inbound-proxy

# 3. Start the chatbot
node jokebot.js

# 4. Start the Botium script with the Redis config
BOTIUM_CONFIG=botium-redis.json node botiumFluent.js

To execute an asserter during a test, use its defined ref followed by arguments separated by the pipe | character. You can trigger asserters at three specific lifecycle points using these keywords:

• #begin: Before the conversation starts.
• #bot: After a bot response (on step).
• #end: After the conversation is finished.

Syntax: [KEYWORD] [REF] [ARG1] | [ARG2] | ...

#begin
DUMMY arg1 | arg2 | arg3

#me
hi

#bot
Hello!
DUMMY argA | argB

#end
DUMMY argX | argY

Botium Box provides an integrated inbound endpoint secured with an API key.

To use this method:

1. Launch your chatbot (e.g., node jokebot.js).
2. In Botium Box, register the endpoint by importing the _botium-box.json_ file.
3. Update the callbackUri within that file to include a valid API Key from Botium Box.

# 1. Launch the chatbot
node jokebot.js

# 2. Import _botium-box.json_ into Botium Box and update callbackUri with your API Key

This sample demonstrates a Botium connector that uses polling to interact with an HTTP/JSON chatbot endpoint. The included demo chatbot (jokebot.js) responds with random jokes. To run the full demonstration, you must first start the chatbot endpoint and then execute the Botium script.

# 1. Start the chatbot endpoint
node jokebot.js

# 2. Start the Botium script to send input and poll for responses
node botiumFluent.js

Botium allows configuration through environment variables following specific naming conventions:

• Capabilities: Any environment variable starting with BOTIUM_ (e.g., BOTIUM_PROJECTNAME) is treated as a capability.
• Sources: If a BOTIUM_ variable matches a known source key (e.g., BOTIUM_LOCALPATH), it is applied to the sources object.
• Environment Variables: Variables starting with BOTIUM_ENV_ are mapped to the driver's envs object. For example, BOTIUM_ENV_DATABASE_URL=localhost results in envs.DATABASE_URL = 'localhost'.

Note: If BOTIUM_CONFIG is set, the driver will attempt to load configuration from that specific JSON file and its associated .local.json or environment-specific variants.

You can pass parameters to a specific conversation step using a special logic hook named CONVO_STEP_PARAMETERS. These parameters can be provided as a JSON string in the first argument or as key-value pairs separated by colons in subsequent arguments.

These parameters are merged with globalConvoStepParameters (defined in a begin step) and are available to the step's execution context.

// Example of a step with parameters in a JSON conversation format
{
  "sender": "bot",
  "messageText": "Hello",
  "logicHooks": [
    {
      "name": "CONVO_STEP_PARAMETERS",
      "args": ["stepTimeout:5000", "ignoreNotMatchedBotResponses:true"]
    }
  ]
}

A conversation is composed of ConvoStep objects. Each step defines an interaction and can have several properties:

• sender: Determines the role of the step. Valid values are me (user input), bot (expected bot response), begin (setup), end (teardown), or include (importing other conversations).
• messageText: The text content for the step.
• sourceData: Used for asserting against non-textual data (e.g., JSON objects).
• not: A boolean flag. If true, the step asserts that the expected condition/message did not occur.
• optional: A boolean flag. If true, the step will not cause the entire conversation to fail if the assertion fails or if the bot does not respond (it will be skipped instead).
• asserters: A list of assertions to perform on the step.
• logicHooks: Custom logic to execute during the step.
• userInputs: Specific user input actions to perform.

By default, this module sends anonymous installation information (operating system, architecture, and library version) to the Botium server to assist in project improvement.

You can disable this tracking by setting the BOTIUM_ANALYTICS_ environment variable to false before installing the package.

export BOTIUM_ANALYTICS_=false
npm install botium-core