Selenium Handler Details

Overview

The Selenium handler provides a way to open and interact with browsers during Chorus tests.

At present steps are provided to open a browser and navigate to a URL, but the full capabilities of Selenoium are not exposed. This is because the Selenium Handler is generally used in conjunction with the Web Sockets handler and the chorus-js javascript library.

The chorus-js project allows a web app to connect to a web socket opened by Chorus and publish its own step definitions, so that test steps can be integrated within a web app. This can either be done by building chorus-js into the main web app, or by injecting a Chorus script into a web app after the page loads, using the Selenium handler’s execute script test steps.

Handler Steps
Handler Properties

How to use the Selenium Handler

You can use this by adding ‘Uses: Selenium’ to the top of your feature file:

Uses: Selenium

You will need to ensure the chorus-selenium extension is on your classpath if using the JUnit Suite Runner, e.g. for a Maven project:

<dependency>
    <groupId>org.chorusbdd</groupId>
    <artifactId>chorus-selenium</artifactId>
    <version>3.1.0</version>
    <scope>test</scope>
</dependency>

If you don’t configure a browser in the properties, the Selenium handler will default to using Chrome Driver, which must be installed and in the PATH on the local system. Alternatively, you can add a named config for a Chrome Driver or Remote Web Driver (which enables the use of Selenium Grid)

Using the default Chrome Driver

The feature file may start like this:

Uses: Selenium

Feature-Start:
    Given I open Chrome
    And I navigate to http://my-big-single-page-app
   
Scenario: Scenario One
    ...scenario steps here

Configuring a Remote Web Driver

You can add properties in chorus.properties or myFeatureName.properties to define a named browser for use with the Selenium Handler:

e.g. to configure a browser named ‘myBrowserName’ which connects to a Selenium Hub at the address seleniumHub:4444/wd/hub:

# chorus.properties:
selenium.myBrowserName.driverType=REMOTE_WEB_DRIVER
selenium.myBrowserName.remoteWebDriver.URL=http://seleniumHub:4444/wd/hub

See Handler Configuration for more details on configuring handlers

Closing the browser

The browser window will be closed automatically at the end of the feauture (if the scope is FEATURE) or at the end of the scenario (for SCENARIO scoped browser configs)

For more details of the Selenium Handler in use with the chorus-js library

See Chorus JS

Steps available in the Selenium Handler:

Step	Example	Deprecated	Description	Retry Duration (wait for step to pass)
.*open Chrome	Given I open Chrome	Deprecated	Open a window in a local Chrome browser using the chromedriver installed on the system. Deprecated - use 'open the Chrome browser' which allows configuration
.*open the ([a-zA-Z0-9-_]+) browser	Given I open the myChrome browser	No	Open a window in a named browser which is defined in handler properties
.navigate the ([a-zA-Z0-9-_]+) browser to (.)	When I navigate the myChrome browser to http://www.bbc.co.uk	No	Open an provided URL in the window of the named browser
.navigate to (.)	When I navigate to http://www.bbc.co.uk	No	Open the provided URL in the most recently opened browser window
.*refresh the page	And I refresh the page	No	Refresh the current page in the most recently opened browser window
.*refresh the page in the ([a-zA-Z0-9-_]+) browser	And I refresh the page in the myChrome browser	No	Refresh the current page in the named browser window
.the url is (.)	Then the url is http://www.bbc.co.uk	No	Test the URL in the most recently opened browser matches the provided URL	2 SECONDS
.the url in the ([a-zA-Z0-9-_]+) browser is (.)	Then the url in the myChrome browser is http://www.bbc.co.uk	No	Test the URL in the named browser matches the provided URL	2 SECONDS
.*close the browser	Then I close the browser	No	Close the most recently opened browser window
.*close the ([a-zA-Z0-9-_]+) browser	Then I close the myChrome browser	No	Close the open window in the named browser
.execute the script (.) in the browser	Then I execute the script myJavascript.js in the browser	No	Execute a script at the file path relative to the feature directory within the window of the last opened browser
.execute the script (.) in the ([a-zA-Z0-9-_]+) browser	Then I execute the script myJavascript.js in the myChrome browser	No	Execute a script at the file path relative to the feature directory within the window of the named browser

Configuration properties for the Selenium Handler:

Property	Is Mandatory	Description	Default	Validation
driverType	yes	Defines the selenium driver type, e.g. CHROME, REMOTE_WEB_DRIVER, EDGE, CUSTOM (if specifying a custom webDriverFactoryClass)	REMOTE_WEB_DRIVER	One of: CUSTOM, CHROME, EDGE, REMOTE_WEB_DRIVER
webDriverFactoryClass	no	Set the implementation class for WebDriverFactory. Supply a fully qualified class name. Class must have a nullary constructor and implement WebDriverFactory	org.chorusbdd.chorus.selenium.manager.DefaultWebDriverFactory
chromeDriver.arguments	no	Arguments to pass to the chrome browser if using CHROME driver type
edgeDriver.arguments	no	Arguments to pass to the edget browser if using EDGE driver type
remoteWebDriver.browserType	no	If using REMOTE_WEB_DRIVER, a value to pass to the remote selenium web driver to request a browser type, e.g. chrome, firefox, safari	chrome
remoteWebDriver.URL	no	If using REMOTE_WEB_DRIVER, the URL to use to make the connection to the remote web driver or selenium grid	http://localhost:4444/wd/hub
scope	yes	Defines whether a browser connection should be closed at the end of a feature, or after each scenario This will be set automatically to FEATURE for connections established during 'Feature-Start:' if not provided, otherwise Scenario	SCENARIO	One of: SCENARIO, FEATURE
driverLogLevel	no	Desired log level for the selenium web driver, an attempt will be made to configure this level if the driver supports it	OFF	One of: ALL, INFO, DEBUG, WARNING, SEVERE, OFF

Chorus BDD