Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
434 lines (293 sloc) 18.4 KB

Botium Connector for WebdriverIO scripts

NPM

Codeship Status for codeforequity-at/botium-connector-webdriverio npm version license

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:

How it works ?

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:

Requirements

  • Node.js and NPM
  • a chatbot running on a website
  • a project directory on your workstation to hold test cases and Botium configuration

Install Botium and Webdriver IO Connector

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

Preparation Steps: Selenium server

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 small PhantomJS server.

Installing and starting the Selenium server (with Chrome, Edge, Firefox)

As a starter, this repository includes scripts for installing and starting a Selenium server with the help of selenium-standalone-package.

Preparation

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.

Start the integreated Selenium server

To automatically start the integrated Selenium server when Botium is executing, use the WEBDRIVERIO_START_SELENIUM capability (see below).

Start the Selenium server from command line

> npm run selenium

With this running Selenium server you can now run the Botium samples.

Installing and starting the Phantomjs server

As a very small replacement you can also start with Phantomjs, a headless browser. You won't need a separate Selenium installation in this case.

Using the integrated PhantomJS server

Setting the capability "WEBDRIVERIO_START_PHANTOMJS" to true will make Botium start an integrated PhantomJS automatically (and stop it afterwards).

Starting a separate Phantomjs server

After cloning the repository (see above), just run this command to start PhantomJS server:

> npm run phantomjs

You can run the Botium samples with this PhantomJS server now - but be aware that some websites don't work well with PhantomJS.

Preparation Steps: Analyze Chatbot Widget

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.

botbuilder_webchat_(version) - Microsoft Bot Framework Webchat

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

dialogflow_com - Dialogflow Web Demo Chatbot

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

messenger_com - Facebook Messenger Chatbot (experimental)

For chatbots published in Facebook Messenger.

  • Point the capability WEBDRIVERIO_URL to the full URL of the chatbot page (for example: "https://www.messenger.com/t/1271293572983985").
  • Additionally, set the capabilities WEBDRIVERIO_USERNAME and WEBDRIVERIO_PASSWORD to your Facebook credentials

Customize pre-defined Selenium Scripts

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)
  • Javascript code to be compiled and executed (see below)

Placing code in a Javascript file

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 = (container, browser) => {
 return browser.waitForVisible('.cc-btn', 20000)
 .click('.cc-btn')
 .pause(2000)
 .waitForVisible('#StartChat', 20000)
 .click('#StartChat')
 .waitForVisible('#chat', 10000)
 .waitForVisible('#textInput', 10000)
 .waitForVisible('.from-watson', 10000)
}

Placing code in a capability as String

When placing the code in a string capability, make sure to assign a Promise to the result variable. The parameters handed over to the function are described below.

result = browser.waitForVisible('.cc-btn', 20000)
 .click('.cc-btn')
 .pause(2000)
 .waitForVisible('#StartChat', 20000)
 .click('#StartChat')
 .waitForVisible('#chat', 10000)
 .waitForVisible('#textInput', 10000)
 .waitForVisible('.from-watson', 10000)

The capabilities representing the extension points are:

WEBDRIVERIO_OPENBROWSER

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

WEBDRIVERIO_OPENBOT

Pre-defined behaviour:

  • Waiting until the input text field is visible

This has to be customized often - 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

WEBDRIVERIO_SENDTOBOT

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

WEBDRIVERIO_RECEIVEFROMBOT

Pre-defined behaviour:

  • Poll for new chatbot response elements

This has to be customized rarely.

Extension function called with arguments: container, browser

WEBDRIVERIO_GETBOTMESSAGE

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

Webdriver Settings (Select Browser)

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": {	
        "desiredCapabilities": {
          "browserName": "chrome"      
        }
      }
      ...
    }
  }
}

This example selects the cloud device provider Saucelabs:

{
  "botium": {
    "Capabilities": {
      ...
      "WEBDRIVERIO_OPTIONS": {
        "desiredCapabilities": {
          "deviceName": "Samsung Galaxy S6 GoogleAPI Emulator",
          "platformName": "Android",
          "platformVersion": "7.0",
          "browserName": "Chrome",
          "name": "Banking Chatbot Tests",
          "tags": "botium, chatbot",
          "username": "xxx",
          "accessKey": "xxxxx"
        },
        "host": "ondemand.saucelabs.com",
        "port": 80
      },
      ...
    }
  }
}

