Get Started

tip

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

Setup

Choose a setup option

JS Project

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

System requirements

• Linux, Mac or Windows OS
• Chrome, Firefox, Safari, or Edge browser
• Java 8+ (install Java)
• node 12+ (install node)

Add Gwen to your project and initialise

note

If you don't have a JS project, you can create one by installing node and running npm init in a new directory and use that.

Open a terminal in the root of your project and run the following commands to add Gwen as a dev dependency and initialise your project for Gwen:

npm

Install the gwen-web package:

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

In the scripts section of your package.json file, add the following entry:

{
  "scripts": {
    "gwen": "gwen"
  }
}

Then, initialize Gwen in the project by running:

npm run gwen init

Yarn

yarn add -D @gweninterpreter/gwen-web
yarn gwen init

pnpm

pnpm add -D @gweninterpreter/gwen-web
pnpm gwen init

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

 /project                    # Your 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

Automatic Updates

Automatic installs and updates to the latest version of Gwen are enabled by default for JS 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.

Set your default browser

Gwen is configured to use the Chrome browser by default. To change this default, amend the gwen.target.browser setting in your /project/gwen.conf file to load your preferred browser settings instead of chrome.

Amend setting

File: /project/gwen.conf

gwen {
  target {
    browser = "chrome"            # <- Change to firefox, safari, edge, or ie
  }
}

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

npm

Launch Gwen

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

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

Yarn

Launch Gwen

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

pnpm

Launch Gwen

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

A HTML evaluation report will be generated at gwen/output/reports/index.html in your project.

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, or Edge browser
• Java 8+ (install Java)

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                # Your standalone project root
 ├── gwen.conf           # Project settings
 ├── .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

Set your default browser

Gwen is configured to use the Chrome browser by default. To change this default, amend the gwen.cli.options.conf setting in your /project/gwen.conf file to load your preferred browser settings instead of chrome.

Amend setting

File: /project/gwen.conf

gwen {
  cli {
    options {
      config = [
        "browsers/chrome.conf", // <- Change to firefox, safari, edge, or ie
        "env/local.conf"
      ]
    }
  }
}

For example, to change it to Firefox, amend the highlighted settings line above to:

"browsers/firefox.conf",

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

Launch Gwen

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

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

A HTML evaluation report will be generated at output/reports/index.html in your project.

Workspace

Deprecated

Gwen workspaces have been deprecated in favor of JS projects since Gwen 3.

• Migrate to Gwen 3