Scenario

To actually express the behavior we want, each feature contains several scenarios. Each scenario is a single concrete example of how the system should behave in a particular situation. If you add together the behavior defined by all of the scenarios, that’s the expected behavior of the feature itself.

When Cucumber runs a scenario, if the system behaves as described in the scenario, then the scenario will pass; if not, it will fail. Each time you add a new scenario to your Cucumber test suite and make it pass, you’ve added some new functionality to the system, and that’s time for a high-five.

Each feature typically has somewhere between five and twenty scenarios, each describing different examples of how that feature should behave in different circumstances. We use scenarios to explore edge cases and different paths through a feature.

Scenarios all follow the same pattern:

1. Get the system into a particular state.
2. Poke it (or tickle it, or ...).
3. Examine the new state.

So, we start with a context, go on to describe an action, and then finally check that the outcome was what we expected. Each scenario tells a little story describing something that the system should be able to do.

Given, When, Then

In Gherkin, we use the keywords Given, When, and Then to identify those three different parts of the scenario:

So, we use Given to set up the context where the scenario happens, When to interact with the system somehow, and Then to check that the outcome of that interaction was what we expected.

And, But

Each of the lines in a scenario is known as a step. We can add more steps to each Given, When, or Then section of the scenario using the keywords And and But:

Cucumber doesn’t actually care which of these keywords you use; the choice is simply there to help you create the most readable scenario. If you don’t want to use And or But, you could write the previous scenario like this, and it would still work exactly the same way:

But that doesn’t read as nicely, does it?

Replacing Given/When/Then with Bullets

Some people find Given, When, Then, And, and But a little verbose. There is an additional keyword you can use to start a step: * (an asterisk). We could have written the previous scenario like this:

To Cucumber, this is exactly the same scenario. Do you find this version easier to read? Maybe. Did some of the meaning get lost? Maybe. It’s up to you and your team how you want to word things. The only thing that matters is that everybody understands what’s communicated.

Stateless

When writing scenarios, here’s a really important concept you need to grasp:

Each scenario must make sense and be able to be executed independently of any other scenario.

That means you can’t put some money into the account in one scenario and then expect that money to be there in the next scenario. Cucumber won’t stop you from doing this, but it’s extremely bad practice: you’ll end up with scenarios that fail unexpectedly and are harder to understand.

This might seem a little dogmatic, but trust us, it really helps keep your scenarios simple to work with. It avoids building up brittle dependencies between scenarios and also gives you the flexibility to run just the scenarios you need to when you’re working on a particular part of the system, without having to worry about getting the right test data set up. We explain these problems in depth in Chapter 6, ​When Cucumbers Go Bad​.

When writing a scenario, always assume that it will run against the system in a default, blank state. Tell the story from the beginning, using Given steps to set up all the state you need for that particular scenario.

Name and Description

Just like a Feature, a Scenario keyword can be followed by a name and description. Normally you’ll probably just use the name, but it’s valid Gherkin to follow the name with a multiline description—everything up until the first Given, When, or Then will be slurped up into the description of the scenario.

Stale scenario names can cause confusion. When modifying existing scenarios (or copying and pasting them), take care to check that the name still makes sense. Since the scenario name is just documentation, Cucumber won’t fail the scenario even if its name no longer has anything to do with what’s actually going on in the steps. This can be really confusing for anyone reading the scenario later.

Matt says:

Take Care with Your Naming Scenarios

Even though they can’t make your tests pass or fail, scenario names are surprisingly important to get right. Here are some reasons why it’s a good idea to pay attention to them:

• When your tests break, it’s the failing scenario’s name that will give you the headline news on what’s broken. A concise, expressive name here can save everyone a lot of time.

• Once you have a few scenarios in a feature file, you don’t want to have to read the detail of the steps unless you really need to do so. If you’re a programmer, think of it a bit like method naming. If you name the method well, you won’t need to read the code inside it to work out what it does.

• As your system evolves, your stakeholders will quite often ask you to change the expected behavior in an existing scenario. A well-composed scenario name will still make sense even if you add an extra Then step or two.

A good tip is to avoid putting anything about the outcome (the Then part) of the scenario into the name and concentrate on summarizing the context and event (Given and When) of the scenario.

Try This

• Now that you understand how to write Gherkin scenarios, try converting some of the concrete examples you wrote down earlier for your own project into Gherkin.

• Show them to someone who knows nothing about your project, and ask them what they think your application does.

• Practice describing what you’re doing with Given/When/Then while you’re doing everyday things such as starting your car, cooking breakfast, or switching channels on the TV. You’ll be surprised how well it fits.