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 🙌