Skip to main content

Settings

Jump to Settings Reference

Settings Files​

All Gwen settings and properties are maintained in settings files in your project.

Formats​

The following settings file formats are supported:

  • HOCON (Human-Optimized Config Object Notation), since v3.0.0
    • The recommended and default format
    • A superset of JSON
    • Maintained in .conf files
  • JSON, since v3.0.0
    • Pure JSON format
    • Maintained in .json files
  • Properties, since v1.0.0
    • Legacy Java properties style format
    • Flat name = value pairs
    • Maintained in .properties files

Ideally you should use one format for all your settings files, but using combinations of the above is also permitted. Priority will be given in the order shown to same named files in a directory having different formats:

  1. .conf
  2. .json
  3. .properties

Load order and precedence​

Settings are loaded in the following order of precedence, with those higher in the list overriding the lower.

  1. Environment variable overrides
  2. System properties
  3. User settings
    • A gwen.conf, gwen.json, or gwen.properties file in your user directory
  4. Profile settings
    • A *.conf, *.json, or *.properies file denoted name passed to -p|--profile launch option.
  5. Launch settings
    • Comma separated list of *.conf, *.json, or *.properies files passed to Gwen via the -c|--conf launch option. These are loaded in the order given with latter entries overriding the former.
  6. Project settings
    • A gwen.conf, gwen.json or gwen.properties file in your root project directory
  7. Default settings
    • Internal Gwen defaults
System properties override all other settings

-Dname=value pairs passed to Gwen as system properties have topmost precedence and will always override ALL other settings.

You can maintain settings and override internal defaults at various levels as described here.

User settings files​

User-level settings can optionally be defined in a gwen.conf|json|properties file in the root of your user directory on a machine. These are useful when you want to override certain settings on a machine for a user.

 /Users
 └── /<username> (~/) 
     └── gwen.conf           # User-level overrides

Profile settings files​

All profile settings are stored in *.conf|json|properties files in the gwen/conf/profiles subdirectory of the project. Gwen selectively discovers and loads these files when you inovke Gwen with the -p|--profile option passing in a profile name. The settings file with the same name as the passed in profile is the one that is loaded.

 /project                     # Your project root
 └── /gwen
     └── /conf
         └── /profiles        # Profile settings
             ├── profile1.conf   
             ├── profile2.conf
             ├── ..
             └── profileN.conf

Project settings files​

When you set up and initialise your project, all project level settings are stored in a gwen.conf|json|properties file in the root of the project. Gwen automatically discovers and loads this file for you, so you don't need to explictly pass it to Gwen when you launch in the project directory.

 /project                    # Your project root
 └── gwen.conf               # Project settings

Settings reference​

Launch settings​

gwen.launch.options.parallel

Controls whether or not the --parallel launch option will be passed to Gwen.

Supported values

  • true to always launch Gwen in parallel execution mode
  • false to only launch Gwen in parallel execution mode if the --parallel launch option is explicitly passed (default).

Default value

  gwen {
    launch {
      options {
        parallel = false
      }
    }
  }
launch option: --parallel
Since v3.0.0
gwen.launch.options.batch

Controls whether or not the -b|--batch launch option will be passed to Gwen.

Supported values

  • true to always launch Gwen in batch mode and disable the REPL.
  • false to launch Gwen in batch mode if the -b|--batch option is explicitly passed and in REPL mode if it is not (default).

Default value

  gwen {
    launch {
      options {
        batch = false
      }
    }
  }
launch option: -b|--batch
Since v3.0.0
gwen.launch.options.verbose

Controls whether or not the -v|--verbose launch option will be passed to Gwen.

Supported values

  • true for verbose logging mode
  • false for pretty logging mode (default)

Default value

  gwen {
    launch {
      options {
        verbose = false
      }
    }
  }
launch option: -v|--verbose
Since v3.0.0
gwen.launch.options.dryRun

Controls whether or not the -n|--dry-run launch option will be passed to Gwen.

Supported values

  • true to always launch Gwen in dry run mode
  • false to only launch Gwen in dry run mode if the -n|--dry-run launch option is explicitly passed (default).

Default value

  gwen {
    launch {
      options {
        dryRun = false
      }
    }
  }
launch option: -n|--dry-run
Since v3.0.0
gwen.launch.options.report

Sets the -r|--report option to pass to Gwen.

Supported values

  • A path to a directory to output all reports to (default = ${gwen.outDir}/reports).

Default value

  gwen {
    launch {
      options {
        report = "${gwen.outDir}/reports"
      }
    }
  }
launch option: -r|--report
Since v3.0.0
gwen.launch.options.format

Sets the -f|--format option to pass to Gwen.

Supported values


Notes

This setting is additive, meaning that all entries in all loaded settings files are merged.

