To Gherkin or not to Gherkin? a findability story

Shall we make our lives easier ?

If you have a code based scenario then it will look like so:

def testLoginAndLogout(user)
  openApp()
  assertLoginScreen()
  fillCredentials(user)
  tapOnLoginButton()
  assertHomeScreenIsRendered()
  tapOnMainMenu()
  tapOnLogoutButton()
  assertLoginScreen()
        

But if you had gherkin you would write it like so:

Scenario: Verify that a user with valid credentials can Login and Logout successfull
Given that you have opened the mobile application
And that you have found yourself to Login screen
And that you have filled the Login form with username and password of a Valid user
When tapping on the Login button
Then it is expected that the user is found in the Home screen
When tapping on Main Menu
And tapping on Logout button
Then the user is found back to the Login screen        

The second one in Gherkin format means that each of the above steps must correspond to some code:

Meaning that the code will look like so:

def step("Given that you have opened the mobile application")
openApp():        

But let's say that the scenario or Gherkin step is not implemented yet... so you would have something like:

def testLoginAndLogout(user)
raise Exception('Not implemented yet'):        

and for first step of Gherkin:

def step("Given that you have opened the app")
raise Exception('Not implemented yet'):        

Now imagine that you have a huge codebase with multiple folders, multiple files and many lines in each. And also you have a new-comer who just joined the team.

This newcomer has two options: Either to implement it from scratch OR find already existing <-- He will choose whatever is actually faster

So basically the problem here becomes a kind of big-data problem, and a problem of FINDABILITY !!

Findability: The probability that you will find something easily

The new comer knows that he wants as first action something that starts the application.

So searching through the entire project for keywords like "start", "init", "launch", "begin" and has spend already sometime to find other functions that contain these keywords.

He is frustrated and decides to write his own function.

In our tiny example of course the newcomer with the four words that he tried he would have found neither using code-scenarios, nor using Gherkin-scenarios

If the QA engineer cannot find the supposingly already existing solution will write it from scratch <-- We do not want this because it is low speed and in writing scenarios we want high speed and simplicity

But the code solution always becomes somehow too short. This is ok for simple cases like:

tapOnLoginButton() <-> When tapping on the Login button

In the above using the "Login Button" or the "LoginButton" when searching the entire codebase will likely easily get you the results that you want

But now consider more complex cases like this one:

fillCredentials(user) <---> And that you have filled the Login form with username and password of a Valid user

When any engineer, new comer or not, is trying to find the function that just fills the login form how likely is he going to find it when his query needs to have the word "credentials" inside ?? The probability is low that he will spot the fillCredentials function.

But when the user will be searching for "login form" or for "username" or for "password" , then all of these queries will return the step And that you have filled the Login form with username and password of a Valid user, which is a double win:

He is searching for scenario steps where he can find more easily and also scan them visually much more easily because they are written in plain english

In addition imagine that the software developer mindset will might lead someone to split the fillCredentials to two functions fillUsername and fillPassword which created extra steps and making the scenario harder to read. Recall the scenario is about testing the login of a single user. The details that this user has a username and a password (and not any other way) are encompassed to one step as they should

Basically if you have capacity you should have QA analysts write all the Gherkin scenarios and then have QA engineers implement them in order to separate completely those who are thinking in the business way with those who are implementing the underlying code for automation

The dos and don'ts of the Gherkin way:

Do it like so:

def step("And that you have filled the Login form with username and password of a Valid user: <user>")
#imagine here that gherkin frameworks give the user a way to pass parameters to the scenario such as the user variable here
fillUsername(user.name)
fillPassword(user.pass):        

Do NOT do it like so. Write a script to scan code for having too many inputs and mark them as BAD steps that need refactoring and do not actually represent directly business logic!

def step("Given that you have param1 <param1> and param2 <param2> and param3 <param3> and param4 <param4>")
#code here ..:        

Instead do it like so:

def step("Given that you have a validated demo user who has registered from an Asian country and has funds in his account")
#code here should take the various parameters and make them a unique case as you read it:        

Do NOT do it like so:

def step("And that you have verified the email of the newly created user")
#in pseudocode
body = requests.get('https://get.latest.email.request')
token = body.findToken()
if token == None:
fail()
resp = request.post('https://verify.user', token)
assert resp.status == 200:        

Instead inside the step have some helper functions to make it a bit clearer:

def step("And that you have verified the email of the newly created user")
token = get_token_from_latest_email()
if token == None:
fail()
resp = validate_token(token)
assert resp.status == 200:        

Finally one might claim that having a number of QA engineers, each one a bit newer or older member of the team and each one from different background you might end up with the both of the two steps above, the first with pure python code and the latter more organized and the only difference is in their title:

And that you have verified the email of the newly created user and And that you verify the email of the newly created user

Then this is OK.

Why ? Because think of all the duplicated questions and answers in Stackoverflow. Yet Stackoverflow if immensely helpful! Not because it is super organized but because it has tons of information, all represented by various users who think differently (e.g. init vs launch vs start vs begin) and are expressing differently but finally anyone can find what is looking for. Namely in stackoverflow you search for "How to start a mobile app using Appium" and this will serve those users who think in English like that while others will think of "How to getting started with Appium" and this question is a duplicate but is serving users who think in English like this and thus BOTH find what they wanted easily.

The same with Gherkin, it will evolve to be a library of scenario steps where everyone can find what they are searching for easily and quickly.

For those who are thinking about maintainability again they are thinking in software engineering terms which do not apply for Automated Scenarios. Scenarios should be small easy to understand scripts that you either keep or throw away. You do not refactor scenarios, better write them from scratch. You don't want to waste the resources to do this. It does not worth it.