Running the samples

> cd samples/dialogflow
> npm install && npm test

(This sample will use the integrated PhantomJS server)

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.

Supported Capabilities

Set the capability CONTAINERMODE to webdriverio to activate this connector.

WEBDRIVERIO_OPTIONS

The Webdriver.io-Options (see above)

WEBDRIVERIO_URL

The url to open in the browser

WEBDRIVERIO_VIEWPORT_SIZE

Set browser view port size to dimensions Example:

...
WEBDRIVERIO_VIEWPORT_SIZE: { width: 1280, height: 768 },
...

WEBDRIVERIO_PROFILE

Choose pre-defined Selenium scripts (see above)

  • botbuilder_webchat - Microsoft Bot Framework Webchat
  • dialogflow_com - Dialogflow Web Demo Chatbot
  • messenger_com - Facebook Messenger Chatbot (experimental)

WEBDRIVERIO_OPENBROWSER

Extension function to start up the browser (see above)

WEBDRIVERIO_OPENBOT

Extension function to navigate to the chatbot and/or make the chatbot visible after opening the url in the browser (see above)

WEBDRIVERIO_OPENBOTPAUSE

Pause execution for given amount of milliseconds after the chatbot is visible (maybe waiting for initialization)

WEBDRIVERIO_SENDTOBOT

Extension function to send a message to the chatbot (see above)

WEBDRIVERIO_RECEIVEFROMBOT

Extension function to gather chatbot response (see above)

WEBDRIVERIO_GETBOTMESSAGE

Extension function to extract the message from the chatbot response element (see above)

WEBDRIVERIO_INPUT_ELEMENT

Webdriver selector for the input text field

WEBDRIVERIO_INPUT_ELEMENT_VISIBLE_TIMEOUT

Default: 10000ms (10 sec)

Wait for the input element to become visible. If not visible within this amount of milliseconds, test fails.

WEBDRIVERIO_INPUT_ELEMENT_SENDBUTTON

Simulate button click for sending a text message (if not set: Enter key is simulated)

WEBDRIVERIO_INPUT_ELEMENT_BUTTON

Default: //button[contains(text(),'{{button.text}}')][last()] | //a[contains(text(),'{{button.text}}')][last()]

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}']

WEBDRIVERIO_OUTPUT_ELEMENT

Webdriver selector for the chatbot output elements

WEBDRIVERIO_OUTPUT_ELEMENT_TEXT and WEBDRIVERIO_OUTPUT_ELEMENT_TEXT_NESTED

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

WEBDRIVERIO_OUTPUT_ELEMENT_BUTTONS and WEBDRIVERIO_OUTPUT_ELEMENT_BUTTONS_NESTED

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.

WEBDRIVERIO_OUTPUT_ELEMENT_MEDIA and WEBDRIVERIO_OUTPUT_ELEMENT_MEDIA_NESTED

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

WEBDRIVERIO_OUTPUT_ELEMENT_DEBUG_HTML

Default: false

Print the output element HTML content to the debug stream. Important for development phase, to actually see what Botium is receiving.

WEBDRIVERIO_IGNOREUPFRONTMESSAGES

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

WEBDRIVERIO_IGNOREWELCOMEMESSAGES

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.

WEBDRIVERIO_IGNOREEMPTYMESSAGES

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.

WEBDRIVERIO_USERNAME and WEBDRIVERIO_PASSWORD

Login data if required - messenger_com-profile requires Facebook login.

WEBDRIVERIO_SCREENSHOTS

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

WEBDRIVERIO_START_SELENIUM and WEBDRIVERIO_START_SELENIUM_OPTS

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_PHANTOMJS and WEBDRIVERIO_START_PHANTOMJS_ARGS

Default: false

Default args: --webdriver=4444

Start the integrated PhantomJS server automatically

You can’t perform that action at this time.