Default value (empty to pick up Gwen default format: html)

  gwen {
    launch {
      options {
        format = [ 
        ]
      }
    }
  }

Example with multiple entries

  gwen {
    launch {
      options {
        format = [ 
          "html"
          "results"
        ]
      }
    }
  }
launch option: -f|--format
Since v3.0.0
gwen.launch.options.tags

Sets the -t|--tags option to pass to Gwen.

Supported values

  • A list of @include and ~@exclude tags to pass to Gwen on every launch


Notes

This setting is additive, meaning that all entries in all loaded settings files are merged.

Default value (empty for no tags)

  gwen {
    launch {
      options {
        tags = [ 
        ]
      }
    }
  }

Example setting two default tags

  gwen {
    launch {
      options {
        tags = [ 
          "@includeTag"
          "~@excludeTag"
        ]
      }
    }
  }
launch option: -t|--tags
Since v3.0.0
gwen.launch.options.inputData

Sets the -i|--input-data option to pass to Gwen.

Supported values

  • A path to a CSV or JSON data feed file to pass to Gwen on every launch

Default value (blank for no input file)

  gwen {
    launch {
      options {
        inputData = ""
      }
    }
  }

Example setting a default CSV data file

  gwen {
    launch {
      options {
        inputData = "data/file1.csv"
      }
    }
  }

Example setting a default JSON data file (since v3.47.0)

  gwen {
    launch {
      options {
        inputData = "data/file1.json"
      }
    }
  }
launch option: -i|--input
Since v3.0.0
gwen.launch.options.meta

Sets the -m|--meta option to pass to Gwen.

Supported values

  • A list of paths to meta files to pass to Gwen on every launch


Notes

This setting is additive, meaning that all entries in all loaded settings files are merged.

Default value (blank for no meta)

  gwen {
    launch {
      options {
        meta = [ 
        ]
      }
    }
  }

Example setting two default meta files

  gwen {
    launch {
      options {
        meta = [ 
          "meta/file1.meta"
          "meta/file2.meta"
        ]
      }
    }
  }
launch option: -m|--meta
Since v3.0.0
gwen.launch.options.features

Sets the list of feature files or directories to pass to Gwen.

Supported values

  • A list of paths to feature files to pass to Gwen on every launch


Notes

This setting is additive, meaning that all entries in all loaded settings files are merged.

Default value (empty for no feature files/dirs)

  gwen {
    launch {
      options {
        features = [ 
        ]
      }
    }
  }

Example setting two default feature files

  gwen {
    launch {
      options {
        features = [ 
          "features/file1.feature"
          "features/file2.feature"
        ]
      }
    }
  }
CLI argument: [files/dirs]
Since v3.0.0

Core Settings​

gwen.assertion.mode

Controls whether or not hard, soft or sustained assertions are enabled by default.

Supported values

  • hard to halt feature execution on the first assertion error and report failure (default)
  • soft to collect all assertion errors and continue execution whilst reporting failures
  • sustained to collect all assertion errors and continue execution without reporting failures

Default value

  gwen {
    assertion {
      mode = "hard"
    }
  }
Since v2.18.0
gwen.auto.bind.tableData.outline.examples

Controls whether or not to bind row data in outline examples tables to same named attributes in the current scope.

Supported values

  • true to bind table data to same named attributes in the current scope for each row (default)
  • false to not bind table data to attributes in the current scope

Default value

  gwen {
    auto {
      bind {
        tableData {
          outline {
            examples = true
          }
        }
      }
    }
  }
Since v3.15.0
gwen.auto.trim.data.csv

Controls whether or not to trim surrounding whitespace from incoming CSV data.

Supported values

  • true to trim the CSV data
  • false to not trim the CSV data (default)

Default value

  gwen {
    auto {
      trim {
        data {
          csv = false
        }
      }
    }
  }
Since v3.26.0
gwen.auto.trim.data.json

Controls whether or not to trim surrounding whitespace from incoming JSON data.

Supported values

  • true to trim the JSON data
  • false to not trim the JSON data (default)

Default value

  gwen {
    auto {
      trim {
        data {
          json = false
        }
      }
    }
  }
Since v3.47.0
gwen.behavior.rules

Controls whether strict or lenient rules around Given-When-Then usage will be enforced for features.

Note: gwen.behaviour.rules is no longer a supported alias (since v3.0.0)

Supported values

  • strict to enforce the following strict rules (default):

    • Steps in scenarios and backgrounds must satisfy Given-When-Then order
    • Givens must set context
    • Whens must perform actions
    • Thens must assert expectations
    • Buts must perform assertions (and are permitted after Then steps)

    • StepDefs tagged with

      • @Context : can only be called by Givens
      • @Action : can only be called by Whens
      • @Assertion : can only be called by Thens or Buts
  • lenient to relax all strict rules

