Best practices for scenario writing

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.

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.

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

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.

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.

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

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.

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:

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:

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

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 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.

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.

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.

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.

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.

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.

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.

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 ( - ).

https://cucumber.io/blog/bdd/cucumber-antipatterns-part-one/

https://cucumber.io/blog/bdd/cucumber-anti-patterns-part-two/