Skip to main content

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?​

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.
  • 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.
  • Get support from the project maintainers by sponsoring.

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 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.

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

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 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 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  │    │<── feature 2a ──>|<── feature 2b ──> ..
core 3  │    │    │<── feature 3a ──>|<── feature 3b ──> ..
core 4  │    │    │    │<── feature 4a ──>|<── feature 4b ──> ..

Can I run scenarios in parallel?​

Yes, see: parallel scenario execution

How do I compose step definitions?​

By declaring a Scenario and annotating it with the @StepDef tag. See StepDefs and Meta.

Can I validate my features?​

Yes, see dry run execution mode.

Can I ignore (skip over) features and scenarios at execution time?​

Yes, you can either:

  • Annotate them with the @Ignore tag
  • Or annotate them with your your own tag like @MyTag and launch Gwen with the -t ~@MyTag or --tags ~@MyTag launch option to exclude them from execution

Can I execute certain tagged features and scenarios and exclude all others?​

Yes, to execute only those tagged with @MyTag, launch Gwen with the -t @MyTag or --tags @MyTag launch option to include only those and exclude all others.

How do I generate evaluation reports?​

HTML evaluation reports are generated by default. You can specify -r|--report options when launching Gwen to generate other types of reports or change the report output directory.

Can I generate CSV reports?​

Yes, see CSV reports.

Can I generate JUnit-XML reports?​

Yes, see JUnit-XML reports.

Can I generate JSON reports?​

Yes, see JSON reports.

Can I generate more than one type of report?​

Yes, To generate JUnit, CSV, and HTML reports:

yarn gwen -b -r reports -f "junit,results,html"

or

yarn gwen --batch --report reports --format "junit,results,html"
  • JUnit reports will be written to reports/junit/TEST-*.xml
  • CSV reports will be written to reports/results/*.csv
  • HTML reports will be written to the reports/html directory with an index page at reports/index.html

How can I feed CSV data to my features?​

See CSV data feeds.

How can I feed JSON data to my features?​

See JSON data feeds.

Can I configure runtime settings?​

Yes, see Gwen settings.

Is string interpolation supported?​

Yes, see string interpolation.

How do I configure logging?​

Gwen uses logback to perform all logging using the configuration shown below. This default configuration is defined in a log4back.xml file bundled in the Gwen binary. To override this and specify your own configuration, add a logback.configurationFile=file:/path-to-logback-config-file entry to your settings file in your user home directory. Be sure to use forward slashes instead of backslashes.

<configuration>
  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%-5level - %msg%n</pattern>
    </encoder>
  </appender>

  <root level="error">
    <appender-ref ref="STDOUT" />
  </root>
</configuration>

Can I access and work with database data?​

Yes, see:

Are scenario outlines supported?​

Yes, see Gwen Gets Scenario Outlines

Are data tables supported?​

Yes, see Data Tables.

Can I use Doc Strings?​

Yes, see Doc Strings.

Can I pass parameters to StepDefs?​

Yes, see StepDefs with parameters.

Can I compare or match content using templates?​

Yes, see Template Matching.

Are soft assertions supported?​

Yes, hard, soft and sustained assertions are supported. See Assertion Modes.

Can Gwen help me to write good Gherkin?​

The gwen.behavior.rules setting, when set to strict, can help you to write Strictly Good Gherkin

How do I target a specific web browser?​

Gwen is configured to target the chrome browser by default. To change this, amend the gwen.target.browser setting to your preferred value.

File: /project/gwen.conf

gwen {
  target {
    browser = "chrome"
  }
}

Can I locate elements in frames or other elements?​

Yes, see Locator Chaining.

Can I drive multiple browsers from a single feature?​

Yes, you can allocate names to browser sessions and switch between them. See Named Browser Sessions.

Can I run Gwen on docker​

Yes, you can run Gwen on docker using Selenoid

Can I run Gwen on BrowserStack or LambdaTest​

Yes, see

Can I run Gwen on Jenkins?​

Yes, see Running Gwen on Jenkins.

Can I run a headless browser?​

Yes, set gwen.web.browser.headless to true.

Can I emulate mobile devices in browser?​

Yes, see mobile emulation.

How do I upload files to a file input field?​

Define a locator for the file input field and set the path to the file you want upload. Note that you can only use absolute paths. If you wish, you can use system properties or a custom Gwen setting to reference the location of the file.

Given the file input field can be located by xpath "//input[@type='file']"
 
 # using a hard coded path
 When I type "absolute/path/to/file.ex" in the file input field

 # or using the system user directory path
 When I type "${user.dir}/file.ext" in the file input field

 # or using a path defined in a custom setting
 When I type "${custom.dir}/file.ext" in the file input field

Can I get support?​

Support is offered through sponsorships. By purchasing support you will be sponsoring our open source work on this project.