Default value since v3.0.0

  gwen {
    behavior {
      rules = "strict"
    }
  }

Default value in prior versions

  gwen {
    behavior {
      rules = "lenient"
    }
  }
Since v2.41.0
gwen.dryRun.limit.tableData.outline.examples.records

Sets the maximum number of outline examples table records to include in dry runs.

Supported values

  • A positive integer representing the the maximum number of records to include

    • or infinity to log all records (default)

Default value

  gwen {
    dryRun {
      limit {
        tableData {
          outline {
            examples {
              records = "infinity"
            }
          }
        }
      }
    }
  }
Since v3.28.0
gwen.error.messages.inline.locators

Controls whether or not to inline locator information next to all named bindings in error messages.

Supported values

  • true to include locator information
  • false to exclude locator information (default)

Default value since v3.30.1

  gwen {
    error {
      messages {
        inline {
          locators = false
        }
      }
    }
  }

Effecitve default value in prior versions when setting was not defined

  gwen {
    error {
      messages {
        inline {
          locators = true
        }
      }
    }
  }
Since v3.31.0
gwen.feature.dialect

Sets the default Gherkin dialect (or spoken language).

Supported values

Default value

  gwen {
    feature {
      dialect = "en"
    }
  }
Since v2.42.0
gwen.feature.failfast.enabled

Enables or disables fail fast mode at the feature level.

Supported values

  • true to enable (default)

    • Will fail a feature as soon as the first scenario fails before resuming with the next feature.
  • false to disable

Default value

  gwen {
    feature {
      failfast {
        enabled = true
      }
    }
  }
Since v1.0.0
gwen.feature.failfast.exit

Controls whether to exit or resume with the next feature when a feature fails.

Supported values

  • true to enable

    • Will fail a feature as soon as the first scenario fails and exit immediately.

  • false to disable (default)

    • Will resume with the next feature if the previous one fails.

Default value

  gwen {
    feature {
      failfast {
        exit = false
      }
    }
  }
Since v1.0.0
gwen.feature.mode

Controls whether or not Gwen DSL steps are permitted in feature specs.

Supported values

  • declarative (default)

    • DSL steps not permitted in feature specs
  • imperative
    • DSL steps permitted in feature specs

Default value since v3.0.0

  gwen {
    auto {
      feature {
        mode = "declarative"
      }
    }
  }

Default value in prior versions

  gwen {
    auto {
      feature {
        mode = "imperative"
      }
    }
  }
Since v2.39.0
gwen.mask.char

Sets the masking character used for logging masked settings.

Supported values

  • Any single character (default = *)

Default value

  gwen {
    mask {
      char = "*"
    }
  }
Since v2.48.0
gwen.baseDir

Sets the base Gwen project directory

Supported values

  • A relative or absolute directory location (default = gwen)

    • The output directory

Default value

  gwen {
    baseDir = "gwen"
  }
Since v3.0.0
gwen.outDir

Sets the default Gwen output directory.

Supported values

  • A relative or absolute directory location (default = ${gwen.baseDir}/output)

    • The output directory

Default value

  gwen {
    outDir = "${gwen.baseDir}/output"
  }
Since v3.0.0
gwen.parallel.maxThreads

Sets the maximum number of permitted parallel executor threads.

Supported values

  • auto (since v3.18.0) or 0 to run one thread on each available cores (default)
  • A percentage of the total number of the cores available (since v4.3.0). For example: 80%

  • Or positive integer value denoting the maximum number of threads to allow

    • When less than the number of available cores, the remaining cores will be free
    • When greater than the number of available cores, more than one thread may execute on some or all cores (use judiciously)

Default value

  gwen {
    parallel {
      maxThreads = auto
    }
  }
Since v2.45.0
gwen.rampup.interval.seconds

Sets the ramp up interval for staggered parallel execution.

Supported values

  • A positive integer denoting the number of seconds to wait before executing successive features in parallel
  • Zero for no interval or delay between successive feature executions (default)


Example: A 5 second interval would stagger parallel feature executions like this over 4 cores:

  time  00   05   10   15   seconds
        │    │    │    │
core 1  │<── feature 1a ──>|<── feature 1b ──> ..
core 2  │    │<── feature 2a ──>|<── feature 2b ──> ..
core 3  │    │    │<── feature 3a ──>|<── feature 3b ──> ..
core 4  │    │    │    │<── feature 4a ──>|<── feature 4b ──> ..

Default value

  gwen {
    rampup {
      interval {
        seconds = 0
      }
    }
  }
Since v1.3.0
gwen.report.attach.functions

Controls whether or not the scripts of evaluated functions are attached to steps in the Gwen report (default is true).

