FAQ
What is Gwen?
Gwen = [G]iven [W]hen Th[en]
Gwen is a Gherkin interpreter with built-in automation capabilities that can readily be utilised for end-to-end testing and robotic processing. Automation is achieved through Gherkin bindings in meta specs, composed with the Gwen DSL and maintained alongside your feature files. An embedded Selenium engine executes scenarios according to the meta you provide to perform operations in browsers for you.
What are the key Gwen features?
- Fully Gherkin compliant interpreter.
- Composable StepDefs and automation details confined to meta.
- Good Gherkin practice encouraged by default.
- Consistent and reliable execution across browsers.
- NPM package for quick project setup and automatic updates.
- Parallel and dry run execution modes.
- Interactive REPL console and debugging.
- HTML, CSV, JSON and JUnit-XML reports.
- Configurable settings and launch profiles.
- Hard, soft, and sustained assertion modes.
- Multiple web element locator mechanisms including JavaScript
- JavaScript function bindings
- System process calls.
- CSV and JSON data feeds.
- String interpolation.
- Runs on Windows, Linux and Docker.
What are the system requirements
- Linux, Mac or Windows OS
- Chrome, Edge, Firefox or Safari browser
- Java 17+
- If you have more than one version of Java installed on your system, you can nominate which one to use by setting the
JAVA_HOME
environment variable.
- If you have more than one version of Java installed on your system, you can nominate which one to use by setting the
- node 18+ (for JS projects)
Why would I use Gwen over other tools?
- Quickly get started and be productive with less coding and development.
- Focus more on business process and less on automation concerns.
- Matured over many years in industry.
How mature is Gwen?
Early adopters helped us mature Gwen in industry since it was open sourced in 2014. We regularly keep the project up to date with the latest Gherkin parser, Selenium library and other dependencies released by the open source community. We strive to maintain consistency, reliability and backwards compatibility at all times to minimise impact to users. We continue to make improvements based on feedback and new ideas. Many years of effort, experience and learnings have helped shape Gwen, making it very reliable and stable.
Can I add Gwen to my JS project?
Yes, you can add Gwen to JS projects using npm and have all your executable Gherkin living next to your code and integrated into your development and testing process. See the getting started guide.
Does Gwen have a GUI interface?
No. You can do everything with the launcher and your favourite IDE or text editor.
Can I debug my executable specifications?
Breakpoints can be added to any feature or meta steps by prefixing them with the @Breakpoint
annotation. See debugging.
What are the batch and REPL modes?
Batch mode forces Gwen to immediately exit after a given feature or features have executed. You should always invoke Gwen in batch mode on server environments such as build servers.
REPL mode leaves the interpreter session open after a given feature or features have executed, allowing you to interactively enter additional steps to execute or inspect bound data in memory. You should use this mode to verify the execution of your StepDefs as you develop your meta or when you want to diagnose a failing feature.
What are the available REPL commands?
See REPL commands.
How do I run a single feature file?
Launch Gwen passing in the single feature file.
- Yarn
- npm
- pnpm
yarn gwen -b path/to/File.feature
npm run gwen -- -b path/to/File.feature
pnpm gwen -b path/to/File.feature
The -b
launch option instructs Gwen to exit immediately after executing (omitting it will open the REPL instead).
How do I run all features files in a directory?
Launch Gwen passing in the directory.
- Yarn
- npm
- pnpm
To run all feature files in the features
directory, including all feature files in all sub-directories:
yarn gwen -b features
To run all feature files in the features/todo
directory, including all feature files in all sub-directories:
yarn gwen -b features/todo
To run all feature files in the features
directory, including all feature files in all sub-directories:
npm run gwen -- -b features
To run all feature files in the features/todo
directory, including all feature files in all sub-directories:
npm run gwen -- -b features/todo
To run all feature files in the features
directory, including all feature files in all sub-directories:
pnpm gwen -b features
To run all feature files in the features/todo
directory, including all feature files in all sub-directories:
pnpm gwen -b features/todo
The -b
launch option instructs Gwen to exit immediately after executing (omitting it will open the REPL instead).
How do I run multiple features in sequence?
To run multiple feature files or directories of features in sequence:
- Yarn
- npm
- pnpm
yarn gwen -b path/to/file-or-dir-1 path/to/file-or-dir-2 path/to/file-or-dir-N
npm run gwen -- -b path/to/file-or-dir-1 path/to/file-or-dir-2 path/to/file-or-dir-N
pnpm gwen -b path/to/file-or-dir-1 path/to/file-or-dir-2 path/to/file-or-dir-N
The -b
launch option instructs Gwen to exit immediately after executing (omitting it will open the REPL instead).
How do I run multiple features in parallel?
To run multiple feature files or directories in parallel, specify the --parallel
launch option:
- Yarn
- npm
- pnpm
yarn gwen --parallel path/to/file-or-dir-1 path/to/file-or-dir-2 path/to/file-or-dir-N
npm run gwen -- --parallel path/to/file-or-dir-1 path/to/file-or-dir-2 path/to/file-or-dir-N
pnpm gwen --parallel path/to/file-or-dir-1 path/to/file-or-dir-2 path/to/file-or-dir-N
Can I set a ramp up interval for staggered parallel execution?
Yes. Configure the gwen.rampup.interval.seconds
setting. If you set this value to 5, the staggered execution will look like this:
time 00 05 10 15 seconds
│ │ │ │
core 1 │<── feature 1a ──>|<── feature 1b ──> ..
core 2 │ │<