View on GitHub

Preceptor-webdriver

WebDriver plugin for the Preceptor test-runner and aggregator

Download this project as a .zip file Download this project as a tar.gz file

Preceptor-WebDriver (Plugin)

Preceptor client-decorator plugin to inject WebDriver (Selenium) code into testing clients, simpifying the test setup and tear-down for Selenium tests by configuring it in one centralized configuration file.

Build Status npm version

NPM

API-Documentation

Coverage Report

Table of Contents

Installation

Install this module with the following command:

npm install preceptor-webdriver

Add the module to your package.json dependencies:

npm install --save preceptor-webdriver

Add the module to your package.json dev-dependencies:

npm install --save-dev preceptor-webdriver

Usage

In your Preceptor configuration, add this plugin package-name to the plugins list in the global configurations section. Preceptor will automatically load and initialize the plugin, and this plugin will be from then on available to all tasks.

{
    // ...
    plugins: ['preceptor-webdriver']
    // ...
}

Afterwards, the Web-Driver client-decorator plugin can be configured:

{ // Preceptor task configuration
    "type": "mocha",

    // ...

    "decorator": [
        {
            "type": "webDriver", // Id of this module when registered in Preceptor

            "configuration": {
                "isolation": true, // Runs in isolation mode

                "client": { // Client configuration
                    "type": "cabbie",
                    "configuration": {
                        "mode": "sync"
                    },
                    "capabilities": {
                        "browserName": "firefox"
                    }
                },

                "server": { // Server configuration
                    "type": "selenium"
                }
            }
        }
    ],

    // ...
}

Services

This plugin provides the following services for Preceptor:

WebDriver - Client-Decorator

The WebDriver client-decorator is loaded for each Preceptor task and executes code at different stages of a tests testing lifecycle. See the Preceptor project page for more information about the testing lifecycle. This module has its own plugin management, providing different clients and servers for the Selenium testing infrastructure.

Configuration

The Web-Driver client-decorator has the following configuration options:

Example
"configuration": {
    "isolation": true,
    "server": {
        "type": "selenium",
        "configuration": {
            "port": "4444"
        },
        "timeOut": 10000
    },
    "client": {
        "type": "cabbie",
        "configuration": {
            "mode": "sync",
            "debug": true
        },
        "capabilities": {
            "browserName": "firefox",

            "acceptSslCerts": true,
            "cssSelectorsEnabled": true,
            "javascriptEnabled": true,
            "takesScreenshot": true,
            "handlesAlerts": true,
            "unexpectedAlertBehavior": 'accept'
        },
        "url": "http://127.0.0.1:4444/wd/hub"
    }
}

WebDriver Clients

Following clients are included with this module:

Any additional Web-Driver clients can be added by importing them through the Preceptor plugin manager. See the Plugin section below for more information.

Configuration

Every Web-Driver client has configuration options that are the same across all Web-Driver clients. These options are:

Example
"client": {
    "type": "cabbie",
    "configuration": {
        "mode": "sync",
        "debug": true
    },
    "capabilities": {
        "browserName": "firefox",

        "acceptSslCerts": true,
        "cssSelectorsEnabled": true,
        "javascriptEnabled": true,
        "takesScreenshot": true,
        "handlesAlerts": true,
        "unexpectedAlertBehavior": 'accept'
    },
    "url": "http://127.0.0.1:4444/wd/hub"
}
Cabbie

Cabbie is a lightweight Selenium client that supports synchronous and asynchronous testing. For more information, visit the project page at: https://github.com/ForbesLindesay/cabbie

Configuration

The web-driver client plugin exposes the following configuration options in the Preceptor client-decorator configuration:

External

This is a placeholder plugin for the Web-Driver client that will not do anything; it is just there to satisfy the client-decorators need to have a client select. This client should be used if the Preceptor testing client supplies its own Web-Driver client.

WebDriver Servers

Following servers are included in this module:

Any additional Web-Driver servers can be added by importing them through the Preceptor plugin manager. See the Plugin section below for more information.

Configuration

Every Web-Driver server has configuration options that are the same across all Web-Driver servers. These options are:

Example
"server": {
    "type": "selenium",
    "configuration": {
        "port": "4444"
    },
    "timeOut": 10000
}
BrowserStack

The browserStack server plugin will provision a Web-Driver server in the Browser-Stack cloud and will make it available to be used by the Preceptor client thorugh an url.

Configuration

For this plugin to work, it needs to supply the following configuration options:

ChromeDriver

The ChromeDriver will be started locally, connecting Preceptor clients with the local instance of the Chrome browser. There is no need for a Selenium hub when using this plugin since the ChromeDriver will function as a hub on its own. This server plugin does not add any configuration options. This server uses port '9515' for Selenium communication.

Modules required

For this plugin to work, you need to add the following modules to your package.json:

External

This is a placeholder plugin for the web-driver server; it doesn't start or stop any server. However, it provides the client with a url to connect to. The plugin first checks if an environment variable with the name SELENIUM_HUB_URL is available and uses that, otherwise it will use http://127.0.0.1:4444/wd/hub as default since it is the default address for a locally running Selenium stand-alone server. This server plugin does not add any configuration options.

GhostDriver

The GhostDriver plugin will start and stop PhantomJs with GhostDriver listening on a given port. It will also automatically set the browserName option in the client capabilities to phantomjs if none was given. The server-url will always be set to http://127.0.0.1:<port>/.

Configuration
Modules required

For this plugin to work, you need to add the following modules to your package.json:

SauceLabs

The sauceLabs server plugin will provision a Web-Driver server in the SauceLabs cloud and will make it available to be used by the Preceptor client through an url.

Configuration

For this plugin to work, it needs to supply the following configuration options:

Selenium

The selenium server plugin will start and stop the Selenium stand-alone server on the local machine.

Configuration
Modules required

For this plugin to work, you need to add the following modules to your package.json:

Coverage

The Web-Driver decorator supports coverage reporting, supplying the coverage data to Preceptor and merging the coverage reports from client and server.

Configuration

The following configuration options are available for code-coverage that is accessible through the decorator configuration as coverage:

Plugins

It is possible to add your own client- or server-plugin to this WebDriver module by using the AbstractClient or AbstractServer objects which are made available by this module. Afterwards, the plugin needs to be added to the plugins list in the global configuration section of the Preceptor configuration file. See the Preceptor project for more information on how to register a Preceptor plugin.

The following API's are available for server and client plugins (see API documentation for more information):

Client-Plugin

Server-Plugin

Example

{
    // ...
    plugins: ['preceptor-webdriver', 'preceptor-webdriver-custom']
    // ...
}

Make sure that this module is listed before your plugin module so that the WebDriver plugin is already registered when your plugin should be registered.

API-Documentation

Generate the documentation with following command:

npm run docs

The documentation will be generated in the docs folder of the module root.

Tests

Run the tests with the following command:

npm run test

The code-coverage will be written to the coverage folder in the module root.

Third-party libraries

The following third-party libraries are used by this module:

Dependencies

Dev-Dependencies

Optional-Dependecies:

License

The MIT License

Copyright 2014 Yahoo Inc.