Supported values

  • true to attach (default)
  • false to not attach

Default value

  gwen {
    report {
      attach {
        functions = true
      }
    }
  }
Since v3.56.0
gwen.report.overwrite

Controls whether to overwrite previously generated reports or create a timestamped backup instead.

Supported values

  • true to overwrite previous report (default)
  • false to backup previous report into a timestamped directory

Default value

  gwen {
    report {
      overwrite = true
    }
  }
Since v1.0.0
gwen.report.stepDef.indent.pixels

Controls the left margin indent size of StepDefs in HTML reports.

Supported values

  • A positive integer representing the indent size in pixels (default = 20)

Default value

  gwen {
    report {
      stepDef {
        indent {
          pixels = 20
        }
      }
    }
  }
Since v3.37.0
gwen.console.log.colors

Controls whether to use ANSI colors to highlight Gherkin keywords and evaluation results in the console report output.

Supported values

  • true to use colors (default)
  • false to not use colors

Default value

  gwen {
    console {
      log {
        colors = true
      }
    }
  }
Since v3.0.0
gwen.console.log.depth

Controls the step logging depth in the console report output at evaluation time (excluding dry run mode which unconditionally logs all levels as of v3.41.0)

Supported values

  • A positive integer representing the step depth to log to (default = 1)

    • or infinity to log to all depths

Default value

  gwen {
    console {
      log {
        depth = 1
      }
    }
  }

To log all depths:

  gwen {
    console {
      log {
        depth = "infinity"
      }
    }
  }
Since v3.15.0
gwen.console.repl.autoSuggestions

Controls whether or not auto suggestions based on user history are enabled or not in the REPL console.

Supported values

  • true to enable auto suggestions (default)
  • false to disable auto suggestions

Default value

  gwen {
    console {
      repl {
        autoSuggestions = true
      }
    }
  }
Since v3.40.0
gwen.console.repl.tabCompletion

Controls whether or not tab completion is enabled or not in the REPL console.

Supported values

  • true to enable tab completion (default)
  • false to disable tab completion

Default value

  gwen {
    console {
      repl {
        tabCompletion = true
      }
    }
  }
Since v3.40.0
gwen.report.suppress.meta

Controls whether or not to suppress meta from generated HTML reports.

Supported values

  • true to suppress meta (default)
  • false to include meta

Default value since v3.0.0

  gwen {
    report {
      suppress {
        meta = true
      }
    }
  }

Default value in prior versions

  gwen {
    report {
      suppress {
        meta = false
      }
    }
  }
Since v1.3.0
gwen.report.slideshow.framespersecond

Sets the default number of frames per second to set the image playback speed to in generated slideshows.

Supported values

  • A positive integer denoting the number of frames per second (default = 4)

Default value

  gwen {
    report {
      slideshow {
        framespersecond = 4
      }
    }
  }
Since v1.0.0
gwen.state.level

Controls whether to maintain state at the feature or scenario level.

Supported values

  • feature for feature level state that is shared across scenarios in a feature (each feature gets a new state) (default)
  • scenario for scenario level state that is not shared across scenarios (each scenario gets a new state)

Default value

  gwen {
    state {
      level = "feature"
    }
  }
Since v2.38.0
gwen.video.dir

Sets the output directory for video recordings.

Video capture is currently only supported in docker. This setting is used to set the location where the selenium video recorder will output mp4 files.

Supported values

  • A relative or absolute directory location (default = ${gwen.outDir}/.video)

Default value

  gwen {
    video {
      dir = "$<user.home>/.assets/$<gwen.web.sessionId>"
    }
  }
Since v3.7.0
gwen.video.timeoutSecs

Sets the number of seconds wait for video files to be ready when including them in generated HTML reports.

Video capture is currently only supported in Docker. This setting is used to set the maximum time to wait for video files to be asynchronously written out to the host directory by the video recorder after a browser session is closed. If the video files in your environment take longer than the default, then you will need to explicitly configure this setting to a higher value.

Supported values

  • A number of seconds wo wait (default = 10)

Default value

  gwen {
    video {
      timeoutSecs = 10
    }
  }
Since v3.7.0
gwen.logLevel.deprecations

Controls how deprecation messages are reported.

Supported values

  • warn to log deprecations as warnings

  • error to raise and report deprecations as errors

  • none to suppress logging or reporting of deprecation messages (no operation)

Default value

  gwen {
    logLevel {
      deprecations = "warn"
    }
  }
Since v2.74.0
gwen.input.data.maskFields

Specifies input data fields to mask.

Default value

  gwen {
    input {
      data {
        maskFields = [
        ]
      }
    }
  }
Since v4.1.0
gwen.input.data.readOnly

