Runtime Settings

Branko Juric edited this page Jun 19, 2018 · 92 revisions

Gwen logo

Gwen-Web Runtime Settings

Gwen Properties

The first thing that you will need to do as part of installing Gwen is to create a properties file for storing your desired settings.

For convenience, these settings can be stored in a gwen.properties file in your local user home directory. Create this file now if you don't have one. Gwen will automatically find and load the settings in this file when it is launched.

Browser Settings

The next thing that you will need to do is configure your target browser and native web driver settings shown in this section.

Target browser

Add one of the settings shown below for the browser that you want Gwen to use in your gwen.properties file.

#firefox browser
gwen.web.browser=firefox

#chrome browser
gwen.web.browser=chrome

#ie browser
gwen.web.browser=IE

#safari browser
gwen.web.browser=safari

Make sure that the browser you have chosen is installed and updated on your machine. Then proceed to the next section that follows to install and configure the native web driver for that browser.

Native Web Drivers

In addition to the above browser setting, Gwen also requires a native web driver for your target browser to be installed. If you are targeting the Safari browser, then follow the instructions here and start using Gwen. Otherwise if you are targeting Chrome, Firefox, or IE, then install the native driver using method 1 or 2 below.

1. Install the native web driver using the Gwen package manager

  • Install the Gwen Package Manager (gwen-gpm) if you do not already have it installed
  • Open a command prompt and run one of the following commands below, depending on your target browser.

    Replace <destinationDir> with the directory location where you would like the native web driver to be installed to or omit it if you want to install it to the default location at ~/.gwen/packages/(chrome|gecko|ie)-driver under your user home. If you don't want to install the latest driver version, you can change the latest literal in the command below to the version that you do want to install.

    • For chrome: gwen-gpm install chrome-driver latest <destinationDir>
    • For firefox: gwen-gpm install ghecko-driver latest <destinationDir>
    • For IE: gwen-gpm install ie-driver latest <destinationDir>

2. Install the native web driver manually yourself

  • Click the link to download the driver archive for your target browser (download the latest one or the version that you want)
  • Unpack the archive to a location on your drive

Point Gwen to your installed web driver

Once you've install the native driver using one of the methods above, set the path to it in your gwen.properties file with one of the browser specific settings below (depending on your browser and platform):

For Windows:

    # firefox driver
    webdriver.gecko.driver = c:/path/to/geckodriver.exe

    # chrome driver
    webdriver.chrome.driver = /path/to/chromedriver.exe

    # ie driver
    webdriver.ie.driver = c:/path/to/IEDriverServer.exe

For Linux:

    # firefox driver
    webdriver.gecko.driver = /path/to/geckodriver

    # chrome driver
    webdriver.chrome.driver = /path/to/chromedriver

You are now ready to get started

The browser and web driver settings above are the minimum required configuration for Gwen. With your browser settings configured, you are now ready to start using Gwen.

More Settings

Web driver properties

All selenium web driver system properties are also supported and can be stored in your Gwen settings. For example, all the FireFox driver properties are supported. See the native web driver documentation to find out what settings are available for your browser.

Gwen-Web Settings

The following settings can be used to configure certain runtime aspects of the Gwen web engine. These can be defined in the gwen.properties file in your home directory or in a separate properties file passed to Gwen at launch time through the -p|--properties command line option.


Since v1.0.0


gwen.feature.failfast
  • Enables or disables fail fast mode at the feature level. If enabled, will fail a feature as soon as the first scenario in that feature fails before resuming with the next feature (if provided).
    • true to enable (default)
    • false to disable

gwen.feature.failfast.exit
  • If enabled, will exit execution as soon as any feature step fails.
    • true to enable
    • false to disable (default)

gwen.report.slideshow.framespersecond
  • The default number of frames per second (speed) in generated slideshow
    • default is 1

gwen.report.overwrite
  • Overwrites any previously generated report if enabled or creates a timestamped backup otherwise
    • true to overwrite (default)
    • false to create backup

gwen.web.browser
  • Configures the browser that Gwen will use.
    • Valid values include: firefox (default), chrome, IE, safari

gwen.web.useragent
  • Sets the user agent header in the browser to the literal string value assigned.

