WebDriver.md

August 19, 2020 · View on GitHub

WebDriver

Extends Helper

WebDriver helper which wraps webdriverio library to manipulate browser using Selenium WebDriver or PhantomJS.

WebDriver requires Selenium Server and ChromeDriver/GeckoDriver to be installed. Those tools can be easily installed via NPM. Please check Testing with WebDriver for more details.

Configuration

This helper should be configured in codecept.json or codecept.conf.js

url: base url of website to be tested.
basicAuth: (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
browser: browser in which to perform testing.
host: - WebDriver host to connect.
port: - WebDriver port to connect.
protocol: - protocol for WebDriver server.
path: - path to WebDriver server,
restart: - restart browser between tests.
smartWait: (optional) enables SmartWait; wait for additional milliseconds for element to appear. Enable for 5 secs: "smartWait": 5000.
disableScreenshots: - don't save screenshots on failure.
fullPageScreenshots - make full page screenshots on failure.
uniqueScreenshotNames: - option to prevent screenshot override if you have scenarios with the same name in different suites.
keepBrowserState: - keep browser state between tests when restart is set to false.
keepCookies: - keep cookies between tests when restart set to false.
windowSize: (optional) default window size. Set to maximize or a dimension in the format 640x480.
waitForTimeout: sets default wait time in ms for all wait* functions.
desiredCapabilities: Selenium's desired capabilities.
manualStart: - do not start browser before a test, start it manually inside a helper with this.helpers["WebDriver"]._startBrowser().
timeouts: WebDriver timeouts defined as hash.

Example:

{
   helpers: {
     WebDriver : {
       smartWait: 5000,
       browser: "chrome",
       restart: false,
       windowSize: "maximize",
       timeouts: {
         "script": 60000,
         "page load": 10000
       }
     }
   }
}

Example with basic authentication

{
   helpers: {
     WebDriver : {
       smartWait: 5000,
       browser: "chrome",
       basicAuth: {username: 'username', password: 'password'},
       restart: false,
       windowSize: "maximize",
       timeouts: {
         "script": 60000,
         "page load": 10000
       }
     }
   }
}

Additional configuration params can be used from webdriverio website.

Headless Chrome

{
   helpers: {
     WebDriver : {
       url: "http://localhost",
       browser: "chrome",
       desiredCapabilities: {
         chromeOptions: {
           args: [ "--headless", "--disable-gpu", "--no-sandbox" ]
         }
       }
     }
   }
}

Internet Explorer

Additional configuration params can be used from IE options

{
   helpers: {
     WebDriver : {
       url: "http://localhost",
       browser: "internet explorer",
       desiredCapabilities: {
         ieOptions: {
           "ie.browserCommandLineSwitches": "-private",
           "ie.usePerProcessProxy": true,
           "ie.ensureCleanSession": true,
         }
       }
     }
   }
}

Selenoid is a modern way to run Selenium inside Docker containers. Selenoid is easy to set up and provides more features than original Selenium Server. Use selenoidOptions to set Selenoid capabilities

{
   helpers: {
     WebDriver : {
       url: "http://localhost",
       browser: "chrome",
       desiredCapabilities: {
         selenoidOptions: {
           enableVNC: true,
         }
       }
     }
   }
}

Connect Through proxy

CodeceptJS also provides flexible options when you want to execute tests to Selenium servers through proxy. You will need to update the helpers.WebDriver.capabilities.proxy key.

{
    helpers: {
        WebDriver: {
            capabilities: {
                proxy: {
                    "proxyType": "manual|pac",
                    "proxyAutoconfigUrl": "URL TO PAC FILE",
                    "httpProxy": "PROXY SERVER",
                    "sslProxy": "PROXY SERVER",
                    "ftpProxy": "PROXY SERVER",
                    "socksProxy": "PROXY SERVER",
                    "socksUsername": "USERNAME",
                    "socksPassword": "PASSWORD",
                    "noProxy": "BYPASS ADDRESSES"
                }
            }
        }
    }
}

For example,

{
    helpers: {
        WebDriver: {
            capabilities: {
                proxy: {
                    "proxyType": "manual",
                    "httpProxy": "http://corporate.proxy:8080",
                    "socksUsername": "codeceptjs",
                    "socksPassword": "secret",
                    "noProxy": "127.0.0.1,localhost"
                }
            }
        }
    }
}

Please refer to Selenium - Proxy Object for more information.

Cloud Providers

WebDriver makes it possible to execute tests against services like Sauce Labs BrowserStack TestingBot Check out their documentation on available parameters

Connecting to BrowserStack and Sauce Labs is simple. All you need to do is set the user and key parameters. WebDriver automatically know which service provider to connect to.

{
    helpers:{
        WebDriver: {
            url: "YOUR_DESIRED_HOST",
            user: "YOUR_BROWSERSTACK_USER",
            key: "YOUR_BROWSERSTACK_KEY",
            capabilities: {
                "browserName": "chrome",

                // only set this if you're using BrowserStackLocal to test a local domain
                // "browserstack.local": true,

                // set this option to tell browserstack to provide addition debugging info
                // "browserstack.debug": true,
            }
        }
    }
}

SauceLabs

SauceLabs can be configured via wdio service, which should be installed additionally:

npm i @wdio/sauce-service --save

It is important to make sure it is compatible with current webdriverio version.

Enable wdio plugin in plugins list and add sauce service:

plugins: {
   wdio: {
      enabled: true,
       services: ['sauce'],
       user: ... ,// saucelabs username
       key: ... // saucelabs api key
       // additional config, from sauce service
   }
}

See complete reference on webdriver.io.

Alternatively, use codeceptjs-saucehelper for better reporting.

BrowserStack

BrowserStack can be configured via wdio service, which should be installed additionally:

npm i @wdio/browserstack-service --save

It is important to make sure it is compatible with current webdriverio version.

Enable wdio plugin in plugins list and add browserstack service:

plugins: {
   wdio: {
      enabled: true,
       services: ['browserstack'],
       user: ... ,// browserstack username
       key: ... // browserstack api key
       // additional config, from browserstack service
   }
}

See complete reference on webdriver.io.

Alternatively, use codeceptjs-bshelper for better reporting.

TestingBot

Recommended: use official TestingBot Helper.

Alternatively, TestingBot can be configured via wdio service, which should be installed additionally:

npm i @wdio/testingbot-service --save

It is important to make sure it is compatible with current webdriverio version.

Enable wdio plugin in plugins list and add testingbot service:

plugins: {
  wdio: {
      enabled: true,
      services: ['testingbot'],
      user: ... ,// testingbot key
      key: ... // testingbot secret
      // additional config, from testingbot service
  }
}

See complete reference on webdriver.io.

Applitools

Visual testing via Applitools service

Use CodeceptJS Applitools Helper with Applitools wdio service.

Multiremote Capabilities

This is a work in progress but you can control two browsers at a time right out of the box. Individual control is something that is planned for a later version.

Here is the webdriverio docs on the subject

{
    helpers: {
        WebDriver: {
            "multiremote": {
                "MyChrome": {
                    "desiredCapabilities": {
                        "browserName": "chrome"
                     }
                },
                "MyFirefox": {
                   "desiredCapabilities": {
                       "browserName": "firefox"
                   }
                }
            }
        }
    }
}

Access From Helpers

Receive a WebDriver client from a custom helper by accessing browser property:

const { WebDriver } = this.helpers;
const browser = WebDriver.browser