Enables or disables read-only mode for all data sourced from input files. This setting has no effect in REPL mode where read-only is not enforced.

Supported values

  • true to enable read only mode (default)

  • false to disable read only mode

Default value

  gwen {
    input {
      data {
        readOnly = true
      }
    }
  }
Since v4.0.0
gwen.reports.results.files

Controls how CSV result files are generated.

See CSV Reports for details.

Since v3.77.0

Web Settings​

gwen.web.assertions.delayMillisecs

Sets the time to delay all assertion attempts.

Supported values

  • A number greater than zero denoting the number of milliseconds to delay each assertion attempt (default = 200).

Default value

  gwen {
    web {
      assertions {
        delayMillisecs = 200
      }
    }
  }
Since v3.42.0
gwen.web.assertions.maxStrikes

Sets the maximum number of consecutive strikes an assertion can make within a timeout period before it is considered failed and reported.

Supported values

  • A number greater than zero denoting the maximum number of consecutive strikes to permit. You can tweak this value to optimise performance.
  • infinity to continually retry on every strike until the assertion passes or the timeout period expires (sub optimal performance)

  • auto to let Gwen decide (default), Since v3.52.0

    • Since 3.52.0, Gwen sets this to the same value configured in gwen.web.wait.seconds. For example, if your configured timeout is 10 seconds, then your max strike count will be 10.
    • This might change in future to use smarter approaches as Gwen evolves

Default value (since v3.52.0)

  gwen {
    web {
      assertions {
        maxStrikes = auto
      }
    }
  }

Default value (since v3.42.9)

  gwen {
    web {
      assertions {
        maxStrikes = 5
      }
    }
  }

Default value (since v3.41.0)

  gwen {
    web {
      assertions {
        maxStrikes = 3
      }
    }
  }

Default value in prior versions

  gwen {
    web {
      assertions {
        maxStrikes = infinity
      }
    }
  }
Since v3.41.0
gwen.web.authorize.plugins

Controls whether or not to permit browser plugins to run.

Supported values

  • true to permit
  • false to deny (default)

Default value

  gwen {
    web {
      authorize {
        plugins = false
      }
    }
  }
Since v1.0.0
gwen.target.browser

Sets the default browser to target when Gwen is launched. Chrome, Firefox, Safari and Edge are supported.

Formerly gwen.web.browser (prior to v3.0.0)

Supported values

  • The name of the browser settings file (minus extension) in your gwen/browsers folder to load if no other browser settings file is explicitly passed via the -c/--config launch option

    • chrome for Chrome browser (default)
    • firefox for Firefox browser
    • safari for Safari browser
    • edge for Edge browser, since v2.35.0

Default value

  gwen {
    target {
      browser  = "chrome"
    }
  }
Since v1.0.0
gwen.target.env

Sets the environment settings to load when Gwen is launched.

Supported values

  • The name of the environment settings file (minus extension) in your gwen/env folder to load if no other environment settings file is explicitly passed via the -c/--config launch option

    • local for your local development environment
    • dev for your dedicated development environment
    • test for your dedicated test environment (default)
    • staging for your dedicated staging environment
    • prod for your production environment
    • Or the name of any other environment file you may create in your gwen/env folder

Default value (since v3.41.0)

  gwen {
    target {
      env  = "test"
    }
  }

Default value in prior versions

  gwen {
    target {
      env  = "local"
    }
  }
Since v3.0.0
gwen.web.browser.headless

Controls whether or not to run the browser in headless mode.

Supported values

  • true to run headless
  • false to not run headless (default)


Notes

Headless mode is supported for Chrome, Firefox, and Edge browsers only.

Default value

  gwen {
    web {
      browser {
        headless = false
      }
    }
  }
Since v2.14.0
gwen.web.browser.size

Sets the size of the browser window.

Supported values

  • String of format <width> x <height>, where:

    • <width> is a positive integer denoting the desired width
    • <height> is a positive integer denoting the desired height

Example

  gwen {
    web {
      browser {
        size = "1920x1080"
      }
    }
  }
Since v2.27.0
gwen.web.browser.position

Sets the position of the main browser window.

Supported values

  • String of format <x>,<y>, where:

    • <x> is a positive integer denoting the x co-ordinate
    • <y> is a positive integer denoting the y co-ordinate

Example

  gwen {
    web {
      browser {
        size = "0,0"
      }
    }
  }
Since v4.7.0
gwen.web.capability.<capabilities>

or Since v3.23.0 (preferred)

gwen.web.capabilities.<capabilities>

Sets a one or more web capabilities on the underlying web driver (including W3C protocol extensions).

Where

Example

  gwen {
    web {
      capabilities {
        acceptInsecureCerts = false
        "se:recordVideo" = false
      }
    }
  }
