How to write better scenarios knowing Cucumber’s anti-patterns

Many companies are listing Cucumber as a requirement for QA positions. Searching on Linkedin, we can find more than 3,000,000 opportunities around the world. It is clear that it is a consolidated framework and, therefore, we want to share our experiences to help you stay up to date with the market!

I have been working at Digital Results for 5 months as Quality Assurance Engineer. During that time, I used Cucumber a lot in my daily life. I know it’s a short period, but it was enough to understand that when learning a new technology, in addition to worrying about good practices, you also need to know what not to do.

Looking at what’s wrong when writing scenarios is a great way to learn. In this post, I’ll share our favorite Cucumber anti-patterns and suggest alternatives we use here in RD. With that, I’m sure you’ll start writing even better scenarios.

1. Use UI elements

When I started working with Cucumber, I remember using UI elements as a basis for describing any and all scenarios. If you do this too, rest assured that when you do a quick Google search, we will find many examples with this same approach.

So that we can identify errors and suggest improvements I will use some scenarios that I found in the famous search engine. Get to work!

When analyzing the scenario below, we should focus on keywords, which highlight the user interface: username textboxpassword textboxclick, and button.

The problem here is that, if in the future the system interface is changed, we will have the rework of updating the description in the feature file and later in the step file.

When changing the interface so that it does not change the system behavior the scenario description should remain the same and, if necessary, the changes should only be implemented in the step file.

Okay, but how can we rewrite this scenario? It’s simple, just write at a higher level of abstraction, removing and/or replacing the words that referenced the user interface.

2. More than one business rule in the same scenario

Another common difficulty when designing scenarios is knowing how far their scope goes. We shouldn’t have more than one business rule in the same scenario, as this would be the base criterion to separate it.

3. Scenarios with a bad name

The name of the scenarios helps, a lot, to understand the behavior of a certain part of the system. Remembering that Cucumber’s main function is the so-called live documentation, we will always need to worry about providing an expressive name for those who are reading.

4. Describe scenarios as testing

We often get used to writing scenarios step-by-step, as if we were performing a manual test on the system. However, as the knowledge in the framework evolves, we realize that the most important thing about the scenario is what it intends to validate and not how it will validate.

5. Confusion with the Given, When and Then reserved words

Although Cucumber doesn’t distinguish between the Given, When and Then reserved words, we like to use them in our scenarios for readability. However, we often find scenarios where the words were used incorrectly.

Before exemplifying this situation, it is interesting to recall the concept. The Given should be used as context and mass data, When refers to action or event and Then with regard to the result expected after the previous steps are executed.


If you’ve identified yourself with some of these mistakes, you’re on the right track! We’ve also made these mistakes and learned a lot. Building scenarios as documentation is a challenging task and I can say that the best way to evolve is to practice.

If you use Cucumber to create your acceptance tests, share your favorite anti-patterns in the comments! Ah, if you like the tool and want to take one of those amazing opportunities that I mentioned at the beginning of the text, we have a space waiting for you 🙂