Skip to content
wannacode

Given, When, Then

In short: A Gherkin scenario is an example written in three steps: Given (where we start), When (what happens), Then (what you see). "And" and "But" continue the step before them. A good scenario passes on the correct system and fails on the system with a bug, so here every scenario runs against both.

Problem

One example, three readings

At the delivery session there is a green card: "A cart of 50.00 €: delivery is free". Everyone nods.

Then everyone writes it down their own way. The owner keeps it in an email. QA writes a test in a spreadsheet. The developer adds a check in the code. A month later someone changes the rule, and only one of the three places gets fixed.

We need one record for everyone: the owner reads it as a sentence, and the computer runs it as a test.

The idea

A scenario in three steps

The example is written down as a scenario in three steps:

  • Given: where we start. What is there before anything happens;
  • When: what happens. The action the scenario is about;
  • Then: what you see. The result that gets checked.
Feature: Free delivery


  Scenario: An order of exactly 50 €
    Given a cart of 50.00 €
    When I place the order
    Then delivery is free

The language is called Gherkin. The words at the start of each line are its keywords. Feature is the title of the file: the thing we describe. The scenarios go under it, each with its own name.

The rest is plain text. That is why a scenario reads like a sentence: "Given a cart of 50 €, when I place the order, then delivery is free."

Try it

Which step?

1. "… a cart of 49.99 €"
2. "… I place the order"
3. "… delivery is 4.90 €"
4. "… the customer is a loyal customer"

The idea

"And" and "But"

Sometimes the start has two parts, or there are two checks. Then the next step starts with And or But:

Feature: Free delivery


  Scenario: An order just under the boundary
    Given a cart of 49.99 €
    When I place the order
    Then the order is accepted
    But delivery is 4.90 €

"And" and "But" are not a new kind of step. They take the kind of the step before them: here "But" is one more check. The difference between the two is only for the reader. "But" says "and still": the order is accepted, but delivery is paid.

The idea

How a scenario is checked here

In the tasks you write scenarios in an editor. Next to it is the step vocabulary: the sentences the system understands, such as Given a cart of {amount} €. In place of {amount} you write a number, for example 49.99. A step outside the vocabulary cannot run, and the check tells you the closest one.

Then the scenarios run twice:

  1. Against the correct system. Every scenario must pass here. If one fails, its expectation is wrong: check it against the rule.
  2. Against versions with one bug each. Each is the same shop with one real defect: > instead of >= at 50 €, the wrong fee, an empty cart that gets charged. Such a version is called a mutant. A good scenario fails on it, that is, it catches it.

The answer sounds like this: "The scenarios pass on the correct system and catch 2 of 3 bugs. A bug slips through: with an empty cart." It does not say which scenario is missing. It says where to look.

Exercise

The first scenarios

1. Exactly 50 €. The scenario name is already there.

Finish the scenario for an order of exactly 50.00 €: Given, When, Then.

GherkinFree delivery

2. Three cases. The scenario for 50 € is already there.

Add a scenario just under the boundary (with "But" or "And") and a scenario for an empty cart. The three scenarios must catch all three bugs.

GherkinFree delivery

The idea

A scenario is an example

Look at what you wrote. Each scenario is one green card from Example Mapping, only written so that it can run. Together the scenarios are the acceptance criteria of the story.

That is why a good scenario has concrete numbers. "Given a big order" cannot run, and everyone reads it differently. "Given a cart of 50.00 €" reads only one way.

More precisely, if you are curious

ISTQB CTFL v4.0.1, section 2.1.3 ("Testing as a Driver for Software Development"), describes BDD (behavior-driven development) as an approach where the desired behaviour is expressed with test cases in a simple form of natural language that stakeholders understand, usually in the Given/When/Then format. Section 4.5.2 calls this the scenario-oriented format of acceptance criteria, next to the rule-oriented format (a checklist or an input-output table).

The keywords. The Gherkin Reference in the Cucumber documentation lists the main keywords and their translations into more than 70 languages. A first line such as # language: fr tells Cucumber which language the file uses; without it, English is assumed. "Scenario" and Example are the same keyword. Instead of a step keyword you can also write *.

Two languages. On the Bulgarian page of this course the scenarios use the Bulgarian keywords (# language: bg), because the goal is for the business to read them and the client there writes in Bulgarian. In an international team scenarios are written in English, so that everyone can read them.

Mutants come from mutation testing: a small bug is planted in a program on purpose to see whether the tests catch it. Here the mutants are ready-made and describe the behaviour of the shop, not code.

Test

Check yourself

1. What does the "Then" step say?
2. What does "And" mean after "Then"?
3. The scenario for 49.99 € passes on the correct system. Does that make it good?
4. What is the first line of the file, with the scenarios under it?

Made by Ivo Gergov as part of Evo Tech's campaign for accessible programming education ·