Since v2.15.0
gwen.web.capture.screenshots.enabled

Controls whether or not to capture screenshots and generate slideshow.

Formerly gwen.web.capture.screenshots (prior to v3.0.0)

Supported values

  • true to enable
  • false to disable (default)

Default value

  gwen {
    web {
      capture {
        screenshots {
          enabled = false
        }
      }
    }
  }
Since v1.0.0
gwen.web.capture.screenshots.highlighting

Controls whether or not to capture screenshots of element highlighting (in addition to standard screenshots).

Supported values

  • true to enable
  • false to disable (default)

Default value

  gwen {
    web {
      capture {
        screenshots {
          highlighting = false
        }
      }
    }
  }
Since v1.0.0
gwen.web.capture.screenshots.duplicates

Controls whether or not consecutively identical screenshots should be captured or discarded.

Supported values

  • true to keep duplicates
  • false to discard duplicates (default)

Default value

  gwen {
    web {
      capture {
        screenshots {
          duplicates = false
        }
      }
    }
  }
Since v1.4.0
gwen.web.highlight.style

Sets the HTML styling used to highlight elements that Gwen interacts with.

Supported values

  • HTML style strings (default = background: yellow; border: 1px solid gold;)

Default value

  gwen {
    web {
      highlight {
        style = "background: yellow; border: 1px solid gold;"
      }
    }
  }
Since v1.0.0
gwen.web.implicit.element.focus

Controls whether or not Gwen should shift the focus onto elements before interacting with them.

Supported values

  • true to enable auto focus (default)
  • false to disable auto focus

Default value

  gwen {
    web {
      implicit {
        element {
          focus = true
        }
      }
    }
  }
Since v2.22.0
gwen.web.implicit.element.moveTo

Controls whether or not Gwen should physically move to elements to bring them into view before interacting with them.

Supported values

  • true to enable auto move to
  • false to disable auto move to (default)

Default value

  gwen {
    web {
      implicit {
        element {
          moveTo = false
        }
      }
    }
  }
Since v3.8.0
gwen.web.locator.wait.seconds

Sets the maximum number of seconds that Gwen should wait when locating web elements before timing out.

Supported values

Default value

  gwen {
    web {
      locator {
        wait {
          seconds = ${gwen.web.wait.seconds}
        }
      }
    }
  }
Since v2.19.0
gwen.web.maximize

Controls whether or not the web driver should maximize the browser window.

Supported values

  • true to maximize
  • false to not maximize (default)

Default value

  gwen {
    web {
      maximize = false
    }
  }
Since v1.0.0
gwen.web.remote.localFileDetector

Controls whether or not the local file detector on remote web driver will be enabled.

Supported values

  • auto to automatically enable for remote driver sessions only (default)
  • true to enable
  • false to disable


This setting is ignored if gwen.web.remote.url is not set.

Default value

  gwen {
    web {
      remote {
        localFileDetector = auto
      }
    }
  }
Since v2.44.0
gwen.web.remote.url

Remote web driver url for connecting to a Selenium Grid server.

Example

  gwen {
    web {
      remote {
        url = "http://selenium-hub:4444/wd/hub"
      }
    }
  }
Since v1.0.0
gwen.web.remote.connectTimeout.seconds

Sets the maximum time to wait for a remote grid connection before timing out.

Supported values

  • A positive integer denoting a number of seconds (default = 30)

Default value

  gwen {
    web {
      remote {
        connectTimeout {
         seconds = 60
        }
      }
    }
  }
Since v4.2.3
gwen.web.remote.sessionRetries

Controls whether or not to retry failed remote session creation attempts.

Supported values

  • true to retry
  • false to not retry
  • auto to retry only for remote sessions and when gwen-web-remote-url is set (default)

When enabled, the number of retry attempts is determined by the number of available CPU cores divided by 4. The first failed attempt waits 1 second, the next 2 seconds, the next 3 seconds and so on until all attempts are exhausted.

Example

  gwen {
    web {
      remote {
        sessionRetries = auto
      }
    }
  }
Since v3.63.0
gwen.web.sendKeys.clearFirst

Controls whether or not Gwen will clear input fields before sending keys to them.

Supported values

  • true to clear first
  • false to not clear first (default)

Default value

  gwen {
    web {
      sendKeys {
        clearFirst = false
      }
    }
  }
Since v2.31.0
gwen.web.sendKeys.clickFirst

Controls whether or not Gwen will click input fields before sending keys to them.

Supported values

  • true to click first
  • false to not click first (default)

Default value

  gwen {
    web {
      sendKeys {
        clickFirst = false
      }
    }
  }
Since v2.43.0
gwen.web.session.expired.autoReplace

Controls whether or not Gwen will auto replace expired sessions with new ones.