gwen.web.authorize.plugins
  • Controls whether or not to allow browser plugins to run (for example: Java applets).
    • true to enable
    • false to disable (default)

gwen.web.wait.seconds
  • Sets the maximum number of seconds that Gwen should wait for repeats and assertion conditions to be satisfied before timing out.
    • Default is 10
  • Note:
    • This value will also be used as the locator timeout (implicit web driver wait time) unless gwen.web.wait.locator.seconds is set to a different value.

gwen.web.maximize
  • Controls whether or not the web driver should maximize the browser window.
    • true to maximize
    • false to minimize (default)

gwen.web.throttle.msecs
  • Sets the number of milliseconds to wait for the web driver and web browser to synchronize with each other between interactions. Also directly controls element highlighting duration.
    • Default is 100

gwen.web.highlight.style
  • Sets the HTML style used by the element highlighting mechanism.
    • Default is background: yellow; border: 2px solid gold;

gwen.web.capture.screenshots
  • Controls whether or not to capture screenshots and generate slideshow.
    • true to enable
    • false to disable (default)

gwen.web.capture.screenshots.highlighting
  • Controls whether or not to capture screenshots of element highlighting (in addition to just screenshots).
    • true to enable
    • false to disable (default)

gwen.web.remote.url
  • If set, allows gwen-web to connect to a remote selenium service at the specified URL.
    • To use selenium grid server: http://host:port/wd/hub
    • To use sauce labs: http://:@ondemand.saucelabs.com:80/wd/hub
    • To use BrowserStack: https://username:accessKey@hub-cloud.browserstack.com/wd/hub

gwen.web.accept.untrusted.certs
  • Controls whether or not the web driver should accept untrusted (self signed) SSL certificates.
    • true to accept (default)
    • false to deny

gwen.web.suppress.images
  • Controls whether or not images are rendered in the browser (supported for firefox browser only).
    • true to suppress image rendering
    • false to include image rendering (default)

gwen.web.chrome.extensions
  • Comma separated list of paths to chrome extensions (crx files or directories) to load.

log4j.configuration
  • URL to log4j configuration file
    • Example: file:/path-to-log4j-config-file
    • If not specified, then the log4j.properties bundled in the binary is used (default)

Since v1.3.0


gwen.rampup.interval.seconds
  • Sets the ramp up interval (in seconds) for staggered parallel execution (supported for parallel execution mode only).
    • If it is not set or is set to zero, then no staggering will occur (default).
    • See also: Add ramp up interval for staggered parallel execution

gwen.report.suppress.meta
  • Controls whether or not meta reports should be suppressed when generating HTML reports.
    • true to suppress meta reporting
    • false enable it (default)

Since v1.4.0


gwen.web.capture.screenshots.duplicates
  • Controls whether or not consecutive duplicate screenshots should be captured or discarded.
    • true to keep duplicates
    • falseto discard duplicates (default)

Since v1.8.0


gwen.web.chrome.args

Since v1.10.0


gwen.web.chrome.prefs

gwen.web.chrome.pref.<name>
  • Where <name> is a chrome preference name
  • Sets a desired chrome preference on the underlying web driver. Only preferences that accept values of type String, Integer, or Boolean are supported.
  • Each setting is a new entry with a different <name> (you can configure as many as you need)
  • Example:
    • gwen.web.chrome.pref.download.default_directory = path/to/dir
      • Here <name> is download.default_directory and the value is a destination folder path string

Since v2.4.0


gwen.auto.discover.meta
  • Controls whether or not to enable or disable automatic discovery of meta files. Disabling this will prevent Gwen from automatically discovering and loading meta files in the path of an executing feature, forcing the user to control explicitly through the -m/--meta command line option which meta files to load.
    • true to enable (default)
    • false to disable

gwen.auto.discover.data.csv
  • Controls whether or not to enable or disable automatic discovery of CSV data files. Disabling this will prevent Gwen from automatically discovering and loading CSV files in the path of an executing feature, forcing the user to control explicitly through the -i/--import command line option which CSV files to load.
    • true to enable (default)
    • false to disable

Since v2.14.0


gwen.web.browser.headless
  • Controls whether or not to run the browser in headless mode.
    • true to run headless
    • false otherwise (default)
  • Notes:
    • Chrome and Firefox currently supported
      • Requires latest web browser and associated web driver

