The functionality for running selenium tests was rewritten and the information presented here may no longer be completely accurate if you're using a GingerSpec 2.2.1.RC1+

In order to run selenium related features, you will need a working browser (chrome/firefox) in your local machine or you will have to specify the address of a running selenium grid/hub instance (more information here), or, the address of a selenium standalone node

Selenium features must contain the @web annotation at the very beginning. This will indicate GingerSpec to bootstrap Selenium

In windows, you may need to use quotes ('') when passing variables via maven!

mvn verify -D'it.test'='com.privalia.mytestproject.mypackage.CucumberRestIT'

• Using your own local browser
  • Running the tests
• Using selenium grid and nodes
  • Running the hub and nodes locally
    • 1) Start the hub
    • 2) Start the nodes
      • 2.1 Chrome
      • 2.2 Firefox
  • Using Docker/docker-compose
    • How do I see my tests running?
    • Stopping services
    • Using filepickers
  • Running your Selenium tests
    • 1) Use all available nodes
    • 2) Run the test with a specific browser
• Using a Selenium standalone node
  • Starting a standalone node
  • Running the tests
    • How do I see my tests running?
• Testing on mobile devices
  • Using a Selenium Grid
  • Running your feature
• Optional command line arguments when starting the browser
  • Running your browser in headless mode

Using your own local browser

This is by far the easiest way and probably the best for local development. If you have a selenium feature (remember that it should contain the @web tag at the beginning), and no other option is specified, gingerspec will try to automatically check the version of the browser installed on the host machine and download the correct webdriver binary according to the host operating system.

Running the tests

You can then, proceed to run your tests in any of the ways described in the running your tests section. For example, assuming you want to run your runner class CucumberSeleniumIT you would do:

mvn verify -Dit.test=com.privalia.myproject.mypackage.CucumberSeleniumIT

If you don't know what a runner class is, better read Structure of a Gingerspec based project first

If no browser is specified, gingerspec will try to run the tests in chrome by default (this means you should have chrome installed in your system). You can also use the variable -Dbrowser=firefox to use firefox, for example:

mvn verify -Dit.test=com.privalia.myproject.mypackage.CucumberSeleniumIT -Dbrowser=firefox

Using selenium grid and nodes

Running the hub and nodes locally

1) Start the hub

The Hub is the central point that will receive all the test requests and distribute them the right nodes. First, download the selenium server standalone jar using this link: http://selenium-release.storage.googleapis.com/3.9/selenium-server-standalone-3.9.1.jar

Open a command prompt and navigate to the directory where you copied the selenium-server-standalone file. Type the following command:

java -jar selenium-server-standalone-3.9.1.jar -role hub -maxSession 20

The hub will automatically start-up using port 4444 by default. To change the default port, you can add the optional parameter -port when you run the command. You can view the status of the hub by opening a browser window and navigating to http://localhost:4444/grid/console

2) Start the nodes

2.1 Chrome

You must first initialize the hub before starting the nodes!

Regardless of whether you want to run a grid with new WebDriver functionality, or a grid with Selenium 1 RC functionality, or both at the same time, you use the same selenium-server-standalone jar file to start the nodes. The ChromeDriver consists of three separate pieces. There is the browser itself ("chrome"), the language bindings provided by the Selenium project ("the driver") and an executable downloaded from the Chromium project which acts as a bridge between "chrome" and the "driver". This executable is called "chromedriver". You will need to download this chromedriver file from here. Choose the correct binary for your distribution and unzip it in the same folder where your selenium server standalone jar is located. Once there, execute the following:

java -Dwebdriver.chrome.driver=chromedriver -jar selenium-server-standalone-3.9.1.jar -host localhost -role node -hub http://localhost:4444/grid/register -browser browserName=chrome,version=mybrowser

For Linux systems, the ChromeDriver expects /usr/bin/google-chrome to be a symlink to the actual Chrome binary

WARNING WINDOWS USERS!

In windows, despite the node is shown as registered in the grid, it is not really available and the tests might fail. To avoid this you have to specify the full path of the driver executable in this way:

java -Dwebdriver.chrome.driver="C:\driver\chromedriver.exe" -jar selenium-server-standalone-3.9.1.jar -host localhost -role node -hub http://localhost:4444/grid/register -browser browserName=chrome,version=mybrowser

Note: The port defaults to 5555 if not specified whenever the "-role" option is provided and is not a hub.

You can also specify the specific webdriver to be used. For example (chromedriver):

Remember: the left side of browserName is not changed, is always chrome, firefox, etc. We only can change the version to distinguish the name, for example:

browserName=chrome,version=mychromebrowser2

but never browserName=chrome2,version=mychromebrowser2

You should be able to see the registered node in the hub console (http://localhost:4444/grid/console)

2.2 Firefox

The process for firefox is very similar to chrome, but instead of a chromedriver, you will need to download geckodriver, you can do it from here (for Linux users, if you are on windows or mac, choose from https://github.com/mozilla/geckodriver/releases the correct binary), unzip it in the same folder where your selenium server standalone jar is located. Once there, execute the following:

java -Dwebdriver.firefox.marionatte=geckodriver -jar /home/jose/selenium-server-standalone-3.9.1.jar -host localhost -rolnode -hub http://localhost:4444/grid/register -browser browserName=firefox,version=mybrowser2

Nodes use the port 5555 port as default, so if you want 2 or more nodes running at the same time (like chrome and firefox), you can specify a different port for each one using the flag -port <port_number> (i.e. -port 5556)

For Linux systems, the geckodriver expects /usr/bin/firefox to be the location of the actual firefox binary, so firefox must be installed in the system

Using Docker/docker-compose

Another way of initializing the selenium hub and selenium nodes is by using a docker-compose script. Take a look at the following example:

    version: '3'
    
    services:
      selenium-grid:
        image: 'privaliatech/privalia-selenium-hub:3.9.1'
        ports:
          - "4444:4444"
      selenium-chrome:
        image: 'privaliatech/privalia-selenium-chrome:64'
        depends_on:
          - selenium-grid
        environment:
          ID: 'chrome'
          SELENIUM_GRID: 'selenium-grid:4444'
        ports:
          - "5900:5900"
      selenium-firefox:
        image: 'privaliatech/privalia-selenium-firefox:60'
        depends_on:
          - selenium-grid
        environment:
          ID: 'firefox'
          SELENIUM_GRID: 'selenium-grid:4444'
        ports:
          - "5901:5900"

You can copy this example and save it in a file selenium-grid-nodes-compose.yml. Assuming you already have docker and coker-compose installed on your system, locate your terminal where the file is located and execute

docker-compose -f selenium-grid-nodes-compose.yml up -d

All services will be available via localhost, and all will have port binding to a local port in the machine. The ports that will be used for binding are:

• 4444 (Selenium hub)
• 5900 (Selenium node chrome)
• 5901 (Selenium node firefox)

So, make sure these ports are available in the host machine. Now you can head to http://localhost:4444/grid/console to see the Selenium grid console up and the nodes connected.

To execute a test:

mvn clean verify -Dit.test=com.privalia.myproject.mypackage.CucumberSeleniumIT -DSELENIUM_GRID=localhost:4444

The tests will be executed in all available browsers. You can also use the option -DFORCE_BROWSER to force the execution of tests in a particular browser, for example:

• -DFORCE_BROWSER=firefox_60.0 //To execute tests only if firefox browser
• -DFORCE_BROWSER=chrome_chrome //To execute tests only in chrome browser

How do I see my tests running?

On MacOSX you can open the Screen Sharing app and connect to the chrome node with the address localhost:5900 (or to the firefox node with localhost:5901). When prompted for a password, just type: "secret"

On Linux, you can install the package vncviewer and type in the terminal:

vncviewer localhost:5900

(when prompted for a password, just type: "secret"). You can also install a graphical tool such as remote desktop client and proceed much like in OSX

Stopping services

To terminate all services just execute in the terminal (in the same folder where this file is located)

docker-compose -f selenium-grid-nodes-compose.yml down

Using filepickers

A filepicker is a web element that allows a user to upload files to the remote server and that usually consists on a button that, upon pressed, opens a dialog to select a file to be uploaded

Currently, when using the docker-compose file from to start up selenium grid and nodes, it is not possible to assign a file to the filepicker using the step

@Then("^I assign the file in '(.+?)' to the element on index '(\\d+)'$")

However, there is a workaround for this. To make it work, some adjustments are needed in the docker-compose file. First, create a docker-compose file like the following in the root folder of your project (this is important)

    version: '3'
     
    services:
      selenium-grid:
        image: 'privaliatech/privalia-selenium-hub:3.9.1'
        ports:
          - "4444:4444"
      selenium-chrome:
        image: 'privaliatech/privalia-selenium-chrome:64'
        depends_on:
          - selenium-grid
        environment:
          ID: 'chrome'
          SELENIUM_GRID: 'selenium-grid:4444'
        ports:
          - "5900:5900"
        volumes:
          - $PWD:/home/shared

(Notice how this file includes a special mapping in the selenium-chrome container)

Once you execute the docker-compose from your project's root folder and the selenium grid and the chrome node are running, you will be able to load files in a filepicker like in the example below:

    When '1' elements exists with 'xpath://*[@id="fileToUpload"]'
    Then I type '/home/shared/src/test/resources/schemas/CAMPAIGN_Es.xls' on the element on index '0'

Running your Selenium tests

All cucumber related tests must be executed against a running hub. By default, the hub will distribute the requests between all the connected nodes

1) Use all available nodes

Unless specified, the grid will split the execution of all the tests between all available nodes. You can run your tests in the following way:

mvn verify -DSELENIUM_GRID=127.0.0.1:4444 -Dit.test=com.privalia.bo.po.CucumberTestIT.java

This will execute the features defined in the runner class CucumberTestIT.java against all available nodes connected to the hub running in 127.0.0.1:4444

2) Run the test with a specific browser