Supported values

  • true to auto replace (default)
  • false to throw exception

Default value

  gwen {
    web {
      session {
        expired {
          autoReplace = true
        }
      }
    }
  }
Since v4.5.0
gwen.web.throttle.msec

Sets the number of milliseconds to wait between web driver interactions and also directly controls web element highlighting duration.

Supported values

  • A positive integer denoting a number of milliseconds. Set to zero for maxmum speed with no highlighting (default = 100).

Default value

  gwen {
    web {
      throttle {
        msec = 100
      }
    }
  }
Since v1.0.0
gwen.web.useragent

Sets the user agent header in the browser to the literal string value assigned.

Supported values

  • User agent string

Example

  gwen {
    web {
      useragent = "Mozilla/5.0 (Linux; Android 4.2.1; en-us; Nexus 5 Build/JOP40D) AppleWebKit/535.19 (KHTML, like Gecko) Chrome/18.0.1025.166 Mobile Safari/535.19"
    }
  }
Since v1.0.0
gwen.web.wait.seconds

Sets the default maximum number of seconds that Gwen should wait for time senstive operations before timing out.

Supported values

  • A positive integer denoting a number of seconds (default = 10)

Default value

  gwen {
    web {
      wait {
        seconds = 10
      }
    }
  }
Since v1.0.0

Chrome​

gwen.web.chrome.args

A chrome preference value.

Supported values


Notes

This setting is additive, meaning that all entries in all loaded settings files are merged.

Example

  gwen {
    web {
      chrome {
        args = [
          "--ignore-certificate-errors"
          "--incognito"
        ]
      }
    }
  }
Since v1.8.0
gwen.web.chrome.args.<seqNo>

Passes an argument to the Chrome web driver.

Where

  • <seqNo> is a unique sequence number

Supported values

Use gwen.web.chrome.args instead.

Since v2.23.0
gwen.web.chrome.extensions

A chrome preference value.

Supported values

  • A relative or absolute file path to an extension (.crx) file or directory


Notes

This setting is additive, meaning that all entries in all loaded settings files are merged.

Example

  gwen {
    web {
      chrome {
        extensions = [
          "path/to/extenstion.crx"
        ]
      }
    }
  }
Since v1.0.0
gwen.web.chrome.mobile.<emulation>

Mobile emulation for Chrome.

Where

  • <emulation> can be one or more of:

    • deviceName for the device name
    • width for the device width
    • height for the device height
    • pixelRatio for the device pixel ratio
    • touch for the device touch mode

Example emulating by name

  gwen {
    web {
      chrome {
        mobile {
          deviceName = "Pixel 2"
        }
      }
    }
  }

Example emulating by metrics

  gwen {
    web {
      chrome {
        mobile {
          width = 360
          height =  640
          pixelRatio = 3.0
          touch = true
        }
      }
    }
  }
Since v2.33.0
gwen.web.chrome.path

Overrides the path to the default system Chrome browser binary.

Supported values

  • The path the the Chrome application.

    • On macOS, this should be the actual binary, not just the app (e.g., /Applications/Google Chrome.app/Contents/MacOS/Google Chrome).

Example

  gwen {
    web {
      chrome {
        path = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
      }
    }
  }
Since v2.44.0
gwen.web.chrome.prefs

A chrome preference value.

Supported values


Notes

This setting is additive, meaning that all entries in all loaded settings files are merged.

Example

  gwen {
    web {
      chrome {
        prefs {
          download {
            default_directory = path/to/dir
            prompt_for_download = false
          }
        }
      }
    }
  }
Since v1.10.0
gwen.web.chrome.pref.<name>

Sets a Chrome preference.

Where

Supported values

  • A preference value

Use gwen.web.chrome.prefs instead.

Since v1.10.0

Edge​

gwen.web.edge.args

A chrome preference value.

Supported values


Notes

This setting is additive, meaning that all entries in all loaded settings files are merged.

Example

  gwen {
    web {
      edge {
        args = [
          "--ignore-certificate-errors"
          "--incognito"
        ]
      }
    }
  }
Since v2.48.0
gwen.web.edge.args.<seqNo>

Passes an argument to the Edge web driver.

Where

  • <seqNo> is a unique sequence number

Supported values

Use gwen.web.edge.args instead.

Since v2.48.0
gwen.web.edge.extensions

A chrome preference value.

Supported values

  • A relative or absolute file path to an extension (.crx) file or directory


Notes

This setting is additive, meaning that all entries in all loaded settings files are merged.

Example

  gwen {
    web {
      edge {
        extensions = [
          "path/to/extenstion.crx"
        ]
      }
    }
  }
Since v2.48.0
gwen.web.edge.mobile.<emulation>

