Skip to main content

Settings Reference

Core Settings

gwen.assertion.mode

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

Supported values

  • hard to halt feature execution on the first assertion error and report failure
  • 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"
}
}
gwen.associative.meta

Controls whether or not same named feature and meta files in a directory are to be exclusively associated.

Supported values

  • true to enable association
    • Gwen will load a discovered meta file only if it has the same name and is in the same directory as the current feature being executed.
  • false to disable association
    • Gwen will unconditionally load every meta file discovered in the path to the current feature being executed.

Default value since v3.0.0

  gwen {
associative {
meta = true
}
}

Default value in prior versions

  gwen {
associative {
meta = false
}
}
gwen.auto.discover.data.csv

Enables or disables automatic discovery and loading of CSV data feed files.

Supported values

  • true to enable
  • false to disable
    • Prevents Gwen from automatically discovering and loading CSV files in the path of an executing feature, forcing the user to explicitly specify the CSV file to load through the -i|--input-data CLI option at launch time.

Default value since v3.0.0

  gwen {
auto {
discover {
data {
csv = false
}
}
}
}

Default value in prior versions

  gwen {
auto {
discover {
data {
csv = true
}
}
}
}
gwen.auto.discover.meta

Enables or disables automatic discovery and loading of meta files.

Supported values

  • true to enable
  • false to disable
    • Prevents Gwen from automatically discovering and loading meta files in the path of an executing feature, forcing the user to load meta explicitly through the -m|--meta CLI option or meta imports.

Default value

  gwen {
auto {
discover {
meta = true
}
}
}
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:
    • 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"
}
}
gwen.feature.dialect

Sets the default Gherkin dialect (or spoken language).

Supported values

Default value

  gwen {
feature {
dialect = "en"
}
}
gwen.feature.failfast.enabled

Enables or disables fail fast mode at the feature level.

Formerly gwen.feature.failfast (prior to v3.0.0)

Supported values

  • true to enable
    • 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
}
}
}
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
    • Will resume with the next feature if the previous one fails.

Default value

  gwen {
feature {
failfast {
exit = false
}
}
}
gwen.feature.mode

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

Supported values

  • declarative
  • 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"
}
}
}
gwen.mask.char

Sets the masking character used for logging masked settings.

Supported values

  • Any single character

Default value

  gwen {
mask {
char = "*"
}
}
gwen.baseDir

Sets the base Gwen project directory

Supported values

  • A relative or absolute directory location
    • The output directory

Default value

  gwen {
baseDir = "gwen"
}
gwen.outDir

Sets the default Gwen output directory.

Supported values

  • A relative or absolute directory location
    • The output directory

Default value

  gwen {
outDir = "{gwen.baseDir}/output"
}
gwen.parallel.maxThreads

Sets the maximum number of permitted parallel executor threads.

Supported values

  • A positive integer value denoting the maximum number of threads to allow
  • Zero to allow all available cores to be utilitised (one thread per core)

Default value

  gwen {
parallel {
maxThreads = 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


Example: A 5 second interval would stagger 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
}
}
}
gwen.report.overwrite

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

Supported values

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

Default value

  gwen {
report {
overwrite = true
}
}
gwen.report.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
  • false to not use colors

Default value

  gwen {
report {
console {
log {
colors = true
}
}
}
}
gwen.report.suppress.meta

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

Supported values

  • true to suppress meta
  • 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
}
}
}
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 value

  gwen {
report {
slideshow {
framespersecond = 4
}
}
}
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)
  • scenario for scenario level state that is not shared across scenarios (each scenario gets a new state)

Default value

  gwen {
state {
level = "feature"
}
}

Web Settings

gwen.web.accept.untrusted.certs

Controls whether or not the web driver should accept untrusted (self signed) SSL certificates.

Supported values

  • true to accept
  • false to decline

Default value

  gwen {
web {
accept {
untrusted {
certs = true
}
}
}
}
gwen.web.authorize.plugins

Controls whether or not to permit browser plugins to run.

Supported values

  • true to permit
  • false to deny

Default value

  gwen {
web {
authorize {
plugins = false
}
}
}
gwen.target.browser

Sets the default browser that Gwen will target.

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

Supported values

  • chrome for Chrome browser
  • firefox for Firefox browser
  • safari for Safari browser
  • edge for Edge browser, since v2.35.0
  • ie for IE browser

Default value

  gwen {
target {
browser = "chrome"
}
}
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


Notes

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

Default value

  gwen {
web {
browser {
headless = false
}
}
}
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

This setting has no default value and will not be honoured if gwen.web.maximize is set to true.

Example

  gwen {
web {
browser {
size = "1200x800"
}
}
}
gwen.web.capability.<name>

Sets a desired web capability on the underlying web driver.

Some capabilities are browser specific. If you set a capability that is not supported for the browser you are targeting, then it will have no effect and will be ignored. Each setting is a new entry with a different <name>. You can configure as many as you need.

Where

Supported values

  • Only capabilities that accept values of type String, Integer, or Boolean are supported.

Example

  gwen {
web {
capability {
ignoreZoomSetting = true
}
}
}
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 value

  gwen {
web {
capture {
screenshots {
enabled = false
}
}
}
}
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 value

  gwen {
web {
capture {
screenshots {
highlighting = false
}
}
}
}
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 value

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

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

Supported values

  • HTML style strings

Default value

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

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

Supported values

  • true to enable auto focus
  • false to disable auto focus

Default value

  gwen {
web {
implicit {
element {
focus = true
}
}
}
}
gwen.web.implicit.js.locators

Controls 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).

Supported values

  • true to enable
  • false to disable

Default value

  gwen {
web {
implicit {
js {
locators = false
}
}
}
}
gwen.web.locator.wait.seconds

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

