Skip to main content

Launching Gwen

Since v1.0.0

Options and usage​

All launch operations can be invoked using the Gwen CLI. To list the usage and all available options, invoke Gwen with only the --help option. The following output will be displayed:

Usage: gwen [options] [files|dirs]

  --version                Print Gwen version
  --help                   Print CLI usage
  --parallel               Execute features or scenarios in parallel
                           - features if gwen.state.level = feature (default)
                           - scenarios if gwen.state.level = scenario
  --repl                   Open REPL (forcefully) regardless of other options
  -p, --profile name       Name of profile to launch
  -b, --batch              Exit when execution completes (ignored if --repl is specified)
  -v, --verbose            Enable verbose log output
  -d, --debug              Enable breakpoints and interactive debugging
  -n, --dry-run            Check all syntax and bindings and report errors
  -c, --conf files         Settings files: conf, json or properties (comma separated)
  -r, --report dir         Directory to output generated report(s) to
  -f, --formats reports    Report formats to include in output (comma separated)
                           - html,results,junit,json,rp,none (default = html, rp deprecated)
  -t, --tags filter        Tags to @include or ~@exclude (comma separated)
  -i, --input-data file    Input data feed (csv or json file)
  -m, --meta files|dirs    Meta files or directories to load (comma separated)
  files|dirs               Feature files or directories to execute (space separated)
Command: init [dir]
Initialise project directory
  dir                      Project directory to initialise (default is gwen)
  --docker                 Generate files in project for running Gwen in Docker
  --jenkins                Generate files in project for running Gwen on Jenkins
  --force                  Regenerate and overwrite previously initialised files
Command: format files|dirs
Format feature and meta files
  files|dirs               Feature/meta files or dirs to format (space separated)
  --pretty                 Pretty Gherkin format (default)

Environment variables​

The following environment variables can be set to override certain settings as below:

SinceEnvironment variableValuesOverrides settingAffects CLI option
v3.23.0GWEN_ENVlocal|dev|
test|staging|
prod|..		gwen.target.env
v4.0.0GWEN_PROFILEName of the profile to launch-p, --profile
v3.16.0GWEN_BROWSERchrome|edge|
firefox|safari|ie		gwen.target.browser
v3.16.0GWEN_DRY_RUNtrue|falsegwen.launch.options.dryRun-n, --dry-run
v3.16.0GWEN_PARALLELtrue|falsegwen.launch.options.parallel--parallel
v3.18.0GWEN_THREADSauto|numbergwen.parallel.maxThreads
v3.16.0GWEN_HEADLESStrue|falsegwen.web.browser.headless
v3.18.0GWEN_VIDEOtrue|falseselenoid:options.enableVideo
v3.71.3GWEN_WEB_VERSIONVersion or Semver range (Overrides Gwen web version in package.json)

System properties and JVM options​

In addition to the above, you can also pass any number of Java system properties or JVM options to the CLI:

  • -Dprop.name=value
    • To pass a system property to the Java process that runs Gwen
    • Will override any same named Gwen setting
    • Will be picked up by ${prop.name} placeholders in feature and meta specs
  • -J<JVM_OPTION>
    • To pass a JVM option to the Java process that runs Gwen
    • The -J prefix will be stripped and <JVM_OPTION> will be passed through

The enviornment variable overrides in the previous section however do have precedence over these.

Launch Options​

Launch Settings

Default launch options and arguments can also be configured in settings (excluding --version and --help) so you don't have to explictly specify them on the command line.

--version

Optional switch for outputting the Gwen version.

Usage

yarn gwen --version