Mobile emulation for Edge.

Where

  • <emulation> can be one or more of:

    • deviceName for the device name
    • width for the device width
    • height for the device height
    • pixelRatio for the device pixel ratio
    • touch for the device touch mode
    • userAgent for the device user agent

Example emulating by name

  gwen {
    web {
      edge {
        mobile {
          deviceName = "Pixel 2"
        }
      }
    }
  }

Example emulating by metrics

  gwen {
    web {
      edge {
        mobile {
          width = 360
          height =  640
          pixelRatio = 3.0
          touch = true
        }
      }
    }
  }
Since v2.48.0
gwen.web.edge.path

Overrides the path to the default system Edge browser binary.

Supported values

  • The path the the Edge application.

    • On macOS, this should be the actual binary.

Example

  gwen {
    web {
      edge {
        path = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
      }
    }
  }
Since v2.48.0
gwen.web.edge.prefs

A chrome preference value.

Supported values


Notes

This setting is additive, meaning that all entries in all loaded settings files are merged.

Example

  gwen {
    web {
      edge {
        prefs {
          download {
            default_directory = path/to/dir
            prompt_for_download = false
          }
        }
      }
    }
  }
Since v2.48.0
gwen.web.edge.pref.<name>

Sets a Edge preference.

Where

Supported values

  • A preference value

Use gwen.web.edge.prefs instead.

Since v2.48.0

Firefox​

gwen.web.firefox.prefs

A chrome preference value.

Supported values

  • Firefox preferences (for full list, visit about:config in your Firefox browser)


Notes

This setting is additive, meaning that all entries in all loaded settings files are merged.

Example

  gwen {
    web {
      firefox {
        prefs {
          browser {
            download {
              useDownloadDir = false
              loglevel = Error
            }
          }
        }
      }
    }
  }
Since v2.20.0
gwen.web.firefox.pref.<name>

Sets a Firefox preference.

Where

  • <name> is a Firefox preference name

Supported values

  • Firefox preferences (for full list, visit about:config in your Firefox browser)

Use gwen.web.firefox.prefs instead.

Since v2.20.0
gwen.web.suppress.images

Controls whether or not image rendering should be suppressed in the browser (firefox only).

Supported values

  • true to suppress
  • false to not suppress (default)

Default value

  gwen {
    web {
      suppress {
        images = false
      }
    }
  }
Since v1.0.0

Masked Settings​

Since v2.48.0

It is a common security practice to never log sensitive data. To support this practice, Gwen will hide all settings that you flag as "masked" by logging their values as ***** in all logs, reports, error messages and console outputs.

Flagging masked settings​

To flag a setting as masked, append :masked to its defined name.

For example, to access a password stored in an environment variable named USER_PASSOWRD, you can read it into a masked setting named user.password as follows:

  user {
    "password:masked" = "${env.USER_PASSWORD}"
  }

Masking input fields​

Since v4.1.0

To mask an input field, add the field's name to the gwen.input.data.maskFields setting. The field value will then be masked in all Gwen outputs.

Using masked settings​

To use a masked setting, just reference it anywhere you need to using it's name (excluding the :masked suffix).

Example:

  When I enter "${user.password}" in the password field

When evaluated, the above will be logged as follows in all outputs:

  When I enter "*****" in the password field
Sample outputs

Console output

Example masked setting logged to console

HTML report output

Example masked setting logged to HTML report

caution

It is your resposibility to enter sensitive data such as passwords into password protected fields to prevent them from being displayed in the browser.

Custom mask character​

You can change the default mask character from * to another character of your choice by assigning it to the gwen.mask.char setting.

Masked Data Bindings​

Values returned by data bindings in the following DSLs can also be masked with the @Masked annotation:

JSONArray Notation​

Since v3.53.0

Lists can be stored in settings in various ways. For example, a list of values could be stored in your settings file as follows:

  my {
    values = [
      "Gwen"
      "Jenkins"
      "Yarn"
      "Docker"
    ]
  }

To access a list of values configured in your settings as a JSON array, append :JSONArray to its setting name in the placeholder references in your feature or meta steps. A JSON array literal containing the values will then be expanded inline.

Example 1

The following will bind the JSON Array ["Gwen","Jenkins","Yarn","Docker"] to the values variable in the current scope:

  Given values is "${my.values:JSONArray}"

Will expand to:

  Given values is "["Gwen","Jenkins","Yarn","Docker"]"

Example 2

The following will inline the JSON Array into a JavaScript expression to get the length and store that in the length variable in the current scope:

  Given length is defined by js "${my.values:JSONArray}.length"
   Then length should be "4"

Will expand to:

  Given length is defined by js "["Gwen","Jenkins","Yarn","Docker"].length"
   Then length should be "4"