Get Started
tip
See the introduction to learn more about Gwen before getting started.
Setup
Choose a setup option
- JS Project
- Standalone
- Workspace
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
- Yarn
- pnpm
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 add -D @gweninterpreter/gwen-web
yarn gwen init
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
- Yarn
- pnpm
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
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
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
A HTML evaluation report will be generated at gwen/output/reports/index.html
in your project.
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
- Windows
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
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
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
A HTML evaluation report will be generated at output/reports/index.html
in your project.
Deprecated
Gwen workspaces have been deprecated in favor of JS projects since Gwen 3.