Background

A background section in a feature file allows you to specify a set of steps that are common to every scenario in the file. Instead of having to repeat those steps over and over for each scenario, you move them up into a Background element. There are a couple of advantages to doing this:

• If you ever need to change those steps, you have to change them in only one place.

• The importance of those steps fades into the background so that when you’re reading each individual scenario, you can focus on what is unique and important about that scenario.

To show you what we mean, let’s take an existing scenario that uses only the basic Gherkin Scenario element and improve its readability by refactoring it to use a Background. Here’s our feature before the refactoring starts:

You can see that there are two scenarios here, but without reading them carefully, it’s quite hard to see what exactly is going on in each one. The first three steps in each scenario, while necessary to clarify the context of the scenario, are completely repeated in both scenarios. That repetition is distracting, making it harder to see the essence of what each scenario is testing.

Let’s factor out the three repeated steps into a Background, like this:

Our refactoring hasn’t changed the behavior of the tests at all: at runtime, the steps in the background are executed at the beginning of each scenario, just as they were before. What we have done is made each individual scenario much easier to read.

You can have a single Background element per feature file, and it must appear before any of the Scenario or Scenario Outline elements. Just like all the other Gherkin elements, you can give it a name, and you have space to put a multiline description before the first step. For example:

Using a Background element isn’t always necessary, but it’s often useful to improve the readability of your features by removing repetitive steps from individual scenarios. Here are some tips for using it well:

• Don’t use Background to set up complicated state unless that state is something the reader actually needs to know. For example, we didn’t mention the actual digits of the system-generated PIN in the previous example, because that detail wasn’t relevant to any of the scenarios.

• Keep your Background section short. After all, you’re expecting the user to actually remember this stuff when reading your scenarios. If the background is more than four lines long, can you find a way to express that action in just one or two steps?

• Make your Background section vivid. Use colorful names and try to tell a story, because your reader can keep track of stories much better than they can keep track of dull names like User A, User B, Site 1, and so on. If it’s worth mentioning at all, make it really stand out.

• Keep your scenarios short, and don’t have too many. If the Background is more than three or four steps long, think about using higher-level steps or splitting the feature file in two. You can use a background as a good indicator of when a feature is getting too long: if the new scenarios you want to add don’t fit with the existing background, consider splitting the feature.

• Avoid putting technical details such as clearing queues, starting backend services, or opening browsers in a background. Most of these things will be assumed by the reader, and there are ways to push those actions down into your support code that we’ll explain later in the book, such as in ​Tagged Hooks​.

Backgrounds are useful for taking Given (and sometimes When) steps that are repeated in each scenario and moving them to a single place. This helps keep your scenarios clear and concise.