It is also possible to force the execution of a test to a specific node using the DFORCE_BROWSER flag.

First start a node (lest use privaliaTest as ID), as explaned before, for example:

docker run -d -P --name selenium-node-chrome --dns 192.168.1.1 --dns 172.16.215.110 --dns 172.16.214.1 --dns 172.16.214.2 -e ID=myBrowser -e SELENIUM_GRID=10.136.180.122 privalia-selenium-chrome:64

Now, to force the execution of a particular test to that node, you must pass the parameter FORCE_BROWSER in the following way:

FORCE_BROWSER=<browserName>_<ID>

Where:

• browserName: The name of the browser. By default, the images based on google chrome use "chrome" as browserName. This can even be seen in the configuration tab of the browser
• ID: the ID given to the node when it was created (in this particular example, ID=myBrowser)

Wrapping up, the final command to force the execution of a test in a particular browser will be:

mvn verify -DSELENIUM_GRID=127.0.0.1:4444 -DFORCE_BROWSER=chrome_myBrowser -Dit.test=com.privalia.bo.po.CucumberTestIT.java -DlogLevel=DEBUG

Using a Selenium standalone node

Starting a standalone node

Using a single standalone node is another way of executing your selenium tests. Instead of running 2 or more separate processes (a hub and one or more selenium nodes), you can just run 1 single standalone node.

The easiest way is using a docker image, for example, use the following command to run a standalone chrome node:

docker run -d -p 4444:4444 -p 5900:5900 -v /dev/shm:/dev/shm selenium/standalone-chrome-debug:3.141.59-selenium

or a firefox standalone node

docker run -d -p 4444:4444 -p 5901:5900 -v /dev/shm:/dev/shm selenium/standalone-firefox-debug:3.141.59-selenium

This will start the standalone node in http://127.0.0.1:4444. You can open that address in the browser to see the selenium console

