node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


Build Status NPM version

What's WebBot?

WebBot provides a beautiful way to automate web functional tests.

Features :

  • Works with embedded phantomjs browser, any installed usual browser, or any available selenium grid hub
  • Provides a clean frame to separate config data and scenario
  • Provides a simple command line to execute web tests, easily integrate them into a CI, and create industrial testing projects
  • Provides a browser object augmented with useful methods (see client-commands.js)

Installation :

Globally :

# npm install -g webbot
# webbot

Or local to your project :

# cd myproject
# npm install webbot --save
# $(npm bin)/webbot

How to use WebBot :

1. Create a test project :

# mkdir myproject && cd myproject

2. Create expected directory structure :

  • scenarii (this is where to place test scripts)
    • mywebtest.js
  • config (optionnal place for test scripts configurations)
    • default (default environment)
      • mywebtest.js or .json
    • live (an environment called 'live')
      • mywebtest.js or .json (will override default config)

Example of directory structure :

3. Create a web test script :

scenarii/mywebtest.js :

var chai = require('chai')
  , webbot = require('webbot')
  , expect = chai.expect
  , browser, scenario;
browser = webbot.getBrowser();
scenario = webbot.getScenario();
describe('Simple web test', function () {
  after(function (done) {
  it('should check web page title', function (done) {
      .log('Connect to %s', scenario.config.url)
      .log('Check page title : %s', scenario.config.title)
      .getTitle(function (err, value) {

4. Create test config :

config/scenarii/default/mywebtest.json :

{ "timeout": 10000 }


{ "url": "", "title": "Google" }

5. Now play :

Find available scenarii :

# webbot -f

Result :


Run a scenario :

# webbot -e live -s mywebtest

Result :

webbot:info webbot - using browser : phantomjs [platform : ANY] +0ms

Simple web test
webbot:info browser - #1 - Connect to +1s
webbot:info browser - #2 - Check page title : Google +827ms
✓ should home page (1782ms)

1 passing (2s)

Command line options :

  • --dir (-d) : base directory of scenarii and configuration files, it should respect directory structure (default : current dir)
  • --env (-e) : environnement name to use for configuration, it should be a child of config directory where to find configuration json files (example : live)
  • --scenario (-s) : scenario to execute, it should be placed under scenarii directory (example : mywebtest)
  • --options (-o) : webdriver browser options, in JSON string format, as specified in WebdriverIO remote options
  • --commands (-c) : extra client commands module to register, it should be a collection of functions to add to the browser object as specified in WebdriverIO custom commands (example : lib/myCustomCommands)
  • --loglevel (-l) : log level to enable (error|warn|info|debug|trace)

Use cases :

See log details

# webbot -e live -s mywebtest -l trace

Execute with Firefox

# webbot -e live -s mywebtest -o '{"desiredCapabilities":{"browserName": "firefox"}}'

Execute with Chrome

# webbot -e live -s mywebtest -o '{"desiredCapabilities":{"browserName": "chrome"}}'

Execute with IE 11 / VM

VM is registered to a selenium hub server

# webbot -e live -s mywebtest -o '{"desiredCapabilities":{"browserName": "internet explorer","version":"11"},"host":"","port":4445}' -l trace

Execute with extra client commands

Specified module provides functions used as extra client commands

# cd mycustomproject
# webbot -e live -s mywebtest -c lib/myCustomCommands

WebBot is mainly powered by WebdriverIO and Mocha

Enjoy !