Advice on writing better Cucumber Gherkin scenarios

Hi all,

Apologies in advance if I am asking this question in the wrong section, I must admit I am a new member so I am new to all this!

I do have a question which unfortunately I am not sure who to ask (I do not have any mentor or such, and since this concerns our team, I suppose they are leaning towards this approach)

We have an E2E automation project in our company, which is using Cypress but with Cucumber wrapped into it.
However I feel we are not following the best practice of Cucumber scenarios

According to the official Cucumber documentation - Writing better Gherkin - Cucumber Documentation
A good practice is doing something such as this

When "Bob" logs in

Whereas a not so good one is something like this

 Given I visit "/login"
  When I enter "Bob" in the "user name" field
    And I enter "tester" in the "password" field
    And I press the "login" button
  Then I should see the "welcome" page

My dilemma is, we are doing the not so good way. This is a simple scenario, in our case its even worse because literally every button click and every assertion is a “step”, so its very common to see 1 scenario to consist of about 20-30 steps.

My problem with this is a couple of things

  • Maintainability/readability - I’ve always thought this is the biggest benefit of Cucumber Gherkin scenarios. But with the way we do things, While its quite easy to reproduce the steps, its very hard to imagine or understand what this scenario is trying to do (imagine 20 steps of click this, click that, see this, see that)
  • The way we do things right now “works”, in a sense that tests are running fine, however I feel like we are adding another layer of complication by wrapping Cypress with Cucumber scenarios. In my opinion, what we are doing can easily be achieved using Cypress if we do things in such way, hence we don’t really need to wrap it with Cucumber (since we are not doing it the proper way anyway).
  • There are some other complications, which is why I personally prefer taking out Cucumber and using Cypress by itself

I suppose I’m in need of an advice as to how to approach this, because my tech lead seems to be adamant that this is the way, but it seems to be quite against what the documentation suggests, or is this actually a common/acceptable practice?

Whenever I bring this up, the answer is always, less repetition.
By doing the below, we can literally have these 2 step definition and keep reusing them. I’m not sure how to respond to that, that’s true… but…

When I click this {button}
Then I see this {text}

In any case, any advice is greatly appreciated!
Thank you in advance!

1 Like

Hi Tony,

welcome to the club!

My short reply is: Don’t.

There is also a rather longer version:

First there is the issue of whether this is acceptance criteria, as when actually practicing BDD, or just an automated check that is written in Gherkin. In the latter case, using Gherkin makes life harder rather than easier (and it has none of the advantages that BDD offers). You can use anything else that is based on ‘keywords.’

And if the tech lead needs convincing: Automated checks are code, even if they are in more or less natural language. If it were written in Java or whatever language, would the coding principles not call for managing this differently for the sake of readability and maintenance (as you already pointed out)?

The other case, proper BDD, would lead to scenarios that describe WHAT you expect, not how you perform a check. A scenario that describes that, if you do X in situation Y, the result is Z, that kind of thing can be considered acceptance criteria. To get there very early in the process, you would want to involve the 3 or 4 amigos before a sprint starts. You will enjoy various benefits throughout the sprint and in later ones. To refactor existing scenarios to something resembling acceptance criteria afterwards, ask the question ‘why?’ as many times as is needed to get to scenarios that just describe the what (considerably shorter, much easier to understand, less sensitive to maintenance and easier to maintain). And this takes much more time, first spelling out the details of the detailed scenario and then removing them …)

So far my contribution. Looking forward to comments from others on this.


Hi there,

I would recommend reading the BDD Formulation Book it will give you some best practices on this.

1 Like