(you can head over to https://github.com/SeleniumHQ/docker-selenium for more information about)

Running the tests

If the library does not find any reference to SELENIUM_GRID, it will, by default, try to connect to a selenium standalone node in 127.0.0.1:4444 (the library also defaults to use chrome). This means, that if you already have your chrome standalone node running in localhost (as explained above), you can use the following command to run your tests:

mvn verify -Dit.test=com.privalia.myproject.mypackage.CucumberSeleniumIT

However, you can use the variables SELENIUM_NODE and SELENIUM_NODE_TYPE to easily change this default configuration in the following way

• SELENIUM_NODE: url and port of where the standalone node is running
• SELENIUM_NODE_TYPE: Browser type the node is running (it can be chrome/firefox/phantomjs/iphone/safari/android)

mvn verify -Dit.test=com.privalia.myproject.mypackage.CucumberSeleniumIT -DSELENIUM_NODE=127.0.0.1:4444 -DSELENIUM_NODE_TYPE=chrome

How do I see my tests running?

On MacOSX you can open the Screen Sharing app and connect to the chrome node with the address localhost:5900 (or to the firefox node with localhost:5901). When prompted for a password, just type: "secret"

On Linux, you can install the package vncviewer and type in the terminal:

vncviewer localhost:5900

(when prompted for a password, just type: "secret"). You can also install a graphical tool such as remote desktop client and proceed much like in OSX

Testing on mobile devices

You can also run your selenium tests in the browser of a mobile device (like Chrome on Android, or Safari in iOS)

Using a Selenium Grid

For this, you will be connecting your emulated devices to a selenium grid (like if the mobile devices were just another type of node). The process is basically the same as the described here, but when creating the node configuration file, you won't have to provide an "app" capability, but a "browserName" capability instead.

For Android

{
    "capabilities": [
        {
            "maxInstances": 1,
            "platformName": "Android",
            "automationName": "UiAutomator2",
            "deviceName": "Android Emulator",
            "browserName": "Chrome"
        }
    ],
    "configuration": {
        "cleanUpCycle": 2000,
        "timeout": 30000,
        "proxy": "org.openqa.grid.selenium.proxy.DefaultRemoteProxy",
        "url": "http://127.0.0.1:4723/wd/hub",
        "maxSession": 1,
        "register": true,
        "registerCycle": 5000,
        "hubPort": 4444,
        "hubHost": "127.0.0.1",
        "hubProtocol": "http",
        "role": "node"
    }
}

Run the file using Appium in the following way (notice the "--allow-insecure chromedriver_autodownload", this is to indicate Appium to automatically download the correct chromedriver for the chrome version installed on your device)

appium -p 4723 --nodeconfig nodeconfig-android.json --allow-insecure chromedriver_autodownload

For iOS

{
    "capabilities": [
        {
            "maxInstances": 1,
            "platformName": "iOS",
            "automationName": "XCUITest",
            "deviceName": "iPhone 8",
            "browserName": "Safari"
        }
    ],
    "configuration": {
        "cleanUpCycle": 2000,
        "timeout": 30000,
        "proxy": "org.openqa.grid.selenium.proxy.DefaultRemoteProxy",
        "url": "http://127.0.0.1:4733/wd/hub",
        "maxSession": 1,
        "register": true,
        "registerCycle": 5000,
        "hubPort": 4444,
        "hubHost": "127.0.0.1",
        "hubProtocol": "http",
        "role": "node"
    }
}

Run the file using Appium in the following way

appium -p 4733 --nodeconfig nodeconfig-ios.json

You should see your devices listed as a node in the grid console :)

Running your feature

Run the tests in exactly the same way as described earlier here

Optional command line arguments when starting the browser

Sometimes, you may need to provide specific command-line arguments when starting your browser. For example, in the case of Google Chrome, you would do something like the following in Java code:

   ChromeOptions options = new ChromeOptions();
   options.setArguments(
      "load-extension=/path/to/unpacked_extension",
      "allow-outdated-plugins");

You can add those parameters when running your tests in the following way

mvn verify -Dit.test=com.privalia.myproject.mypackage.CucumberSeleniumIT -DSELENIUM_ARGUMENTS=load-extension=/path/to/unpacked_extension;allow-outdated-plugins

Running your browser in headless mode

For running chrome or firefox in headless mode (without graphical user interface) you can use the "--headless" argument:

mvn verify -Dit.test=com.privalia.myproject.mypackage.CucumberSeleniumIT -DSELENIUM_ARGUMENTS=--headless