Best practices for scenario writing

Applies to CucumberStudio Cloud, and to Enterprise ver. 3.3 - Last updated on November 17, 2023

This topic describes best practices for writing BDD scenarios in CucumberStudio.

In this topic

Testing process

Write test scenarios at early stages

Write test scenarios before you start creating test code or at the early stages of development. The scenarios help you define software behavior and understand possible problems in a better way. Once a scenario is ready and your teammates agree with it, you can start implementing the functionality. This will save time and effort and remove uncertainty later, during the development or when your team will run acceptance tests.

Don’t write in isolation, work as a team

If a business analyst or a product owner writes test scenarios on their own, they can miss input from other team members, and the resulting scenarios will not represent the common understanding of application behavior.

Also, often, it’s difficult to automate test scenarios written by non-technical team members without modification. And after modification, these scenarios might become significantly different from the original idea.

On the other hand, test scenarios written only by developers or QA engineers often have lots of unimportant details that make it difficult to understand the core test idea.

Involving different types of specialists in scenario creation will help people with different perspectives share their vision and help you create well-defined descriptions.

Don’t test several rules at a time

A good scenario should be as clear as possible and test one feature at time. Imagine the following Gherkin snippet, for example:


Given a user signed up as "userName"
And their password is "password"
And their password confirmation is "password"
And their email is "[email protected]"
And the email is unique in the system
When the user checks their profile
Then the user's account name should be "userName"

Does it check the passwords, email uniqueness, or the account name on the Profile screen? Scenarios like this one lead to uncertainty during development and testing.

An easy way to check this is to look at the number of When-Then pairs. A good scenario has only one When-Then pair (one pair matches one user procedure). Multiple Whens-Thens indicate a problem.

Another way to check if your scenario is clear enough is to show it to somebody who is not familiar with your product and see if they can explain its behavior. If the scenario is not good enough, it will cause misunderstanding during test creation and runs.

Use a reasonable number of scenarios in a feature file

A long feature file can make it difficult to understand how a feature works. Keep some reasonable number of scenarios per file, say, a dozen. Use scenario outlines to check different cases.

If you are testing some complex functionality that requires lots of tests, think of dividing it into subfeatures and create a file for each subfeature.

Remove unneeded scenarios

When you start creating your software product, you can create scenarios that test some basic functionality. A typical example is as follows –


Given the user is logged in
And their bank account is empty
When the user checks the balance
Then the balance should be zero

Most of the time, these kinds of tests are obvious and exist because you needed something to start the implementation. As the time progresses, you create more and more scenarios, and it is likely that basic functionality is covered by some other tests. So, keeping old simple scenarios will not add any significant value to helping your teammates understand how the product works. Delete these scenarios or rephrase them to something more valuable.

Scenario content

Describe the core and avoid insufficient details

Many specialists tend to write scenarios the same way they write tests ("I click this button and enter this value when I run a manual test, so why shouldn’t I add this to the scenario?"). As a result, they get scenarios with incidental details that hide the main story. A simple example of this looks as follows:


Given I sign up as "JohnSmith"
And my password is "password"
And my password confirmation is "password"
And I have deposited "$60" in my account
And I have deposited "$40" in my account
When I check my bank balance
Then my bank balance is "$100"

The purpose of the scenario is to check the bank balance, not to verify the passwords.

To avoid such scenarios, try focusing on the core idea and avoid details that don’t contribute much. For the example above, a possible correction would be as follows:


Given a user signed up as "JohnSmith"
And has deposited "$60" in their account
And has deposited "$40" in their account
When that user checks their bank balance
Then the balance should be "$100"

Avoid creating too high-level scenarios

This problem is contrary to the one described above. Too abstract scenarios make the described idea complex for understanding. Look at this Gherkin code –


Given I have an account
When I withdraw some money
Then the balance should be the original balance minus the amount withdrawn

This scenario has no example data in it. It doesn’t say what the balance was or how much a user withdraws. In some cases, details help better understand what is happening under the cover. You need to find a reasonable balance between too-detailed and too-abstract scenarios.

Don’t write procedure-driven scenarios

Don’t write a scenario the same way you create UI test script. Don’t link to button names or text box captions where possible. This often hides the core idea, and if the UI changes, your tests become misleading, and you need to update them.

Use a reasonable number of steps in a scenario

You can combine conditions with “And” in a scenario. However, using too many “And” lines can make the scenario really complex. Consider decreasing their number to some reasonable value, say, 2-3 “Ands” for one Given, When, or Then step.

Avoid “I” in step definitions

There are two approaches to writing test steps: first-person and third-person. Using the personal pronoun “I” might help you put yourself in the users’ shoes. However, most of the modern applications are multi-user, and putting “I” in a scenario can be confusing as it might be unclear what exact user you are speaking about.

We’d recommend writing steps in third person. This will remind you about the user role in the application, avoid misleading assumptions, and help you provide info in more structured way. Use narrative sentences and clearer definitions. Don’t use both first-person and third-person pronouns in one scenario.

Use meaningful scenario titles and descriptions

Scenario titles help you quickly understand the scenario essence. Titles like “Scenario1” or “YesAnotherScenario” are unclear, and it will be difficult to recall what they do even for the scenarios' authors. We’d also suggest avoiding non-specific scenario names like “Sign Up, open the Balance Screen, check balance, log off”. Consider using more descriptive names like “Check balance when it is positive”, “Check balance when an overdraft is on”, and so on.

As for descriptions, try explaining business rules in them. A description like “As a user, I want to check my balance, so that I know my balance” gives no info on the product behavior. Think of scenarios and descriptions as of living documentation, use them to talk about business rules, to provide examples and remove uncertainty.

Reuse step definitions, when possible

Scenarios can include steps that sound very similar or even the same, for instance, test scenarios for an online shop can contain a step like “Given the user is logged in …”. You benefit from reusing step definitions in the following ways:

  • This makes it easy to maintain your tests when the tested app changes.

  • This will simplify test automation.

We’d recommend reusing steps when it is possible. CucumberStudio offers the concept of action words. These are phrases that you can reuse across step definitions in various scenarios.

Use a reasonable number of scenario outlines

Using too many scenario outlines leads to many scenarios runs because adding a scenario is a matter of adding a new row to the Examples table. A large number of similar tests make the test run longer and clutter up the test results. Use a reasonable number of data sets and choose them carefully to verify various conditions.

Use Given, When, and Then clearly

Some people make no clear separation between the Given, When, and Then clauses. Test automation tools make no difference between them, too.

The only reason for these clauses to exist is to make it easier for people to write test scenarios that are logically structured. Think of Given as something that exists or was done in the past, When as something that happens in the present, and Then as something that will occur in the near future.

From the grammatical point of view, use present or present perfect tenses for Given and present tenses for When and Then.

Set up writing standards

Test scenarios are used in different phases of software development and should be clear to all the team members. Adopting some writing rules (a style guide) will help you create scenarios that are consistent and easy to understand. This is especially important when you have multiple scenario authors in a team.

You can choose rules that fit your needs better. Below are some common recommendations that work in most cases:

  • Use correct spelling and grammar.

  • Use correct punctuation. However, don’t end step definitions with periods, commas, and other punctuation marks.

  • Avoid jargon.

  • Use empty lines to separate scenarios and to separate scenarios and examples.
    Put an empty line after the feature description.
    Don’t put empty lines between test steps.

  • Capitalize Gherkin keywords (the scenario editor in CucumberStudio supports this by default).

  • Don’t capitalize words in step definitions, unless grammar rules require this.

  • Set up some rules for tag names. For instance, write tags in lower case and separate words with hyphens ( - ).


Highlight search results