Skip to main content

Gwen CLI

Command line interface

tip

Set up Gwen to access the CLI.

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
- depending on gwen.state.level (default is feature)
--parallel-features Execute features in parallel (unconditionally)
-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)

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

As of v3.0.0, 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

npm run gwen -- --version

Output

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

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

Optional switch for outputting CLI usage.

Usage

npm run 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
- depending on gwen.state.level (default is feature)
--parallel-features Execute features in parallel (unconditionally)
-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 (depending on state level). Omit to execute sequenctially.

Examples

Features will run in parallel 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

npm run gwen -- -b --parallel gwen/features/dir

Provide parallel switch to execute the given feature files in parallel

npm run gwen -- --batch --parallel gwen/features/file1.feature gwen/features/file2.feature 

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

npm run gwen -- -b gwen/features/dir

Omit parallel switch to execute the given feature files in sequence

npm run gwen -- -b gwen/features/file1.feature gwen/features/file2.feature 
--parallel-features

Optional switch for executing features in parallel (regardless of state level). Omit to execute sequentially.

Examples

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

npm run gwen -- -b --parallel-features gwen/features/dir

Provide parallel-features switch to execute the given feature files in parallel

npm run gwen -- -b --parallel-features gwen/features/file1.feature gwen/features/file2.feature 

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

npm run gwen -- -b gwen/features/dir

Omit parallel-features switch to execute the given feature files in sequence

npm run 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

npm run gwen -- -b gwen/features/dir

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

npm run gwen -- --batch gwen/features/file.feature

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

npm run gwen -- gwen/features/file.feature

Omit batch switch to open the REPL immediately without executing anything

npm run gwen
-v|--verbose

Optional switch for enabling verbose log output.

Where

  • Option name is either:
    • -v for shorthand
    • --verbose for longhand

Usage

npm run gwen -- -v

Or

npm run gwen -- --verbose
-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

npm run 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

npm run 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.


Examples

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

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

To execute a feature file and load custom properties.

npm run gwen -- --batch --config gwen/props/custom.properties gwen/features/file.feature
-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

npm run gwen -- -b gwen/features/file1.feature

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

npm run 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

npm run gwen -- -b gwen/features/dir

To

npm run 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

npm run gwen -- -b -t @regression gwen/features/dir

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

npm run gwen -- -b --tags @wip gwen/features/file.feature

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

npm run 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

npm run 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

npm run gwen -- -b -i gwen/data/records.csv gwen/features/dir

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

npm run 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

npm run gwen -- -b -m gwen/meta/dir gwen/features/dir

To load a specific meta file before executing a feature file

npm run 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

npm run gwen -- -b gwen/features/dir1 gwen/features/dir2

To execute two feature files

npm run gwen -- --batch gwen/features/file1.feature gwen/features/file2.feature

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

npm run gwen -- --batch gwen/features/dir1 gwen/features/dir2 gwen/features/file.feature

Init command

init [dir]

Command for initialising Gwen in a project directory.

Where

  • [dir] is
    • Not required for JS projects
      • Defaults to a gwen subdirectory in your project
    • Must be specified as . for standalone projects (dot = current directory)

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


Example

To initialse Gwen in a JS project

npm run gwen init

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

  /js-project                 # Your JS project root
โ”œโ”€โ”€ gwen.conf # Project settings
โ””โ”€โ”€ /gwen
โ”œโ”€โ”€ .gitignore # Git ignore file
โ”œโ”€โ”€ README.md
โ”œโ”€โ”€ /browsers # Browser settings
โ”‚ โ”œโ”€โ”€ chrome.conf
โ”‚ โ”œโ”€โ”€ edge.conf
โ”‚ โ”œโ”€โ”€ firefox.conf
โ”‚ โ”œโ”€โ”€ safari.conf
โ”‚ โ”œโ”€โ”€ ie.conf
โ”‚ โ”œโ”€โ”€ remote.conf # Remote web driver settings
โ”‚ โ””โ”€โ”€ README.md
โ”œโ”€โ”€ /env # Environment settings
โ”‚ โ”œโ”€โ”€ local.conf
โ”‚ โ”œโ”€โ”€ dev.conf
โ”‚ โ”œโ”€โ”€ test.conf
โ”‚ โ””โ”€โ”€ README.md
โ”œโ”€โ”€ /features # Features and associative meta
โ”‚ โ””โ”€โ”€ README.md
โ”œโ”€โ”€ /meta # Optional common/reusable meta
โ”‚ โ””โ”€โ”€ README.md
โ””โ”€โ”€ /samples # Sample features and meta