Running Selenium tests - veepee-oss/gingerspec GitHub Wiki

This documentation is valid for Gingerspec 2.2.1-RC2+. If you are using an older version, check the legacy documentation

Running Selenium tests is no different than running any other kind of test. You can run then using the console or you can also use your IDE to run your tests either as a cucumber java test or as a TestNG test.

If you add the web annotation to your scenarios (or features), GingerSpec will automatically create an appropriate driver for running the different steps in the scenario. This driver will be automatically closed at the end of the scenario and it can be further configured using VM arguments.

@web
Feature: Testing basic functionality of a web page

    Scenario: Fill the form and click the submit button
        Given I go to 'http://demoqa.com/text-box'
        And I type 'John' on the element with 'id:userName'
        And I type '[email protected]' on the element with 'id:userEmail'
        And I type '123 fake address' on the element with 'id:currentAddress'
        When I scroll down until the element with 'id:submit' is visible
        And I click on the element with 'id:submit'
        Then at least '1' elements exists with 'id:output'

In case you would like to go deeper into the subject, using the @web annotation indicates GingerSpec to execute a special Cucumber hook located in the HookGSpec class. This hook is responsible for initializing the driver

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 you can choose to directly run all your scenarios with @web annotation like this

mvn verify -Dcucumber.filter.tags="@web"

Or you can also run directly the runner class:

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

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

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

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

Configuring the driver

Gingerspec allows you to configure certain capabilities for the initialization of the driver, specifically, the ones used by selenium for browser selection

  • browserName: If not specified will default to chrome. Possible values are chrome, opera, MicrosoftEdge, ie, firefox, phantomjs and safari
  • platform: Empty by default, not included in the capabilities when using the local browser. Possible values are WINDOWS, XP, VISTA, MAC, LINUX, UNIX, ANDROID}. When requesting a new session, the client may specify ANY to indicate any available platform may be used
  • version: Not included by default. If not specified will select any browser available.

So, for running the tests using Firefox, you can use:

mvn verify -Dcucumber.filter.tags="@web" -DbrowserName=firefox

Passing arguments to the browser

You can also pass certain arguments when initializing the browser or also called "command line switches". For this, you must use the VM option -DSELENIUM_ARGUMENTS. Each argument should be separated by ";".

mvn verify -Dcucumber.filter.tags="@web" -DSELENIUM_ARGUMENTS=argument1;argument2;....argumentn

By default, --ignore-certificate-errors and --no-sandbox arguments are applied

For example, if you want the browser to start maximized, you can use the argument "--start-maximized"

mvn verify -Dcucumber.filter.tags="@web" -DSELENIUM_ARGUMENTS=--start-maximized

Or you can also start the browser in headless mode

mvn verify -Dcucumber.filter.tags="@web" -DSELENIUM_ARGUMENTS=--headless

If you're interested, check out the command line switches for chrome

This is currently only supported for chrome, opera and firefox

Using a Selenium Grid/Selenium Standalone Nodes

Gingerspec can also work with Selenium grid and Selenium standalone nodes. In the official web page you can find extensive documentation for you to create your own implementation , or, even better, use the official docker images

You can use the argument -DSELENIUM_GRID to indicate GingerSpec the URL of the Selenium Grid/Standalone Node. So, assuming you have a Selenium grid running at 'http://localhost:4444/wd/hub':

mvn verify -Dcucumber.filter.tags="@web" -DSELENIUM_GRID=http://localhost:4444/wd/hub

You can also pass any of the given capabilities (browserName, platform, version), to select an specific node in the grid You must specify the full URL of the Selenium grid/standalone node

Using extra capabilities

When you make use of the @web annotation in your scenarios/features, GingerSpec will try its best to construct a set of capabilities. These capabilities are usually the minimum set necessary to initialize the driver (browserName, platform, and version). You can further configure any of these basic capabilities using the corresponding VM arguments as mentioned before (-DbrowserName, -Dplatform, -Dversion). This is usually, more than enough when you're are running your tests locally or in a selenium grid.

However, when you're running your tests with a Selenium grid or with a selenium standalone node, you can also pass a set of capabilities as a JSON file

So, assuming you have the following capabilities.json file:

{
  "platform": "ANY",
  "browserName": "chrome",
  "chromeOptions": {
    "args": ["start-fullscreen", "incognito", "disable-extensions", "test-type"],
    "w3c": false
  }
}

You can indicate GingerSpec to use those capabilities when initializing the driver like this:

mvn verify -Dcucumber.filter.tags="@web" -DSELENIUM_GRID=http://localhost:4444/wd/hub -DCAPABILITIES=/path/to/capabilities.json

Advance debugging with screenshots

When an scenario that is using the @web annotation fails, GingerSpec automatically takes a screenshot of the web page, alongside the page's html source code. This becomes really handy for detecting the cause of the issue when you are unable to see for yourself the test running in the browser (like when it is running on a remote selenium grid)

All screenshots are stored inside the target/executions folder, like this:

Default location of screenshots

And the folder structure follows this pattern:

target/executions/<name-of-the-feature>/<name-of-the-scenario>/<browser>-<timestamp>.<html/png>

You can also directly take screenshots in your scenarios with a special step:

 Scenario:
    Given I go to 'http:mydummysite/index.html'
    Then I take a snapshot
⚠️ **GitHub.com Fallback** ⚠️