Since v2.15.0


gwen.web.capability.<name>
  • Where <name> is a desired capability name (or key)
  • Sets a desired web capability on the underlying web driver. Some of these are browser specific. If you set a capability that is not support for the browser you are targeting, then it will have no effect and be ignored. Only capabilities that accept values of type String, Integer, or Boolean are supported.
  • Each setting is a new entry with a different <name> (you can configure as many as you need)
  • Example:
    • gwen.web.capability.ignoreZoomSetting = true
      • Here <name> is ignoreZoomSetting and the value is a Boolean type

Since v2.19.0


gwen.web.locator.wait.seconds
  • Sets the maximum number of seconds that Gwen should wait for web elements to become available before timing out.

gwen.web.implicit.js.locators
  • Determines whether or not Gwen should implicitly convert all locators to JavaScript for greater reliability with web pages that dynamically display or render elements and manipulate the DOM. See Implicit JavaScript Locators for more info.
    • true to enable
    • false to disable (default)

Since v2.20.0


gwen.web.firefox.prefs

gwen.web.firefox.pref.<name>
  • Where <name> is a firefox preference name
  • Sets a desired firefox preference on the underlying web driver. Only preferences that accept values of type String, Integer, or Boolean are supported.
  • Each setting is a new entry with a different <name> (you can configure as many as you need)
  • Example:
    • gwen.web.firefox.pref.browser.download.defaultFolder = path/to/dir
      • Here <name> is browser.download.defaultFolder and the value is a destination folder path string

Since v2.22.0


gwen.web.implicit.element.focus
  • Determines whether or not Gwen should put the focus on elements before performing operations on them. It may help to disable this setting (set it to false) in parallel execution mode where multiple browser sessions are executing at the same time and contending for focus.
    • true to enable (default)
    • false to disable

Since v2.23.0


gwen.web.chrome.args.<uniqueSuffix>
  • Sets the arguments to pass to the chrome driver.
    • Where <uniqueSuffix> is an arbitrarily unique identifier
    • For example, the following settings..
      gwen.web.chrome.args.0=--ignore-certificate-errors
      gwen.web.chrome.args.1=--window-size=1920,1080
      
      ..will result in the following 2 arguments being passed to chrome driver:
      • --ignore-certificate-errors
      • --window-size=1920,1080

Environment Variables

See: Gwen environment settings

Changing the Selenium version

By default, gwen-web uses the latest selenium implementation bundled in its distribution (the gwen-web zip you downloaded). So you do not need to download and install selenium yourself. If your browser is up to date or very recent then this will suffice. But if you have an older or conflicting browser version or for some reason would like to use an earlier version of selenium, then you can download the selenium-java ZIP distribution that you desire from the selenium downloads page and unpack it to a location on your drive and then set the SELENIUM_HOME environment variable to point to that location. Gwen will then use that selenium version when it is next invoked.

Sauce Labs integration

When using the RemoteWebDriver with gwen-web, by changing the user property gwen.web.remote.url to something that includes saucelabs username and apikey you are able to run tests via saucelabs. This allows you to connect to over 700 different browser combinations. Sauce Labs Platforms

The format of the saucelabs remote webdriver is as follows:

http://<saucelabsusername>:<saucelabsapikey>@ondemand.saucelabs.com:80/wd/hub

As an example, using a fictitious account on saucelabs:

gwen.web.remote.url = 
  http://thisIsMySauceUsername:35945f7d-8880-4685-ce89-c8c8c830c88f@ondemand.saucelabs.com:80/wd/hub

See also: Running Gwen on BrowserStack

Logging settings

All log4j system properties are also supported. The following logging configuration is used by default if no log4j.configuration setting is specified. For more information about log4j, see the log4j FAQ.

# Set root logger level to INFO and append to STDOUT
log4j.rootLogger=INFO, STDOUT

# STDOUT is set to be a ConsoleAppender.
log4j.appender.STDOUT=org.apache.log4j.ConsoleAppender

# STDOUT uses PatternLayout.
log4j.appender.STDOUT.layout=org.apache.log4j.PatternLayout
log4j.appender.STDOUT.layout.ConversionPattern=%p - %m%n

# Gwen logging level
log4j.logger.gwen=INFO
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.