Output

   __ ___      _____ _ __     _    
  / _` \ \ /\ / / _ \ '_ \   { \," 
 | (_| |\ V  V /  __/ | | | {_`/   
  \__, | \_/\_/ \___|_| |_|   `    
  |___/                            

Welcome to gwen-web v4.0.0
gweninterpreter.org
Since v1.0.0
--help

Optional switch for outputting CLI usage.

Usage

yarn gwen --help

Output

   __ ___      _____ _ __     _    
  / _` \ \ /\ / / _ \ '_ \   { \," 
 | (_| |\ V  V /  __/ | | | {_`/   
  \__, | \_/\_/ \___|_| |_|   `    
  |___/                            

Welcome to gwen-web v4.0.0
gweninterpreter.org

Usage: gwen [init] [options] <args>...

  --version               Print Gwen version
  --help                  Print CLI usage
  --parallel              Execute features or scenarios in parallel
                          - features if gwen.state.level = feature (default)
                          - scenarios if gwen.state.level = scenario
  -b, --batch             Exit when execution completes (omit to open REPL)
  -v, --verbose           Enable verbose log output
  -n, --dry-run           Check all syntax and bindings and report errors
  -p, --profile name      Name of profile to launch
  -c, --conf files        Settings files: conf, json or properties (comma separated)
  -r, --report dir        Directory to output generated report(s) to
  -f, --formats reports   Report formats to include in output (comma separated)
                          - html,junit,json,rp,none (default is html)
  -t, --tags filter       Tags to @include or ~@exclude (comma separated)
  -i, --input-data file   Input data feed (csv or json file)
  -m, --meta files|dirs   Meta files or directories to load (comma separated)
  files|dirs              Feature files or directories to execute (space separated)
Command: init [dir]
Initialise project directory
 dir                      Project directory to initialise (default is gwen)
 --docker                 Generate files in project for running Gwen in Docker
 --jenkins                Generate files in project for running Gwen on Jenkins
 --force                  Regenerate and overwrite previously initialised files
Command: format files|dirs
Format feature and meta files
 files|dirs               Feature/meta files or dirs to format (space separated)
 --pretty                 Pretty Gherkin format (default)
Since v1.0.0
--parallel

Optional switch for executing features or scenarios in parallel (one per CPU core) depending on the configured state level. Omit to execute sequentially.

Will utilise all avaialable CPU cores unless gwen.parallel.maxThreads is configured with an explicit maximum.

Examples

Features will run in parallel (one per CPU core) when the parallel launch option is provided and gwen.state.level is feature

Specify the parallel launch option to execute all feature files in a given directory in parallel

yarn gwen -b --parallel gwen/features/dir

Specify the parallel launch option to execute the given feature files in parallel

yarn gwen -b --parallel gwen/features/file1.feature gwen/features/file2.feature

Omit parallel launch option to execute all feature files in a given directory in sequence

yarn gwen -b gwen/features/dir

Omit parallel launch option to execute the given feature files in sequence

yarn gwen -b gwen/features/file1.feature gwen/features/file2.feature
Since v1.0.0
--repl

Optional switch to open REPL either even if batch mode is enabled or features are specified.

Where

  • Option name is:

    • --repl (longhand only supported)

Examples

Specify the repl launch option to open the REPL

yarn gwen --repl

Specify the repl launch option to bypass feature execution and open the REPL

yarn gwen --repl gwen/features/file.feature

Specify the repl launch option to open REPL even if batch is specified

yarn gwen --repl -b
yarn gwen --repl --batch

Specify the repl launch option to bypass feature execution and open the REPL even if batch is specified

yarn gwen --repl -b gwen/features/file.feature
yarn gwen --repl --batch gwen/features/file.feature
Since v4.0.0
-b|--batch

Optional switch to execute features and then exit immediately (batch mode). Omit to open REPL instead of exiting (interactive mode).

Where

  • Option name is either:

    • -b for shorthand
    • --batch for longhand

Examples

Specify the batch launch option to execute all feature files in a given directory and then exit

yarn gwen -b gwen/features/dir

Specify the batch launch option to execute the given feature file and then exit

yarn gwen --batch gwen/features/file.feature

Omit the batch launch option to execute the given feature file and then open the REPL

yarn gwen gwen/features/file.feature

Omit the batch launch option to open the REPL immediately without executing anything

yarn gwen
Since v1.0.0
-p|--profile <name>

Name of profile to launch.

Where

  • You can use either:

    • -p for shorthand
    • --profile for longhand
  • <name> is the name of a profile with associated gwen/conf/profiles/<name>.conf settings to load and launch with.

Examples

To load all settings and execute all features defined in the gwen/conf/profiles/custom.conf settings and open REPL:

gwen -p custom

To load all settings and execute all features defined in the gwen/conf/profiles/custom.conf settings and exit when done:

gwen -p custom -b
Since v4.0.0
-v|--verbose

Optional switch for enabling verbose log output.

Where

  • Option name is either:

    • -v for shorthand
    • --verbose for longhand

Usage

yarn gwen -v

Or

yarn gwen --verbose
Since v3.0.0
-d|--debug

Optional switch for enabling breakpoints and debugging.

Where

  • Option name is either:

    • -d for shorthand
    • --debug for longhand

Usage

yarn gwen -d

Or

yarn gwen --debug
Since v3.2.0
-n|--dry-run

Optional switch to find and report any syntax or binding errors that may exist in your feature and meta files. Use this to validate your feature and meta files before committig to an automation cycle. Omit to execute.

Where

  • Option name is either:

    • -n for shorthand
    • --dry-run for longhand

Output

  • A HTML report highlighting all errors found (if any)
  • Errors are also logged to the console

Examples

Specify the dry run launch option to find and report any errors in all feature and meta files in a given directory

yarn gwen -b -n gwen/features/dir

Specify the dry run launch option to find and report any errors in the given feature file and its associative meta

yarn gwen --batch --dry-run gwen/features/file.feature
Since v1.0.0
-c|--conf <files>

Optional list of settings files to load. These are loaded in the order given with latter entries overriding the former.

Where

  • Option name is either:

    • -c for shorthand
    • --conf for longhand
  • <files> is a comma separated list of .conf, .json, or .properties settings file paths.

The following settings files are implicity added as defaults:


Examples

To execute all feature files in a directory on the firefox browser using dev environment settings.

yarn gwen -b -c gwen/conf/browsers/firefox.conf,gwen/conf/env/dev.conf gwen/features/dir

To execute a feature file and load custom properties.

yarn gwen --batch --config gwen/props/custom.properties gwen/features/file.feature
/Link>
Since v3.0.0
-r|--report <dir>

Optional directory to output generated reports to.

Where

  • Option name is either:

    • -r for shorthand
    • --report for longhand
  • <dir> is the path to the directory where generated reports will be written to.

Since v3.0.0, HTML reports are generated by default and all reports are written to the output directory defined by the gwen.launch.options.report setting (which you can change if you wish). You therefore only need to specify this report option if you want to override this default on the CLI for a particular launch. If additionally, you don't want any reports to be generated by default, you can set the gwen.launch.options.format setting to none.


Examples

To execute a feature file and output a HTML report to the default output directory

yarn gwen -b gwen/features/file1.feature

To execute all feature files in a directory and output HTML reports to nominated directory

yarn gwen -b --report nominated/outdir gwen/features/dir
Since v1.0.0
-f|--format <reports>

Optional list of report formats to output.

Where


Since Since v3.0.0, HTML reports are generated by default and all reports are written to the output directory defined by the gwen.launch.options.report setting (which you can change if you wish). You therefore no longer need to explictly specify the -r|--report option with this option unless you want to override the default on the CLI for a particular launch.


Examples

To

yarn gwen -b gwen/features/dir

To

yarn gwen --batch gwen/features/file.feature
Since v1.0.0
-t|--tags <filter>

Optional list of tags to include or exclude for execution.

Where

  • Option name is either:

    • -t for shorthand
    • --tags for longhand

  • <filter> is a comma separated list of one or more of the following tag patterns:

    • @Tag to include a tag
    • ~@Tag to exclude a tag

Examples

To execute all features or scenarios tagged with @regression in a given directory

yarn gwen -b -t @regression gwen/features/dir

To execute all scenarios tagged with @wip in a given feature file

yarn gwen -b --tags @wip gwen/features/file.feature

To execute all scenarios not tagged with @wip in a given feature file

yarn gwen -b -t ~@wip gwen/features/file.feature

To execute all features or scenarios tagged with @regression and not tagged with @wip in a given directory

yarn gwen -b --tags @regression,~@wip gwen/features/dir
Since v1.0.0
-i|--input-data <file>

Optional CSV of JSON data feed file.

Where

  • Option name is either:

    • -i for shorthand
    • --input-data for longhand
  • <file> is a path to a CSV or JSON data file

See data feeds for more details.


Examples

To execute all feature files in a directory for every record in a CSV file

yarn gwen -b -i gwen/data/records.csv gwen/features/dir

To execute a feature file for every record in a CSV file

yarn gwen -b --input-data gwen/data/records.csv gwen/features/file.feature

To execute all feature files in a directory for every record in a JSON file (Since v3.47.0)

yarn gwen -b -i gwen/data/records.json gwen/features/dir

To execute a feature file for every record in a JSON file (Since v3.47.0)

yarn gwen -b --input-data gwen/data/records.json gwen/features/file.feature
Since v1.0.0
-m|--meta <files|dirs>

Optional list of meta files or directories to load.

Where

  • Option name is either:

    • -m for shorthand
    • --meta for longhand
  • <files|dirs> is a comma separated list of meta file paths or directories (containing meta files) to load

Examples

To load all meta files in a directory before executing each feature file in a given directory

yarn gwen -b -m gwen/meta/dir gwen/features/dir

To load a specific meta file before executing a feature file

yarn gwen -b -m gwen/meta/file.meta gwen/features/file.feature
Since v1.0.0

Launch Arguments​

[files|dirs]

Optional list of feature files or directories to execute (optional).

Where

  • <files|dirs> is a space separated list of feature files or directories (containing feature files) to execute

Examples

To execute all features in two given directories

yarn gwen -b gwen/features/dir1 gwen/features/dir2

To execute two feature files

yarn gwen --batch gwen/features/file1.feature gwen/features/file2.feature

To execute all features in two given directories and another feature file

yarn gwen --batch gwen/features/dir1 gwen/features/dir2 gwen/features/file.feature
Since v1.0.0

Project Init​

init [options] [dir]

Command for initialising Gwen in a project directory.

Where

  • [options] Can be one or more space separated switches including:

    • --docker
      • Include to also generate files in your project for running Gwen in Docker
    • --jenkins
      • Include to also generate a Jenkins pipeline file in your project
    • --force
      • Include to regenerate and overwrite any previously initialised files.

  • [dir] is

    • Defaults to a gwen subdirectory in your project if not specified

Run this command in your project directory to initialise Gwen in it. You can then start using Gwen in your project.


Example

To initialse a Gwen project

yarn gwen init

The init command will generate the following Gwen files and subdirectories in your project

./                              # Project root
 ├── .gitignore                 # Git ignore file
 ├── README.md
 ├── gwen.conf                  # Common settings
 └── /gwen
     ├── .gitignore             # Git ignore file
     ├── /conf
     │   ├── /browsers          # Browser settings
     │   │   ├── chrome.conf
     │   │   ├── edge.conf
     │   │   ├── firefox.conf
     │   │   ├── README.md
     │   │   └── safari.conf
     │   ├── /env               # Environment settings
     │   │   ├── dev.conf
     │   │   ├── local.conf
     │   │   ├── prod.conf
     │   │   ├── README.md
     │   │   ├── staging.conf
     │   │   └── test.conf
     │   └── /profiles          # Profile settings
     │       ├── README.md
     │       └── samples.conf
     ├── /features              # Features and associative meta
     │   ├── README.md
     │   └── /samples          # Samples
     └── /meta                  # Common/reusable meta
         └── README.md
Since v3.0.0

Project Init options​

init --docker [--force] [dir]

Generate all the files in your project required for running Gwen in Docker.

Where

  • --force
    • Include to regenerate and overwrite any previously generated docker files.

  • [dir] is the directory to generate the docker files into

    • Defaults to the gwen subdirectory in your project if not specifed
yarn gwen init --docker

The init command will generate the following files

./                           # Project root
 └── /gwen
     ├── .env                # Docker env file
     ├── docker-compose.yml  # Docker compose file
     ├── Dockerfile          # Docker image file
     └── /browsers           # Browser settings
         ├── browsers.json   # Selenoid browsers file
         └── selenoid.conf   # Selenoid settings
Since v3.16.0
init --jenkins [--force] [dir]

Generate a Jenkins pipeline file for your project (Jenkinfile).

Where

  • --force
    • Include to regenerate and overwrite any previously generated Jenkinsfile.

  • [dir] is the directory to generate the Jenkinfile into

    • Defaults to the gwen subdirectory in your project if not specifed
yarn gwen init --jenkins

The init command will generate the following files

./                           # Project root
 └── /gwen
     └── Jenkinsfile         # Jenkins pipeline file
Since v3.16.0

Pretty formatting​

format --pretty <files|dirs>

Command for formatting feature and meta files for consistent and tidy Gherkin. Pretty formatting involves indenting all Gherkin nodes in a standard manner and removing uncecessary whitespace. Formatted files will be updated in place.

Where

  • --pretty
    • Is the pretty formatting option (default)
    • This is currently the default and only supported formatting option

  • <files|dirs> (mandatory) is a space separated list of feature/meta files or directories to format

Comment erasure

This command will remove any comment lines you may have in your files. You should restore them manually after running the command if you don't want to lose them.

Example

To format all feature and meta files in the current directory

yarn gwen format --pretty .

To format all feature and meta files in a given directory

yarn gwen format --pretty path/to/dir

To format a single feature file

yarn gwen format --pretty path/to/file.feature

To format a single feature file

yarn gwen format --pretty path/to/file.feature

To format a single meta file

yarn gwen format --pretty path/to/file.meta
Since v3.38.0