Supports running Botium scripts on Websites with Webdriver, backed by a Selenium server.
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!
This is technical documentation on a rather low level. As introduction to E2E-Testing with Botium, here are are links to some articles you should read first:
With Version 0.2.0 of this connector we switched from Webdriver 4 to Webdriver 5. To continue using Webdriver 4 with your Selenium scripts, use the NPM package botium-connector-webdriverio4 instead of botium-connector-webdriverio.
Botium uses the Webdriver.io library to run conversations against a chatbot running on a website.
It can be used as any other Botium connector with all Botium Stack components:
When using Botium CLI:
> npm install -g botium-cli
> npm install -g botium-connector-webdriverio
> botium-cli init
> botium-cli run
When using Botium Bindings:
> npm install -g botium-bindings
> npm install -g botium-connector-webdriverio
> botium-bindings init mocha
> npm install && npm run mocha
When using Botium Box:
Already integrated into Botium Box, no setup required
An installed and running Selenium server is required. If you don't have a Selenium server already installed (or access to a cloud based Selenium server like Saucelabs), you can use the scripts in this repository as a starter to either install a full-blown Selenium server, or just a headless Chrome browser.
As a starter, this repository includes scripts for installing and starting a Selenium server with the help of selenium-standalone-package.
First, you have to install a recent Java Runtime Environment - see here for required versions. An of course, you need Node.js and Git client.
Clone the repository:
> git clone https://github.com/codeforequity-at/botium-connector-webdriverio.git
Install requirements, Selenium server and drivers for the most common browsers
> npm install
> npm run selenium-install
It downloads and installs the latest webdrivers for common browsers. Maybe you will have to install a previous version of the webdriver for a browser, in case you havn't installed the latest version of the browser - this is possible, but out of scope for this documentation, please consult the selenium-standalone-documentation.
Note: in case of troubles with Selenium installation, this project is not the right place to ask, as it is almost surly a problem with Selenium, not with Botium.
To automatically start the integrated Selenium server when Botium is executing, use the WEBDRIVERIO_START_SELENIUM capability (see below).
> npm run selenium
With this running Selenium server you can now run the Botium samples.
As a very small replacement you can also start with headless Chrome browser. You won't need a separate Selenium installation in this case.
Setting the capability "WEBDRIVERIO_START_CHROMEDRIVER" to true will make Botium start an integrated Chrome automatically (and stop it afterwards).
ATTENTION The version of the included chromedriver in this repository may not match your installed version - the error output is something like this:
This version of ChromeDriver only supports Chrome version XX
In this case you will either have to install the requested Chrome version, our have to update the chromedriver library to match your Chrome version. If you have Chrome 83.xxx installed, you can do this:
> npm install chromedriver@83 --no-save
If you ever worked with Selenium, you are aware that writing an automation script usually is a time-consuming task. This Botium connector helps you in writing automation scripts for a chatbot widget embedded on a website and speeds up the development process by making reasonable assumptions:
All those assumptions can be parameterized for adapting it to your actual chatbot website with Botium capabilities:
If there are additional steps (mouse clicks) to do on the website before the chatbot is accessible, you will have to extend the pre-defined Selenium scripts with custom behaviour (see below).
For some common chatbot widgets and websites, Botium provides out-of-the-box Selenium scripts by setting the Botium capability __WEBDRIVERIO_PROFILE__ to one of the pre-defined Selenium scripts.
For chatbots published with the Bot Framework Webchat Widget. Point the capability _WEBDRIVERIOURL to the full URL of the website where the widget is embedded.
Currently supported:
For chatbots published as Dialogflow "Web Demo". Point the capability _WEBDRIVERIOURL to the full URL of the embedded Dialogflow Web Demo (for example: "https://console.dialogflow.com/api-client/demo/embedded/d388ac41-5c60-483f-b89b-0ec0d99d848d").
For Watson Assistant chatbots published as Preview Link. Point the capability _WEBDRIVERIOURL to the full URL of the chatbot page (for example: "https://assistant-chat-eu-de.watsonplatform.net/web/public/xxxxxxx").
Whatsapp is started via Appium, a contact is opened, the chat history with this contact is cleared and the conversation is run.
Some caveats:
While the pre-defined Selenium scripts make reasonable assumptions, it is not unusual that your chatbot widget and your website has some very special behaviour to address. In those cases, there are some Selenium- and Node.js-Coding skills required.
Customization is done by injection Node.js-Code into Botium. The code to executed is injected by providing a capability to Botium. The capability can contain:
See botium.json in the samples/custom folder for examples
When placing code in a Javascript file, make sure to export exactly one function. The function has to return a Promise. The parameters handed over to the function are described below.
module.exports = async (container, browser) => {
const startChat = await browser.$('#StartChat')
await startChat.waitForClickable({ timeout: 20000 })
await startChat.click()
}
container
Has references to:
browser
The current Webdriver browser session
Pre-defined behaviour:
This has to be customized rarely.
Extension function called with arguments: container, browser
Pre-defined behaviour:
This has to be customized in most cases - for example, to click away the typical "Cookie"-warning from a website, clicking on the chatbot button at the bottom right of the website, ...
The samples/custom folder has an example for this scenario.
Extension function called with arguments: container, browser
Pre-defined behaviour:
This has to be customized rarely.
Extension function called with arguments: container, browser, _msg
Pre-defined behaviour:
This has to be customized rarely.
Extension function called with arguments: container, browser
Pre-defined behaviour:
This has to be customized sometimes. This extension function is responsible for extracting the chatbot output from the HTML element (as notified from the _WEBDRIVERIORECEIVEFROMBOT function) and converting it to a Botium message.
Extension function called with arguments: container, browser, elementId
Configuration of the Webdriver and Selenium is not done by Botium itself, but by passing on the content of the capability _WEBDRIVERIOOPTIONS to Webdriver.io.
This example selects Chrome browser:
{
"botium": {
"Capabilities": {
...
"WEBDRIVERIO_OPTIONS": {
"capabilities": {
"browserName": "chrome"
}
}
...
}
}
}
This example selects the cloud device provider Saucelabs:
{
"botium": {
"Capabilities": {
...
"WEBDRIVERIO_OPTIONS": {
"capabilities": {
"deviceName": "Samsung Galaxy S6 GoogleAPI Emulator",
"platformName": "Android",
"platformVersion": "7.0",
"browserName": "Chrome",
"name": "Banking Chatbot Tests",
"tags": "botium, chatbot",
"username": "xxx",
"accessKey": "xxxxx"
},
"hostname": "ondemand.saucelabs.com",
"port": 80
},
...
}
}
}
> cd samples/dialogflow
> npm install && npm test
(This sample will use the a headless Chrome brwoser)
Check the botium.json files in the sample directories for setting up the browser to use for the Botium conversation. You maybe have to tune the Selenium capabilities in the botium.json file - again, in case of troubles with Selenium, this project is not the right place to ask.
Set the capability CONTAINERMODE to webdriverio to activate this connector.
The Webdriver.io-Options (see above)
The url to open in the browser
The app to install. See Appium documentation
The app package and activity to test. See Appium documentation
Reset app state before testing. See Appium documentation
Depending on the Selenium infrastructure an "appium:" prefix for the Appium-specific capabilities might be required. Check the documentation of your device cloud provider or your Selenium grid.
HTTP(S) proxy settings and exception rules used between browser and internet - see here.
Sample configuration:
...
"WEBDRIVERIO_HTTP_PROXY": "my-corporate-proxy-host:some-port",
"WEBDRIVERIO_HTTPS_PROXY": "my-corporate-proxy-host:some-port",
"WEBDRIVERIO_NO_PROXY": "*.internal.addresses",
...
Set browser view port size to dimensions Example:
...
WEBDRIVERIO_VIEWPORT_SIZE: { width: 1280, height: 768 },
...
Choose pre-defined Selenium scripts (see above)
Extension function to start up the browser (see above)
Extension function to navigate to the chatbot and/or make the chatbot visible after opening the url in the browser (see above)
Pause execution for given amount of milliseconds after the chatbot is visible (maybe waiting for initialization)
Extension function to send a message to the chatbot (see above)
Extension function to gather chatbot response (see above)
Extension function to extract the message from the chatbot response element (see above)
The root element selector for chatbots hosted within a Shadow DOM
DEFAULT: 10s Implicit timeout for all element locators
A list of Webdriver selectors for clickable elements which will be clicked one after the other to navigate to the actual chatbot widget.
Optional/mandatory steps:
Clicking elements:
Magic words for elements:
Magic words for iFrame navigation:
Magic words for Window/Tab navigation:
Magic words for form field input:
Magic words for Hybrid smartphone apps:
Other magic words:
Webdriver selector for the input text field
Default: 10000ms (10 sec)
Wait for the input element to become visible. If not visible within this amount of milliseconds, test fails.
Default: false
By default, wait for input element to show up on start. Can be disabled.
Simulate button click for sending a text message (if not set: Enter key is simulated)
Default: (lowercase selection on button or hyperlink text)
Webdriver selector for selecting the button to click for the user input method BUTTON in Botium Script:
#me
BUTTON ClickMe
By default, a button or a hyperlink showing the given text is selected, this should match most use cases. The capability is a Mustache template and filled with the button text given in BotiumScript.
For example, if you want to select the button to click based on the title attribute, use this Webdriver selector:
button[title*='{{button.text}}']
In some situations it might be required after a user input to wait for a short amount of time to wait for the user interface. In this case you can use this capability to specify an amount of milliseconds to pause execution shortly.
Webdriver selector for the chatbot output elements
Webdriver selector for selecting the text portion within the identified output elements - default behaviour is to just get the displayed text
If the selector is relative to the identified WEBDRIVERIO_OUTPUT_ELEMENT, set WEBDRIVERIO_OUTPUT_ELEMENT_TEXT_NESTED to true (default).
Default: .//button | .//a[@href]
Webdriver selector for selecting the buttons within the identified output elements - default behaviour is to read HTML buttons and hyperlinks
If the selector is relative to the identified WEBDRIVERIO_OUTPUT_ELEMENT, set WEBDRIVERIO_OUTPUT_ELEMENT_BUTTONS_NESTED to true (default). Some chatbot widgets show Quick Response Buttons as overlay, not within the DOM of the chat window - for these cases, setting this capability to false will help.
Set the _WEBDRIVERIO_OUTPUT_ELEMENT_BUTTONSPAUSE capability to pause execution for a few milliseconds to give the screen some additional time to render.
Default: empty
Webdriver selector for selecting additional buttons shown on the screen. Set the _WEBDRIVERIO_OUTPUT_ELEMENT_EXTRA_BUTTONSPAUSE capability to pause execution for a few milliseconds to give the screen some additional time to render.
Default: .//img | .//video | .//audio
Webdriver selector for selecting the media attachments within the identified output elements - default behaviour is to check for pictures, videos and audio attachments
If the selector is relative to the identified WEBDRIVERIO_OUTPUT_ELEMENT, set WEBDRIVERIO_OUTPUT_ELEMENT_MEDIA_NESTED to true (default).
Set the _WEBDRIVERIO_OUTPUT_ELEMENT_MEDIAPAUSE capability to pause execution for a few milliseconds to give the screen some additional time to render.
Extracting cards from the output element
Default: ELEMENTID
The algorithm used to calculate a unique identifier for an identified output element. By default, the Webdriver element identifier is chosen, and this works in most cases. But depending on the level of dynamic content, it might be a better approach to use the output HTML content itself as (very long) identifier. This is recommended in those cases:
Possible values:
Default: empty
If _WEBDRIVERIO_OUTPUT_ELEMENTHASH is HASH, then it is possible to specify a selector for the unique HTML content.
For instance, HTML for a bot message could look like this:
<div class="bot-message"><div class="text" id="1683949299888">Hey, meat bag!</div></div>
Or it can also select something up the DOM tree:
<div class="chat-bubble" id="1683949299888"><div class="bot-message"><div class="text">Hey, meat bag!</div></div></div>
Default: empty
If _WEBDRIVERIO_OUTPUT_ELEMENTHASH is HASH, then it is possible to specify the id attribute.
For instance, HTML for a bot message could look like this:
<div class="bot-message" id="1683949299888"><div class="text">Hey, meat bag!</div></div>
Default: false
Print the output element HTML content to the debug stream. Important for development phase, to actually see what Botium is receiving.
Default: false
If set, all chatbot responses received before first message is sent are ignored. This is for ignoring welcome messages and other things sent upfront from the chatbot (usage instructions, welcome back, ...)
Ignore a fixed number of messages received from the chatbot. For instance, if there are always 4 welcome messages displayed, set this capability to 4 to ignore them.
Default: false
If set, all recognized messages with don't include a text, buttons or media files are ignored. This is for ignoring messages without any content, for example a placeholder for a "Bot is typing" visualization.
Login data if required
Name of the contact if required (for example, in Whatsapp)
Language of the app if required (for example, to set the Whatsapp language)
Default: none
Make screenshots and include it in the Botium message
Note: when debug mode is enabled (environment variable DEBUG=botium-connector-webdriverio*) screenshots are saved to the local directory on failure
Default: false
Default opts: none (use default options)
Start the integrated Selenium server automatically.
The options are handed over to Selenium-standalone 1:1 - see here for examples how to adapt it to your driver versions.
Default: false
Default args: --port=4444 --url-base=wd/hub
Start the a headless Chrome browser automatically with the given args (WEBDRIVERIO_START_CHROMEDRIVER_ARGS). Use the WEBDRIVERIO_START_CHROMEDRIVER_ADDITIONAL_ARGS capability to add an additional arg to the default args
Default: ['--headless', '--no-sandbox', '--disable-gpu', '--disable-dev-shm-usage', '--disable-extensions']
Set the options args for chromedriver (WEBDRIVERIO_START_CHROMEDRIVER_OPTIONS). Use the WEBDRIVERIO_START_CHROMEDRIVER_ADDITIONAL_OPTIONS capability to add an additional option arg to the default option args