Automating Declarative Gherkin with Gwen

Writing Gherkin feature specifications with automation in mind? Something like the following perhaps?

Feature: Google search

Scenario: Simple Google search
Given I start a new browser
 When I navigate to ""
 Then the page title should be "Google"
And the search field can be located by name "q"
When I enter "gwen automation" in the search field
Then the page title should contain "gwen"
And the first result can be located by css selector ".r > a"
When I click the first result
Then the current URL should match regex ".+[G|g]wen.*"


The above is what we call an imperative specification. It describes a sequence of steps and checks that a tester (for example) might perform in a robotic fashion when evaluating the Google search page. Gherkin like this is clearly written with implementation and testing in mind.

If you were in a team tasked to develop the Google search page, would you write Gherkin like the above upfront to describe how the search should behave or would you write it like the below instead?

 Feature: Google search

Scenario: Simple Google search
    Given I have Google in my browser
     When I do a search for "Gwen automation"
     Then I should find a Gwen page

This second example is more declarative, unlike the first. It describes the intended behaviour without specifying any implementation or testing detail. Specifications like this can be used to capture requirements, drive development and testing too (what I like to call: first class specifications). Everyone, regardless of their role in a development team can understand this easily.

Now let’s say the team want’s to adopt a test-first practice and have decided to get started with Gwen. They could then save the above feature (the 2nd one) to a GoogleSearch.feature file in the features folder, and then launch Gwen in the parent directory to evaluate it as follows:


./gwen -b features/GoogleSearch.feature

Windows DOS:

gwen -b features/GoogleSearch.feature

Of course, the test would fail because nothing has been implemented yet and Gwen also doesn’t know how to interpret the first step:

ERROR - Failed step [at line 4]: Given I have Google in my browser: Unsupported or undefined step: Given I have Google in my browser
You can publish your workspace to a git repository and share it with your team.

Now let’s say the developers have implemented the search functionality and now want to automate a test.

Now it’s time to provide Gwen with step definitions for each step in the feature. This is done in Gwen with meta features and predefined Gwen DSL steps. So your declarative feature will remain intact and unchanged. Create a Google.meta file in the features directory (alongside the GoogleSearch.feature file you created earlier) with the following content:

Feature: Google meta (automation glue)

Scenario: I have Google in my browser
Given I start a new browser
When I navigate to ""
Then the page title should be "Google"

Scenario: I do a search for "<query>"
Given the search field can be located by name "q"
When I enter "$<query>" in the search field
Then the page title should contain "$<query>"

Scenario: I should find a Gwen page
Given the first result can be located by css selector ".r > a"
When I click the first result
Then the current URL should match regex ".+[G|g]wen.*"

This is how step definitions are defined in Gwen (in Gherkin too). Notice that each Scenario has a @StepDef annotation. This tells Gwen to load these scenarios into memory and only execute them when a step in the feature with the same name is processed. The steps in each StepDef scenario are predefined DSL steps that Gwen already knows how to execute so you don’t have to write any Selenium code.

So now all the imperative steps used to drive automation that we had in our first imperative feature are all confined to a separate meta file instead. Gwen will auto-discover this meta file since we have put it in the same directory as the feature. It will bind the all the imperative steps in the meta to the declarative steps in our feature without us having to modify the feature whatsoever!

With this meta in place, let’s run Gwen again as before to evaluate the feature:


./gwen -b features/GoogleSearch.feature

Windows DOS:

gwen -b features/GoogleSearch.feature

This time, the Google search page will load, a search will be performed, the first result will be clicked and a Gwen page will be displayed. The lucky Google search behaviour is now verified.

See it in action

The evaluation reports will be available at target/reports/index.html under your workpsace location.

Clicking each step in the report will reveal the underlying step definition.

Development teams can use Gwen like this to evaluate implemented features against declarative Gherkin specifications without changing or polluting them with imperative steps or automation clutter. All of that is confined to Gwen meta.

For those who like this approach, we have introduced a new declarative feature mode in Gwen which enforces this practice. There’s been a lot of talk in the Gherkin/Cucumber community about how feature files should describe intended behaviour only and be automation agnostic. Introducing this mode is the first step we have taken to help you to write cleaner and better Gherkin without sacrificing executability.

Published by

Branko Juric

Imperative by day and functional by night. Co author of the Gwen automation platform.

One thought on “Automating Declarative Gherkin with Gwen”

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s