Specification by Example

Given/When/Then with Style?

Gojko Adzic has started a series of challenges on the Specflow blog where readers can submit solutions to common problems writing automated tests using gherkin (Given/When/Then).

The first challenge is:

“What’s the best way to describe a Given for a value that’s not supposed to be there? For example, starting the specification from a point of a user who does not yet exist in a database, or a product that’s not been set up. “Given a user that doesn’t exist” sounds vague, but “Given user John that does not exist” sounds silly – how can we talk about John if he doesn’t exist yet?”

Gojko Adzic
Given user John does not exist
When John tries to register
Then the registration is successful

Given user John exists
When John tries to register
Then the registration fails

How would you improve the scenario of our example to solve the challenge of this week?

Gojko Adzic

Interestingly this problem highlights the issues I found using Gherkin to specify business rules and examples I previously wrote about:

“I’m not keen on writing specifications in gherkin (Given/When/Then) as I think it’s too generic and frequently makes the feature specifications too verbose – and takes emphasis away from the critical parts.”

Example of lightweight feature documentation

I prefer bullet points and tables.

I’d specify the above scenarios as follows.

User Registration


  1. A user can only register a single account per unique email address
  2. A user’s email address is their username
  3. A user can register using their Google or Facebook account without having to enter a username or password
  4. A user must enter a password unless they are registering using Google or Facebook
  5. Passwords must contain at least 4 letters and 4 digits
  6. Passwords are maximum length of 10 and can contain any ASCII characters

Registration Scenarios/Examples

ScenarioExample Email AddressResult
New user signs up with a new email✅ Registration Successful
New user signs up with a new email and invalid password❌ Registration Unsuccessful – Validation Error Displayed and no account created
User attempts to sign up with email already registered email for account with password❌ Registration Unsuccessful – Reset password page displayed with email prefilled
User attempts to sign up with email already registered email for account with Google❌ Registration Unsuccessful – Log in with Google page displayed

It’s tempting to put passwords into the above table, which is what I originally did, but I’ve found it’s better to specify those separately (in the same document).

Passwords Scenarios/Examples

Password ScenarioExample PasswordValid/Invalid
Less than 8 characters123
Less than 4 digitsaaaabbbb
Less than 4 letters123456aa
No emoji – ASCII Chars Only1234abcd💀
More than 10 characters123456abcdef
10 Characters with ASCII1234abcd%$
4 digits and 4 lettersabcd1234
Special characters don’t count as lettersabc$1234


Whilst these scenarios aren’t gherkin I don’t think they need to be. They could be taken by developers and written as unit tests alongside the code. I wouldn’t have an e2e automated test that tests this logic at this level – it’s complex and an expensive waste of time.

I’ll be interested to see the follow up posts about the best way to specify these in gherkin, as I can’t see a clearer way than just using bullet points and tables 🙌

4 replies on “Given/When/Then with Style?”

Hi Alister,
BDD and Gherkin can also contain a table. The table contains the examples for the rules. It could replace the rules description, but I guess you could also use a comment to add text (if you are using a code editor).
I tried to transform some of your examples into Gherkin format (with style matching the Behave framework for Python). This is how it turned out (not sure how the table will fit this comment box though):

Scenario Outline: User registration
User email has to be unique.
User can register without a password using their Google or Facebook account.
Password legth is 8-10 characters with at least 4 letters and 4 digits.

Given user fills in and in the registration form
When user submits the registration form
Then result is
And appears on the screen

| email | password | result | message |
| | 1234abcd%$ | reset_pwd_page | User already exists, reset password |
| | 1234abcd%$ | google_login_page | User already exists, login with Google |
| | 1234abcd%$ | success_page | Successfully registered |
| | abcd1234 | success_page | Successfully registered |
| | 123 | validation_error | Password doesn’t comply with the rules |
| | aaaabbbb | validation_error | Password doesn’t comply with the rules |

Thanks, I understand that you can include tables in gherkin however I have found trying to coerce it into that format hasn’t been helpful to us. Thanks for your comment.

Hi Alister,

Your table format is very nice. I have two things I want to share in case not known by you or a reader of this comment. I also have a question.

This is what I wanted to reference in case useful:
– The support of the word Rule as per gherkin version 6
– The option of using a star (asterisk) instead of given/when/then so our scenarios read more like a bullet list.

My question is: With a gherkin file you have something readable that works as documentation that can produce a report from your CI for interested parties to read and more importantly it glues the specification with the automation. In case someone is tempted to change the automation without also updating the specification/documentation.

In your example, you mentioned that you automate the scenario with unit tests but that means that the specification you wrote can get outdated or it gets discarded once the automation started. Are you still gluing your specification layer with the automation layer with some other tool?

One nice aspect of having gherkin files is that when used in combination with the screenplay pattern (
… It creates a nice abstraction of the “world” your test is running against and the same specification can be automated against different subcutaneous levels of your application. Wondering too if you are having the same benefits and what you use to accomplish the same? 🙂

Thank you!

Hi Alister,

I have a question … how to combine sample map meetings, tables and designs at the same time?

for example, when it comes to forms? Currently, we get used to having a design and from there writing too much flat information. However, I don’t know how to play with those tools to see tables and rules and maps instead of paragraphs and information distributed in a great word document.
and above all, that the developers read it hahaha

Leave a Reply

Your email address will not be published.