Get Started
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
- Standalone
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
- New project
- Existing project
To start a new project, create a new directory and open a terminal window in that.
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
- npm
- pnpm
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
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
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 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.
- conf
- json
- properties
File: /project/gwen.conf
gwen {
target {
browser = "chrome" # chrome|firefox|safari|edge|ie
env = "test" # local|dev|test|staging|prod|..
}
}
File: /project/gwen.json
{
"gwen": {
"target": {
"browser": "chrome"
"env": "test"
}
}
}
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 todeclarative
to confine your DSL usage to meta and keep your features cleangwen.behavior.rules
is set tostrict
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
- npm
- pnpm
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
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
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
The sample features will execute and a HTML evaluation report will be generated at gwen/output/reports/index.html
in your project.
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:
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
- Windows
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
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
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:
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.
- conf
- json
- properties
File: /project/gwen.conf
gwen {
target {
browser = "chrome" # chrome|firefox|safari|edge|ie
env = "test" # local|dev|test|staging|prod|..
}
}
File: /project/gwen.json
{
"gwen": {
"target": {
"browser": "chrome"
"env": "test"
}
}
}
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 declarativegwen.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.
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
The sample features will execute and a HTML evaluation report will be generated at output/reports/index.html
in your project.