Get Started

tip

Read the introduction to learn more about Gwen before getting started.

Standalone

Use this option to set up Gwen as a standalone installation on your machine.

System requirements

• Linux, Mac or Windows OS
• Chrome, Firefox, Safari, Edge or IE web browser
• Java SE 8+, install Java

1. Download and install Gwen

• Browse the releases and download the binary gwen-web-<version>.zip package of the version you want to install and use
• Extract the downloaded ZIP into a desired directory

This will give you the following file system setup:

 /gwen-web-<version>         # Your installation root ├── gwen                    # Linux launch script ├── gwen.bat                # Windows launch script ├── /bin                    # Gwen scripts ├── /lib                    # Gwen binaries └── /samples                # Sample features and meta

2. Add Gwen to your system path

Add the absolute location of your gwen-web-<version>/bin directory to your system PATH to make Gwen available in any directory on your machine.

Linux

set PATH variable

Run the following command to set the PATH in your current session temporarily or consult your OS manual to make it permanent:

export PATH=$PATH:/absolute/path/to/gwen-web-<version>/bin

Replace:

• /absolute/path/to with the absolute path to the location where you extracted the ZIP in step 1
• <version> with the Gwen version you installed

Windows

set PATH variable

Go to Environment Variables on your Windows system, and find and edit the PATH variable to include the following.

C:\absolute\path\to\gwen-web-<version>\bin

Replace:

• C:\absolute\path\to with the absolute path to the location where you extracted the ZIP in step 1
• <version> with the Gwen version you installed

No automatic updates

You will need to repeat steps 1 and 2 to udpate.

3. Set your default browser

Gwen is configured to use the Chrome browser by default. To change it, create a new gwen.properties file in your user directory and set the following setting to your preferred default:

Amend setting

File: gwen.properties

# default browser to usegwen.web.browser = firefox

Where:

• Browser options include: chrome, firefox, safari, edge, or ie

This example sets Firefox as the default browser.

4. Execute the samples

Run the following command in your installation directory to execute the sample feature specs.

Linux

Launch Gwen

gwen -b -r output/reports samples

Where:

• The -b switch instructs Gwen to exit immediately after executing the samples. Omitting it will open the REPL Console instead of exiting.
• The -r option sets the report output directory to output/reports
• samples is the directory containing the meta and feature samples to execute

CLI usage

An evaluation report will be generated at output/reports/index.html in your directory.

Windows

Launch Gwen

gwen -b -r output\reports samples

Where:

• The -b switch instructs Gwen to exit immediately after executing the samples. Omitting it will open the REPL Console instead of exiting.
• The -r option sets the report output directory to output\reports
• samples is the directory containing the meta and feature samples to execute

CLI usage

An evaluation report will be generated at output\reports\index.html in your directory.

5. Create and execute your own meta and features

Create a new features directory in a preferred location on your machine and start adding your own feature and meta files there. Run the following command in the parent directory to execute them:

Linux

Launch Gwen

gwen -b -r output/reports features

Where:

• The -b switch instructs Gwen to exit immediately after executing your features. Omitting it will open the REPL Console instead of exiting.
• The -r option sets the report output directory to output/reports
• features is the directory containing your meta and feature files to execute

CLI usage

Windows

Launch Gwen

gwen -b -r output\reports features

Where:

• The -b switch instructs Gwen to exit immediately after executing your features. Omitting it will open the REPL Console instead of exiting.
• The -r option sets the report output directory to output\reports
• features is the directory containing your meta and feature files to execute

CLI usage

Workspace

Deprecated

Gwen workspaces are deprecated in favor of JS projects coming to Gwen 3.

Use this option to set up a Gwen workspace that can run on any machine.

System requirements

• Linux, Mac or Windows OS
• Chrome, Firefox, Safari, Edge or IE web browser
• Java SE 8+, install Java

1. Download and extract workspace

• Download and extract this gwen-workspace.zip into a desired location on your computer

