Skip to main content

Get Started

tip

See the introduction to 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.

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:

Open a terminal session​

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

Add Gwen and initialise​

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

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

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

  ./                           # Project root
   ├── gwen.conf               # Gwen settings file
   └── /gwen
       ├── README.md
       ├── .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 local environment by default. To change these, amend the gwen.target.browser and gwen.target.env settings to your preferred values.

Amend settings

File: /project/gwen.conf

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

Gherkin style​

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

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.

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

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