Skip to main content

Gwen CLI

Command line interface

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 switch. 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
-b, --batch Exit when execution completes (omit to open REPL)
-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)
-p, --properties files Properties files (deprecated, use -c|--conf instead)
-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 file with column headers)
-m, --meta files|dirs Meta files or directories to load (comma separated)
files|dirs Feature files or directories to execute (space separated)
Command: init [options] [dir]
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

Environment variables

The following environment variables can be set to override configured settings:

SinceEnvironment variableValuesOverrides settingAffects CLI option
v3.16.0GWEN_BROWSERchrome|edge|
firefox|safari|ie
gwen.target.browser
v3.23.0GWEN_ENVlocal|dev|
test|staging|
prod|..
gwen.target.env
v3.16.0GWEN_DRY_RUNtrue|falsegwen.cli.options.dryRun-n, --dry-run
v3.16.0GWEN_PARALLELtrue|falsegwen.cli.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

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

Configurable CLI options

Since Gwen 3

CLI options can be configured in settings enabling you to customize your own launch profile (excluding --version and --help).

CLI reference

Options

--version

Optional switch for outputting the Gwen version.

Usage

yarn gwen --version

Output

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

Welcome to gwen-web v3.0.0
gweninterpreter.org
--help

Optional switch for outputting CLI usage.

Usage

yarn gwen --help

Output

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

Welcome to gwen-web v3.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
-c, --conf files Settings files: conf, json or properties (comma separated)
-p, --properties files Properties files (deprecated, use -c|--conf instead)
-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 file with column headers)
-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]
dir Project directory to initialise (default is gwen)
--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 switch is provided and gwen.state.level is feature

Provide parallel switch to execute all feature files in a given directory in parallel

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

Provide parallel switch to execute the given feature files in parallel

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

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

yarn gwen -b gwen/features/dir

Omit parallel switch to execute the given feature files in sequence

yarn gwen -b gwen/features/file1.feature gwen/features/file2.feature 
-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

Provide batch switch to execute all feature files in a given directory and then exit

yarn gwen -b gwen/features/dir

Provide batch switch to execute the given feature file and then exit

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

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

yarn gwen gwen/features/file.feature

Omit batch switch to open the REPL immediately without executing anything

yarn gwen
-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
-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
-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

Provide dry run switch to find and report any errors in all feature and meta files in a given directory

yarn gwen -b -n gwen/features/dir

Provide dry run switch to find and report any errors in the given feature file and its associative meta

yarn gwen --batch --dry-run gwen/features/file.feature
-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 -p|--properties option in early version of Gwen has been deprecated and replaced in favor of this option since Gwen 3. The former will still work for properties files until the next major release (and will be removed then). You should use this launch option going forward.

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/browsers/firefox.conf,gwen/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
-p|--properties <files>

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

Deprecated since Gwen 3, use -c|--conf instead.

Where

  • Option name is either:
    • -p for shorthand
    • --properties for longhand
  • <files> is a comma separated list of .properties file paths.

Examples

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

gwen -b -p browsers/firefox.properties,env/dev.properties features/dir

To execute a feature file and load custom properties.

gwen --batch --properties props/custom.properties features/file.feature
-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 Gwen 3, HTML reports are generated by default and all reports are written to the output directory defined by the gwen.cli.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.cli.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
-f|--format <reports>

Optional list of report formats to output.

Where


Since Gwen 3, HTML reports are generated by default and all reports are written to the output directory defined by the gwen.cli.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
-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
-i|--input-data <file>

Optional CSV data feed file.

Where

  • Option name is either:
    • -i for shorthand
    • --input-data for longhand
  • <file> is a path to a CSV data file

See CSV 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
-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

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

Init command

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
├── gwen.conf # Gwen settings file
└── /gwen
├── README.md
├── .gitignore # Git ignore file
├── /browsers # Browser settings
│ ├── chrome.conf
│ ├── edge.conf
│ ├── firefox.conf
│ ├── ie.conf
│ ├── README.md
│ └──safari.conf
├── /env # Environment settings
│ ├── dev.conf
│ ├── local.conf
│ ├── prod.conf
│ ├── README.md
│ └── test.conf
├── /features # Features and associative meta
│ └── README.md
├── /meta # Optional common/reusable meta
│ └── README.md
└── /samples # Sample features and meta

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
├── docker-compose.yml # Docker compose file
├── Dockerfile # Docker image file
└── /browsers # Browser settings
├── browsers.json # Selenoid browsers file
└── selenoid.conf # Selenoid settings
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