Get Started

tip

Learn more about Gwen before getting started.

Setup

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 17+
  • node 18+

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

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 (and delete or keep them when done).

Launch Gwen

Yarn

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

yarn gwen -p samples -b

or (with long-hand option names)

yarn gwen --profile samples --batch

npm

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

npm run gwen -- -p samples -b

or (with long-hand option names)

npm run gwen -- --profile samples --batch

pnpm

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

pnpm gwen -p samples -b

or (with long-hand option names)

pnpm gwen --profile samples --batch

Where:

• The -p|--profile samples option instructs Gwen to execute the samples as defined in gwen/conf/profiles/samples.conf settings file
• The -b|--batch option instructs Gwen to exit immediately after executing the samples. Omitting it will open the REPL Console instead of exiting.

Gwen Launcher

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