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:
- Botium in a Nutshell, Part 6: E2E-Testing with Botium Box
- Run Selenium Grid and Connect to Botium Box
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:
- Node.js and NPM
- a chatbot running on a website
- 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-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:
- There maybe is some kind of click-through to actually open the chatbot
- The chatbot has an input text field, or some buttons to click (however it looks)
- The chatbot outputs reponses in some kind of list within a window (however it looks)
All those assumptions can be parameterized for adapting it to your actual chatbot website with Botium capabilities:
- WEBDRIVERIO_URL to point to the website to launch for accessing the chatbot
- WEBDRIVERIO_INPUT_ELEMENT, the Webdriver selector for the input text field
- WEBDRIVERIO_INPUT_ELEMENT_SENDBUTTON, the Webdriver selector for the "Send"-Button (if present, otherwise message to the chatbot is sent with "Enter" key)
- WEBDRIVERIO_OUTPUT_ELEMENT, the Webdriver selector for the chatbot output elements
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 WEBDRIVERIO_URL to the full URL of the website where the widget is embedded.
Currently supported:
- botbuilder_webchat_v3
- botbuilder_webchat_v4
- botbuilder_webchat_v4_10_0
For chatbots published as Dialogflow "Web Demo". Point the capability WEBDRIVERIO_URL 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 WEBDRIVERIO_URL 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:
- Whatsapp has to be already installed end registered on the phone. When using device cloud providers, this is only possible with a private device cloud.
- The contact name of the bot has to be configured (WEBDRIVERIO_CONTACT) and a first conversation has to be done manually to make it visible in the conversations view of Whatsapp.
- The language of the Whatsapp app has to be configured (WEBDRIVERIO_LANGUAGE) for naming the menu items. See profiles/whatsapp.js.
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:
- a pointer to a Javascript Function (not possible when configuration is done in botium.json file)
- the name of an NPM Package, which exports a single function
- a Javascript file name relative to the current working directory, which exports a single function (see below)
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:
- container.caps: the list of Botium capabilities. Use it like: container.caps['MY_CAP_NAME']
- container.findElement and container.findElements: mirror the Webdriver $- and $$-functions for finding HTML elements in the page, but also consider Shadow DOM
browser
The current Webdriver browser session
Pre-defined behaviour:
- Opening website url
- Wait for page title
- Setting viewport size
This has to be customized rarely.
Extension function called with arguments: container, browser
Pre-defined behaviour:
- If there are buttons configured (see WEBDRIVERIO_INPUT_NAVIGATION_BUTTONS), click them one after the other
- Waiting until the input text field is visible
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:
- Set value of text input field
- Send "Enter" or simulate button click (if WEBDRIVERIO_INPUT_ELEMENT_SENDBUTTON capability is available)
This has to be customized rarely.
Extension function called with arguments: container, browser, _msg
Pre-defined behaviour:
- Poll for new chatbot response elements
This has to be customized rarely.
Extension function called with arguments: container, browser
Pre-defined behaviour:
- Chatbot output is the text value of the chatbot response elements
This has to be customized sometimes. This extension function is responsible for extracting the chatbot output from the HTML element (as notified from the WEBDRIVERIO_RECEIVEFROMBOT 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 WEBDRIVERIO_OPTIONS 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)
- messenger_com - Facebook Messenger (experimental)
- dialogflow_com - Google Dialogflow Web Demo
- botbuilder_webchat_v3 - MS BotBuilder Webchat (v3)
- botbuilder_webchat_v4 - MS BotBuilder Webchat (v4)
- watsonpreview - IBM Watson Assistant Preview Link
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:
- For a selector starting with ! any failure will stop script execution (the default)
- For a selector starting with ? any failure will be shown in the log but script execution will continue
Clicking elements:
- Starting a selector with click: will wait for the element to be clickable and then apply a click to it
- This is also the default behaviour, if none of the other magic words is used
Magic words for elements:
- Starting a selector with waitForDisplayed: will wait for the element to be displayed
- Starting a selector with waitForClickable: will wait for the element to be clickable
- Starting a selector with waitForEnabled: will wait for the element to be enabled
- Additional parameter can be given to specify the timeout period waitForDisplayed:#button-id:5000 (waiting 5000ms for a button)
Magic words for iFrame navigation:
- Starting a selector with iframe: will switch all subsequent selectors to the iFrame selected by the selector
- Switching back to the iFrame parent can be done with the selector with iframe:parent
Magic words for Window/Tab navigation:
- Starting a selector with switch:_ will switch the context to the window/tab with the given title/url
Magic words for form field input:
- Starting a selector with setvalue: will set the value of an input field. Value and input field selector are part of the element: setvalue:value-to-set:my-field-selector
- Starting a selector with addvalue: will append the value to an input field. Value and input field selector are part of the element: addvalue:value-to-append:my-field-selector
- Starting a selector with sendkeys: will send the keys to an input field. Value and input field selector are part of the element: sendkeys:value-to-send:my-field-selector
- When using Enter as value then the Enter key will be sent instead
Magic words for Hybrid smartphone apps:
- Starting a selector with context: will switch the context to an embedded webview, for example context:webview (for a named context) or context:1 (by index)
Other magic words:
- pause:1000 will pause for 1 second (1000ms)
- dumphtml will dump the current page source to the botiumwork directory
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_BUTTONS_PAUSE 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_BUTTONS_PAUSE 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_MEDIA_PAUSE capability to pause execution for a few milliseconds to give the screen some additional time to render.
Extracting cards from the output element
- WEBDRIVERIO_OUTPUT_ELEMENT_CARD
- WEBDRIVERIO_OUTPUT_ELEMENT_CARD_KEY_ATTRIBUTE
- WEBDRIVERIO_OUTPUT_ELEMENT_CARD_PAUSE
- WEBDRIVERIO_OUTPUT_ELEMENT_CARD_TEXT
- WEBDRIVERIO_OUTPUT_ELEMENT_CARD_SUBTEXT
- WEBDRIVERIO_OUTPUT_ELEMENT_CARD_MEDIA
- WEBDRIVERIO_OUTPUT_ELEMENT_CARD_BUTTONS
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:
- On iOs the Webdriver element identifier is not unique, so you have to rely on HTML content to be unique
- If you have unique HTML content (in combination with WEBDRIVERIO_OUTPUT_ELEMENT_HASH_SELECTOR)
- If you have a unique identifier in the HTML content (in combination with WEBDRIVERIO_OUTPUT_ELEMENT_HASH_ATTRIBUTE)
- Depending on your test cases, TEXT is a safe option (if there are no loops in the conversations)
Possible values:
- HASH - use parts of the HTML output (or an HTML attribute) as identifier (most stable)
- INDEX - use the position in the output DOM as identifier (only if DOM is stable)
- TEXT - use the displayed text as identifier (fallback if none of the above possible)
- ELEMENTID - use the Webdriver element identifier (nearly unuseable)
Default: empty
If WEBDRIVERIO_OUTPUT_ELEMENT_HASH 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>
- WEBDRIVERIO_OUTPUT_ELEMENT - //div[contains(@class,'bot-message')]
- WEBDRIVERIO_OUTPUT_ELEMENT_HASH - HASH
- WEBDRIVERIO_OUTPUT_ELEMENT_HASH_SELECTOR - ./div[contains(@class,'text')]
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>
- WEBDRIVERIO_OUTPUT_ELEMENT - //div[contains(@class,'bot-message')]
- WEBDRIVERIO_OUTPUT_ELEMENT_HASH - HASH
- WEBDRIVERIO_OUTPUT_ELEMENT_HASH_SELECTOR - ../div[contains(@class,'chat-bubble')]
- WEBDRIVERIO_OUTPUT_ELEMENT_HASH_ATTRIBUTE - id
Default: empty
If WEBDRIVERIO_OUTPUT_ELEMENT_HASH 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>
- WEBDRIVERIO_OUTPUT_ELEMENT - //div[contains(@class,'bot-message')]
- WEBDRIVERIO_OUTPUT_ELEMENT_HASH - HASH
- WEBDRIVERIO_OUTPUT_ELEMENT_HASH_ATTRIBUTE - id
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
- none - no screenshots
- onbotsays - attach screenshot after each received message
- onstop - attach screenshot after conversation is ready
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.
WEBDRIVERIO_START_CHROMEDRIVER and WEBDRIVERIO_START_CHROMEDRIVER_ARGS/WEBDRIVERIO_START_CHROMEDRIVER_ADDITIONAL_ARGS
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