Introduction

Gwen = [G]iven [W]hen Th[en]

Gwen is a Gherkin interpreter for driving automated testing and robotic processing with feature specifications.

Automation is achieved through Gherkin bindings called meta specs, composed with the Gwen DSL and maintained alongside your feature files. An embedded Selenium engine executes each step in your features according to your meta to automate operations in browsers for you.

Declare features

Declare feature specs to describe how scenarios should behave.

Feature specs are used to communicate requirements in the language of your domain. They should clear, concise and declarative. For example, the following describes how adding items to a todo list should behave.

Feature: Add todo items
 
  Scenario: Create todo list
    Given a new todo list
     When the following items are added
          | Item          |
          | Get the milk  |
          | Walk the dog  |
     Then the list will contain 2 items

Compose meta

Compose meta specs with the Gwen DSL to formulate how scenarios will execute.

Meta specs are used to describe execution and are written in Gherkin too. Step definitions and bindings are defined in meta so your features remain clean and unconcerned with automation details.

For example, the following meta describes how the scenario in the feature above can be executed to automate a test against a running todo application.

Feature: Todo Meta

  @Context
  @StepDef
  Scenario: a new todo list
    Given my todo list can be located by css ".todo-list"
     When I navigate to "${todo.page.url}"
     Then the page title should contain "TodoMVC"
      And my todo list should be hidden

  @Action
  @StepDef
  @DataTable
  @ForEach
  Scenario: the following items are added
    Given the todo field can be located by class "new-todo"
     When I enter Item in the todo field
     Then my todo list should contain Item

  @Assertion
  @StepDef
  Scenario: the list will contain <expected-count> items
    Given the displayed count can be located by css ".todo-count strong"
     Then the displayed count should be "$<expected-count>"

Declaring step definitions

Each step definition is declared as a @StepDef annotated scenario with a name that matches that of the step in the feature it binds to. Each one calls out to one or more DSL Steps (or potentially other StepDefs) in its body to perform the specified operations at run time.

The first StepDef in our meta example binds to the first step in the feature and will only execute when it is interpreted for execution by Gwen.

  Given a new todo list

  @Context
  @StepDef
  Scenario: a new todo list
    Given my todo list can be located by css ".todo-list"
     When I navigate to "${todo.page.url}"
     Then the page title should contain "TodoMVC"
      And my todo list should be hidden

Web elements selectors

The first thing the above will do is bind the selector for locating the todo list element on the web page to the name my todo list. Later steps can then reference that element using this name to interact with it and Gwen will locate it dynamically.

  Given my todo list can be located by css ".todo-list"

Navigating to a web page

The next step in this StepDef will open a new browser window and navigate to the URL in the todo.page.url property.

  When I navigate to "${todo.page.url}"

Accessing externalised properties

We could have just hard coded the https://todomvc.com/examples/react URL in the above step, but externalising it enables us to target different environments through string interpolation without changing our meta. This is useful during development when you want to execute against a locally running instance of the application or during testing when it is running on a different host or port. With this approach you can define a settings file per environment and assign the URL for that environment to the todo.page.url property in each file. Then when you want to target an environment, you pass the settings file for that environment to Gwen and the URL will be resolved accordingly.

  # test instance url
  todo.page.url = https://todomvc.com/examples/react

Checking the page title

The next step in the same StepDef checks that the page title in the browser window contains the string literal "TodoMVC" in it. If it doesn't then an assertion error will be raised, otherwise execution will resume to the next step. It is generally a good idea when navigating to a page to verify that you did indeed land on that page before proceeding to interact with it. Checking the title is one way to do it which will suffice in this case.

  Then the page title should contain "TodoMVC"

Verifying that an element is hidden from view

The last step in this StepDef verifies that the web element containing the current list of todo items is hidden from view. We expect it to not be displayed because we haven't added any items to it yet. Recall that we bound this element in the first step earlier to the name my todo list. So here we reference it by that name and if Gwen cannot see it on the page then execution will resume, otherwise an assertion error will be raised.

  And my todo list should be hidden

Processing records in data tables

The second StepDef uses the @DataTable and @ForEach annotations which work together to process each record in the data table of the second step in the feature.

  When the following items are added
       | Item          |
       | Get the milk  |
       | Walk the dog  |

  @Action
  @StepDef
  @DataTable
  @ForEach
  Scenario: the following items are added
    Given the todo field can be located by class "new-todo"
     When I enter Item in the todo field
     Then my todo list should contain Item

Gwen will call the StepDef for each record in the table and bind each field value to its declared name in the header record. The second and third steps in this StepDef will enter each Item into the todo field and check that it was added to my todo list. This is the same my todo list that we earlier confirmed was absent when we opened the page in the browser. We reuse it here to check that it now contains and displays each item. If it does not, then an assertion error will be raised.

  When I enter Item in the todo field
  Then my todo list should contain Item

Passing parameters to StepDefs

The last StepDef accepts the number of expected items from the last step in the feature into a parameter placeholder named expected-count and then uses that to assert its value against the displayed count on the page. In this example, the value 2 will passed as the parameter.

  Then the list will contain 2 items

  @Assertion
  @StepDef
  Scenario: the list will contain <expected-count> items
    Given the displayed count can be located by css ".todo-count strong"
     Then the displayed count should be "$<expected-count>"

Behavioral rules and semantics

The following annotations on StepDefs are used to associate behavior types and enforce the following rules when the gwen.behavior.rules setting is set to strict.

When binding to a step declared with And, But, or *, then the keyword in the first step in the chain of preceeding steps declared with either Given, When or Then will become the tying keyword. Should the topmost step in a chain be declared with *, then the tying keyword will be Given.

For example, the following binding will be permitted since the feature step is declared with the Then keyword and the StepDef is annotated with @Assertion.

  Then the list will contain 2 items

  @Assertion
  @StepDef
  Scenario: the list will contain <expected-count> items
    Given the displayed count can be located by css ".todo-count strong"
     Then the displayed count should be "$<expected-count>"

If we were to change the keyword in the feature step to When however, it would not only read poorly but would no longer imply @Assertion behavior and Gwen would report the violation. Similarly, if we were to change the behavior annotation on the StepDef to @Context, then that behavior would not be implied by the Then keyword declared in the feature step.

Associative meta

When the gwen.associative.meta setting is enabled, Gwen will automatically associate and bind all same named feature and meta files discovered in a directory with each other. In the following case, the meta would be considered associative.

features/todo.feature
features/todo.meta

Launch Gwen

Launch Gwen to bind your meta and execute your features to automate.

Invoke the CLI to execute

The CLI is used to launch Gwen and execute features. When launched on a directory, it will recursively discover and bind all meta and feature files in that directory and execute all the features. Any settings files passed in will be loaded and all ${prop.name} placeholder references throughout the meta and feature files will resolve during execution.

The example presented in this introduction would execute to automate a test.

yarn gwen -b -c gwen/env/test.conf gwen/features/todo.feature

npm run gwen -- -b -c gwen/env/test.conf gwen/features/todo.feature

pnpm gwen -b -c gwen/env/test.conf gwen/features/todo.feature

gwen -b -c env/test.conf features/todo.feature