Supported values

  • A positive integer denoting a number of seconds
Default value: gwen.web.wait.seconds or 10 if not configured

Default value

  gwen {
web {
locator {
wait {
seconds = 5
}
}
}
}
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 value

  gwen {
web {
maximize = false
}
}
gwen.web.remote.localFileDetector

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

Supported values

  • true to enable
  • false to disable


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

Default value

  gwen {
web {
remote {
localFileDetector = false
}
}
}
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 value

  gwen {
web {
sendKeys {
clearFirst = false
}
}
}
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 value

  gwen {
web {
sendKeys {
clickFirst = false
}
}
}
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 value

  gwen {
web {
throttle {
msec = 100
}
}
}
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"
}
}
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


This value will also be used as the locator timeout unless gwen.web.locator.wait.seconds is set to a different value.

Default value

  gwen {
web {
wait {
seconds = 10
}
}
}

Chrome

gwen.web.chrome.args

A chrome preference value.

Supported values


Notes

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

Example

  gwen {
web {
chrome {
args = [
"--ignore-certificate-errors",
"--incognito"
]
}
}
}
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.

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 loaed settings files are merged.

Example

  gwen {
web {
chrome {
extensions = [
"path/to/extenstion.crx"
]
}
}
}
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
}
}
}
}
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"
}
}
}
gwen.web.chrome.prefs

A chrome preference value.

Supported values


Notes

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

Example

  gwen {
web {
chrome {
prefs = [
"download.default_directory=path/to/dir",
"prompt_for_download=false"
]
}
}
}
gwen.web.chrome.pref.<name>

Sets a Chrome preference.

Where

Supported values

  • A preference value

Use gwen.web.chrome.prefs instead.

Edge

gwen.web.edge.args

A chrome preference value.

Supported values


Notes

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

Example

  gwen {
web {
edge {
args = [
"--ignore-certificate-errors",
"--incognito"
]
}
}
}
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.

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 loaed settings files are merged.

Example

  gwen {
web {
edge {
extensions = [
"path/to/extenstion.crx"
]
}
}
}
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
}
}
}
}
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"
}
}
}
gwen.web.edge.prefs

A chrome preference value.

Supported values


Notes

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

Example

  gwen {
web {
edge {
prefs = [
"download.default_directory=path/to/dir",
"prompt_for_download=false"
]
}
}
}
gwen.web.edge.pref.<name>

Sets a Edge preference.

Where

Supported values

  • A preference value

Use gwen.web.edge.prefs instead.

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 loaed settings files are merged.

Example

  gwen {
web {
firefox {
prefs = [
"browser.download.useDownloadDir=false",
"browser.download.loglevel=Error"
]
}
}
}
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)
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 value

  gwen {
web {
suppress {
images = false
}
}
}

CLI Settings

gwen.cli.options.parallel

Controls whether or not the --parallel switch will be passed to the Gwen CLI by default.

Supported values

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

Default value

  gwen {
cli {
options {
parallel = false
}
}
}
CLI option: --parallel
Since v3.0.0
gwen.cli.options.parallelFeatures

Controls whether or not the --parallel-features switch will be passed to the Gwen CLI by default.

Supported values

  • true to always launch Gwen with parallel features mode enabled by default
  • false to only launch Gwen with parallel features mode enabled if the --parallel-features switch is explicitly passed.

Default value

  gwen {
cli {
options {
parallelFeatures = false
}
}
}
gwen.cli.options.batch

Controls whether or not the -b|--batch switch will be passed to the Gwen CLI by default.

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 switch is explicitly passed and in REPL mode if it is not.

Default value

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

Controls whether or not the -v|--verbose switch will be passed to the Gwen CLI by default.

Supported values

  • true for verbose logging mode
  • false for pretty logging mode

Default value

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

Controls whether or not the -n|--dry-run switch will be passed to the Gwen CLI by default.

Supported values

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

Default value

  gwen {
cli {
options {
dryRun = false
}
}
}
CLI option: -n|--dry-run
Since v3.0.0
gwen.cli.options.conf

Sets the -c|--conf option to pass to the Gwen CLI by default.

Supported values

  • A list of zero or more settings file paths


Notes

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

Default value (for JS projects only)

  gwen {
cli {
options {
conf = [
"${gwen.baseDir}/browsers/${gwen.target.browser}.conf",
"${gwen.baseDir}/env/${gwen.target.env}.conf"
]
}
}
}

If you don't want a value, set it to empty. You'll then have to explictly specify the -c|--config option on the CLI when you want to load settings.

  gwen {
cli {
options {
conf = [
]
}
}
}
CLI option: -c|--conf
Since v3.0.0
gwen.cli.options.report

Sets the -r|--report option to pass to the Gwen CLI by default.

Supported values

  • A path to a directory to output all reports to.

Default value

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

Sets the -f|--format option to pass to the Gwen CLI by default.

Supported values


Notes

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

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

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

Example with multiple entries

  gwen {
cli {
options {
format = [
"html",
"junit"
]
}
}
}
CLI option: -f|--format
Since v3.0.0
gwen.cli.options.tags

Sets the -t|--tags option to pass to the Gwen CLI by default.

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 loaed settings files are merged.

Default value (empty for no tags)

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

Example setting two default tags

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

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

Supported values

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

Default value (blank for no input file)

  gwen {
cli {
options {
inputData = ""
}
}
}

Example setting a default data file

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

Sets the -m|--meta option to pass to the Gwen CLI by default.

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 loaed settings files are merged.

Default value (blank for no meta)

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

Example setting two default meta files

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

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

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 loaed settings files are merged.

Default value (empty for no feature files/dirs)

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

Example setting two default feature files

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