Get Started

tip

Learn more about Gwen before getting started.

Setup

Choose a setup option

The Project option is recommended since everything will be self contained and Git ready.

Project

Since Gwen 3

Use this option to start a new project or add Gwen to an existing one.

System requirements

• Linux, Mac or Windows OS
• Before you can start, you will need to have the following installed:
  • Chrome, Edge, Firefox or Safari browser
  • Java 8+ JRE (no need for JDK unless you really want it)
  • node 12+

Open a terminal session

New project

To start a new project, create a new directory and open a terminal window in that.

Existing project

To add Gwen to an existing project, open a terminal window in the root of that project.

Add Gwen and initialise

Add Gwen using one of the following tools (Yarn is recommended for ease of use).

Yarn

Install the gwen-web package as a dev dependency:

yarn add -D @gweninterpreter/gwen-web

Then, initialize Gwen in the project by running:

yarn gwen init

npm

Install the gwen-web package as a dev dependency in your project:

npm i --save-dev @gweninterpreter/gwen-web

Then, initialize Gwen in the project by running:

npm run gwen init

pnpm

Install the gwen-web package as a dev dependency in your project:

pnpm add -D @gweninterpreter/gwen-web

Then, initialize Gwen in the project by running:

pnpm gwen init

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

  ./                           # Project root
   ├── .gitignore              # Git ignore file
   ├── README.md
   ├── gwen.conf               # Gwen settings file
   └── /gwen
       ├── .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
       │   ├── staging.conf
       │   └── test.conf
       ├── /features           # Features and associative meta
       │   └── README.md
       ├── /meta               # Optional common/reusable meta
       │   └── README.md
       └── /samples            # Sample features and meta

Automatic Updates

Automatic installs and updates to the latest version of Gwen are enabled by default for projects. You can disable them by setting the version field in the gwenWeb section of your package.json file to a specific version.

"gwenWeb": {
  "version": "X.Y.Z"
}

Omitting or setting it to latest will re-enable automatic updates.

Review default settings

All the default settings for your project are pre-configured in the gwen.conf file in the root of your project (created by the init command). You can change any of them at any time to suit your needs.

Default web browser and target environment

Gwen is configured to target the Chrome browser and your test environment by default. To change these, amend the gwen.target.browser and gwen.target.env settings to your preferred values.

Amend settings

.conf

File: /project/gwen.conf

gwen {
  target {
    browser = "chrome"            # chrome|firefox|safari|edge|ie
    env = "test"                  # local|dev|test|staging|prod|..
  }
}

.json

File: /project/gwen.json

{
  "gwen": {
    "target": {
      "browser": "chrome"
      "env": "test"
    }
  }
}

.properties

File: /project/gwen.properties

gwen.target.browser = chrome
gwen.target.env = test

Gherkin style

The following defaults are pre-configured to help promote good Gherkin practice:

• gwen.feature.mode is set to declarative to confine your DSL usage to meta and keep your features clean
• gwen.behavior.rules is set to strict to enforce proper behavioural rules and Given-When-Then order

You can relax these by setting them to imperative and lenient (respectively) if you find them too rigid.

Web driver settings

Gwen has an embedded web driver manager which automatically downloads and installs native web drivers for you on most platforms. If however you need to manage this manually, see Web Driver Management and Web Settings for options.

Execute the samples

To confirm your setup, execute the samples in the gwen/samples directory and delete (or keep) them when done.

Yarn

Launch Gwen

Run the following command in your project to execute the samples.

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

Gwen CLI

npm

Launch Gwen

Run the following command in your project to execute the samples.

npm run gwen -- -b gwen/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

Gwen CLI

pnpm

Launch Gwen

Run the following command in your project to execute the samples.

pnpm gwen -b gwen/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

Gwen CLI

The sample features will execute and a HTML evaluation report will be generated at gwen/output/reports/index.html in your project.

Standalone

Since v1.0.0

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

System requirements

• Linux, Mac or Windows OS
• Before you can start, you will need to have the following installed:
  • Chrome, Edge, Firefox or Safari browser
  • Java 8+ JRE (no need for JDK unless you really want it)

Download and install Gwen

Browse the releases and download the binary package of the version you want to install and use. The donwloaded zip will have a name that matches gwen-web-<version>.zip. Extract the downloaded ZIP into a dedicated applications directory on your machine. This will give you the following Gwen insallation on your file system:

 /applications             # Your top level applications directory
 └──/gwen-web-<version>    # Your Gwen install
    ├── gwen               # Linux launch script
    ├── gwen.bat           # Windows launch script
    ├── /bin               # Gwen scripts
    └── /lib               # Gwen binaries

Add Gwen to your system path

Add the absolute location of your /applications/gwen-web-<version>/bin directory to your system PATH variable to make Gwen accessible 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/applications/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\applications\gwen-web-<version>\bin

Replace:

• C:\absolute\path\to with the absolute path to the location where you extracted the ZIP in step 1 (your drive letter may differ)
• <version> with the Gwen version you installed

No automatic updates

You will need to repeat the above to udpate.

Inititialise a project directory

Create a new directory (called gwen-project for example) somewhere on your machine that will serve as your working Gwen project directory. It should be outside of the /applications directory where you installed Gwen earlier. Open a terminal and run the following command in your gwen-project directory to initialise it:

Launch Gwen

Be sure to include the trailing dot

gwen init .

Gwen CLI

The init command will generate the following files and subdirectorie in your project:

  ./                       # Project root
   ├── .gitignore          # Git ignore file
   ├── README.md
   ├── gwen.conf           # Gwen settings 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

Review default settings

All the default settings for your project are pre-configured in the gwen.conf file in the root of your project (created by the init command). You can change any of them at any time to suit your needs.

Default web browser and target environment

Gwen is configured to target the Chrome browser and your test environment by default. To change these, amend the gwen.target.browser and gwen.target.env settings to your preferred values.

Amend settings

.conf

File: /project/gwen.conf

gwen {
  target {
    browser = "chrome"            # chrome|firefox|safari|edge|ie
    env = "test"                  # local|dev|test|staging|prod|..
  }
}

.json

File: /project/gwen.json

{
  "gwen": {
    "target": {
      "browser": "chrome"
      "env": "test"
    }
  }
}

.properties

File: /project/gwen.properties

gwen.target.browser = chrome
gwen.target.env = test

Gherkin style

The following settings are pre-configured with strictly good Gherkin in mind:

• gwen.feature.mode is set to declarative to help keep your features high level and declarative
• gwen.behavior.rules is set to strict to enforce proper behavioural semantics and Given-When-Then order

You can relax these by setting them to imperative and lenient instead if you find them too rigid.

Web driver settings

Gwen has an embedded web driver manager which automatically downloads and installs native web drivers for you on most platforms. If however you need to manage this manually, see Web Driver Management and Web Settings for options.

Execute the samples

To confirm your setup, execute the samples in the samples directory and delete (or keep) them when done.

Launch Gwen

Run the following command in your project to execute the samples.

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

Gwen CLI

The sample features will execute and a HTML evaluation report will be generated at output/reports/index.html in your project.