This will give you the following file system setup:

 /gwen-workspace             # Your workspace root ├── .gitignore              # Git ignore file ├── gwen                    # Linux launch script ├── gwen.bat                # Windows launch script ├── gwen.properties         # Gwen properties/settings ├── gwen-gpm.jar            # Gwen package manager JAR ├── /browsers               # Browser settings │   ├── chrome.properties   # - default is chrome │   ├── edge.properties │   ├── firefox.properties │   ├── safari.properties │   ├── ie.properties │   └── README.txt ├── /env                    # Environment settings │   ├── local.properties    # - default is local │   └── README.txt ├── /features               # Your feature & meta files go here └── /samples                # Sample features and meta

2. Enable/Disable automatic updates

When you first launch Gwen in your workspace, it will take a little time to download the latest version of itself before starting. On subsequent launches it will start much faster and won't download anything again until we publish a new release in which case it will automatically update itself.

To turn off automatic updates, open the gwen.properties file in your workspace directory in a text editor and amend the gwen.gwen-web.version property from latest to the version number of the release you want to use.

Amend setting

File: gwen.properties

# Gwen package version# --------------------# Gwen web version (specify desired version or latest for auto updates)gwen.gwen-web.version = latest

3. Set your default browser and environment

Gwen workspaces are configured to use the Chrome browser and local environment properties by default. To change either or these, open the Gwen launch script in your workspace directory and set the following variables to your preferred defaults:

Linux

Amend launch script

File: gwen

DEFAULT_BROWSER="firefox"DEFAULT_ENV="local"

Where:

• Browser options include: chrome, firefox, safari, edge, or ie
• The environment is the name of a properties file in the env folder of your workspace

This example sets Firefox as the default browser and leaves the default environment as local.

Windows

Amend launch script

File: gwen.bat

SET DEFAULT_BROWSER=firefoxSET DEFAULT_ENV=local

Where:

• Browser options include: chrome, firefox, safari, edge, or ie
• The environment is the name of a properties file in the env folder of your workspace

This example sets Firefox as the default browser and leaves the default environment as local.

4. Execute the samples

Run the following command in your workspace directory to execute the sample feature specs.

Linux

Launch Gwen

./gwen -b samples

Where:

• The -b switch instructs Gwen to exit immediately after executing the samples. Omitting it will open the REPL Console instead of exiting.
• samples is the directory containing the meta and feature samples to execute

CLI usage

An evaluation report will be generated at target/reports/index.html in your directory.

Windows

Launch Gwen

gwen -b samples

Where:

• The -b switch instructs Gwen to exit immediately after executing the samples. Omitting it will open the REPL Console instead of exiting.
• samples is the directory containing the meta and feature samples to execute

CLI usage

An evaluation report will be generated at target\reports\index.html in your directory.

5. Create and execute your own meta and features

Start adding your own features and meta to the features directory in your workspace. Run the following command to execute your features:

Linux

Launch Gwen

To use the default browser and env/local.properties settings:

./gwen -b features

To use the Edge browser and env/local.properties settings:

./gwen edge -b features

To use the default browser and env/dev.properties settings:

./gwen dev -b features

To use the Edge browser and env/dev.properties settings:

./gwen edge dev -b features

Where:

• The first optional arguments are:
  • browser - the specified browser or default if absent
  • environment - the specified environment or default if absent
• The -b switch instructs Gwen to exit immediately after executing your features. Omitting it will open the REPL Console instead of exiting.
• features is the directory containing your meta and feature files to execute

CLI usage

Windows

Launch Gwen

To use the default browser and env\local.properties settings:

gwen -b features

To use the Edge browser and env\local.properties settings:

gwen edge -b features

To use the default browser and env\dev.properties settings:

gwen dev -b features

To use the Edge browser and env\dev.properties settings:

gwen edge dev -b features

Where:

• The first optional arguments are:
  • browser - the specified browser or default if absent
  • environment - the specified environment or default if absent
• The -b switch instructs Gwen to exit immediately after executing your features. Omitting it will open the REPL Console instead of exiting.
• features is the directory containing your meta and feature files to execute

CLI usage

6. Share your workspace with your team

Push your workspace to a Git repository and share it with your team. A .gitignore file that excludes the target output directory is included. You can keep or delete the samples subdirectory (up to you).

JS Project

Coming to Gwen 3

Support for JS projects coming soon to Gwen 3.

Use this option to add Gwen to a JS project.

System requirements

• Linux, Mac or Windows OS
• Chrome, Firefox, Safari, Edge or IE web browser
• Java SE 8+, install Java
• node 12+, install node