Given When Then
Clone this wiki locally
Cucumber scenarios consist of steps, also known as Givens, Whens and Thens.
Cucumber doesn’t technically distinguish between these three kind of steps. However, we strongly recommend that you do! These words have been carefully selected for their purpose, and you should know what the purpose is to get into the BDD mindset.
Robert C. Martin has written a great post about BDD’s Given-When-Then concept where he thinks of them as a finite state machine.
The purpose of givens is to put the system in a known state before the user (or external system) starts interacting with the system (in the When steps). Avoid talking about user interaction in givens. If you were creating use cases, givens would be your preconditions.
- Create records (model instances) / set up the database state.
- It’s ok to call into the layer “inside” the UI layer here (in Rails: talk to the models).
- Log in a user (An exception to the no-interaction recommendation. Things that “happened earlier” are ok).
And for all the Rails users out there – we recommend using a Given with a multiline table argument to set up records instead of fixtures. This way you can read the scenario and make sense out of it without having to look elsewhere (at the fixtures).
The purpose of When steps is to describe the key action the user performs (or, using Robert C. Martin’s metaphor, the state transition).
- Interact with a web page (Webrat/Watir/Selenium interaction etc should mostly go into When steps).
- Interact with some other user interface element.
- Developing a library? Kicking off some kind of action that has an observable effect somewhere else.
The purpose of Then steps is to observe outcomes. The observations should be related to the business value/benefit in your feature description. The observations should also be on some kind of output – that is something that comes out of the system (report, user interface, message) and not something that is deeply buried inside it (that has no business value).
- Verify that something related to the Given+When is (or is not) in the output
- Check that some external system has received the expected message (was an email with specific content sent?)
While it might be tempting to implement Then steps to just look in the database – resist the temptation. You should only verify outcome that is observable for the user (or external system) and databases usually are not.
If you have several givens, whens or thens you can write
Scenario: Multiple Givens Given one thing Given another thing Given yet another thing When I open my eyes Then I see something Then I don't see something else
Or you can make it read more fluently by writing
Scenario: Multiple Givens Given one thing And another thing And yet another thing When I open my eyes Then I see something But I don't see something else
To Cucumber steps beginning with And or But are exactly the same kind of steps as all the others.