CONVERTING MANUAL TEST CASES TO GHERKIN

Converting Test Cases to Gherkin is an exercise in analysis. While we want to be as specific as possible when authoring test cases, there’s a level of ambiguity that is not only desired but required in Gherkin. We don’t want to tell the developer or automation engineer HOW to write the case, only give them the parameters that are required then let them determine the best way to approach it.

Below are a few examples of test cases and the process used to convert them to Gherkin syntax. (WIP)

---

---

EXAMPLE TEST CASE #1 – CREATE ACCOUNT

TEST CASE

TITLE
Create Company account

PRECONDITIONS

• Test cases should be performed using a laptop provided. Chrome browser.
• Reference video: somerandomurl.com
• Reference planning doc: somerandomdoc.com

STEPS

1. Log in to thewebsite.url with Company username and password with valid credentials.
2. First check if the user already exists by searching by first name in the "Filter by name" section.
3. If the user does not exist, click on "New User" in the bottom left of the page.
4. Under "Project" section of the Company user creation page, select the appropriate module access
5. Under "Roles" section select the appropriate role.
6. Click the "Create User" button.

EXPECTED RESULTS

• You should be taken to the Company user management page
• User's name will appear if user has successfully logged in before.
• Fill in the New User information.
  • Note: To edit an existing Company account: Return to url. Search the name of the user. Click on Action > Edit and change what is necessary.
• Checking box should work as expected.
• On successful creation of Company user, a confirmation should appear.

---

GHERKIN CONVERSION STEP 1 – TEST CASE ANALYSIS

Because test cases can be presented in a myriad of ways, we need to take a look and verify what is actually going on in it. Simple cases that just provide a feature to be tested, steps to test it, and the expected result of the test, are easy to convert as it follows the Golden Rule of BDD: One scenario, One behavior. But what about more complex test cases?

This is where some note-taking or quick jotting down might be useful. Are there multiple tests? Multiple expected results? What is the overall goal of the test? Read through the entire test case a couple of times and be aware if you’re in a situation where one feature has multiple scenarios or not.

For example, if the test case testing a field that has a pass and a fail expected result, that’s two unique scenarios.

Execution

There’s a number of preconditions, and the expected result has additional test steps. But it’s all looking for the same thing: verifying that you get a confirmation message when using the create a new user interface (or after editing an existing user).

If you look at the expected results, even though it mentions editing a user, it doesn’t give an expected result for that situation. Only for successful creation of a new user. This would be a clarification point to discuss with the team. For our purposes, we are going to work on the assumption that because it was mentioned in the expected results, editing a user should also get a confirmation. This gives us two distinct scenarios as they have slightly different preconditions. But they are under the same feature with the similar expected result.

This test case isn’t testing the fields, it’s testing the utility for a confirm, so we aren’t going to make assumptions and generate multiple scenarios or complicated Gherkin syntax for those fields.

GHERKIN CONVERSION STEP 2 – FEATURE

First, we need to define our Feature for Gherkin; what aspect or module of the software that under test. Are we testing login, video playback, a search function? A Feature doesn’t affect the actual glue code that gets written but allows for organization.

You can break it down into 2 sections: Title and Description. The Feature Description is optional but often times can add clarity or context. If there is a user story for the feature, it’s best practice to put it here.

The Feature Title should be a simple statement or phrase denoting a product or feature under test.

Examples

• Login
• Withdraw Money
• Video Playback
• Simple Search

We may want to add a Feature Description, providing additional context and clarity. A common template is similar to a user story in Scrum: As a [role] I want [feature], so that [benefit].

Example
As a user, I want to search the catalog, so that I can find specific products.

Execution

We reference the title of the test case for the Feature Title and initially can say it’s “account creation”. But looking at the steps, we see the test is to add a new user to a project account of some kind (or edit an existing one) and verify we get a confirm on the User Management page. We don’t know details and that’s fine as we know enough to refine our Feature Title to “User Management”.

We don’t need a Feature Description here, but as an exercise, we’ll use the above template and define [role], [feature], and [benefit]. Another consideration is that we have two scenarios, so our description needs to be ambiguous enough to accommodate.

Sometimes you are told the [role] (oftentimes things like user or new user) and sometimes you have to figure it out. For this case, there’s some indication this may be someone in a leadership/HR position (due to editing users with a company account), but we can’t be certain if it’s a manager, team leader, scrum master, et cetera. We’ll use the generic “user” for now; if you’re uncertain, seek clarification from a team member.

For the [feature], we can repurpose the Feature Title: “I want to access the User Management page”.

The [benefit] most likely won’t be apparent. Take the search example above; a test case for searching won’t tell you why the user wants to search, only that we are testing it. Same thing with our example test case. Our clue is nestled in the expected results: getting the confirmation about changes made. We can intuit from here that the [benefit] is to be able to “manage new and existing users.”

Put together we would get this:

Feature: User Management
    As a user, I want to access the User Management page, so that I can manage new and existing users.

The description seems a little, redundant, so we’ll leave it out here and just keep the feature title. Again, if you have a user story for the feature under test, then make sure to put it as the description.

GHERKIN CONVERSION STEP 3 – BACKGROUND AND RULE

Backgrounds and Rules are not always used. A Background is more or less like setting your preconditions. If every one of your scenarios in a feature has the same steps listed, you can move the duplicated steps to the Background. The Background section follows the nomenclature of Scenarios, utilizing “given” and “and” statements to list steps taken.

The Background keyword can be difficult to plan ahead for, so if you don’t see it clearly right now, just take a look at your scenarios once you’re done and see if there’s a clear set of steps you’re duplicating throughout them all.

Example

Background:
   Given the user is logged in
   And the user has the correct permissions

Rule is an optional keyword that represents one business rule that should be implemented. It’s to provide additional information for a feature and can group multiple scenarios under it.

Example

Rule: Users are notified about passwords due to expire tomorrow on first use today

Execution

There are a few preconditions that we can put into the background and we can basically copy/paste them here then do a touch of formatting to the Gherkin syntax. Make sure to check the steps of a test case, as things like logging in with a specific account can be Background. As both our Scenarios require the same login, we can safely include that in this section.

Background:
   Given a user is logged into the Company website
   And the user has valid credentials
   And the browser is Chrome
   And the web browser is at the User Management page

We don’t have a business rule to apply here, so we do not need the Rule keyword.

GHERKIN CONVERSION STEP 4 – SCENARIO or SCENARIO OUTLINES

This is where we write out the actual steps. Each Scenario is a singular collection of Given – Then – When steps. They are prefaced with a Scenario title, giving context to the following steps.

There are many considerations for how to enter information here, and I recommend reading an article or two on proper Gherkin syntax (This is a good one) but there are a couple of points to keep in mind:

• Make sure to always stick to One Behavior, One Scenario.
• Keep syntax simple, but grammatically correct.
  • You don’t need to chop words off, proper sentences, please.
• Try to use variables when you can and format it as a Scenario Outline that then provide Examples (check the above link for some tips on how to properly implement this).

Note: Due to limitations on code blocks, please be aware that typically in this situation you would use Scenario Outline, not Scenario

Example

Scenario: Simple web search
   Given a web browser is on the <search engine> page
   When the search phrase <variable> is entered
   Then results for <variable> are shown

   Examples: Random Topics
       |  variable  |  search engine  |
       |  plants    |  chrome         |
       |  animals   |  safari         |

Execution

This is where some additional planning and focus are required. We have to be cognizant of what is being tested vs what is not. As noted in the Analysis section, we are not testing any of the text fields. But it’s also not testing the create new user window pops up or that any of the buttons pressed work. Nor the search function for users.

We are testing that when we create a new account or edit an existing account, we have a confirmation message appear. There are two Scenarios, so we will have two sets of Given-Then-When statements with each one having its own Scenario title.

The titles are easy enough, we are “Creating a new user” and “Editing an existing user” are our two different scenarios and they clearly indicate what our steps are going to refer to in context of the feature.

This is where declarative vs imperative becomes important. We only want to give 3-5 statements that indicate the parameters of the test, not dictate instructions. We do have two variables here: the usernames we wish to create or edit. This means we should declare the variable in a Scenario Outline with Examples. Also remember, we had a Background, so no need to repeat those steps here.

Note: Due to limitations on code blocks, please be aware that typically in this situation you would use Scenario Outline, not Scenario

Scenario: Creating a new user
   Given that <name> does not exist in the User directory
   When the user creates a new account for <name>
   Then a confirmation message indicates success for the account creation

   Examples: New Users
       |  Name     |
       |  David    |
       |  Candice  |

Scenario: Editing an existing user
   Given that <name2> exists in the User directory
   When the user edits account information for <name2>
   Then a confirmation message indicates success for the changes made

   Examples:  Existing Users
       |  Name2   |
       |  Tracy   |
       |  Austin  |

FINAL RESULT

Feature: User Management

   Background:
      Given the user is logged into the Company website
      And the user has valid credentials
      And the browser is Chrome
      And the web browser is at the User Management page

   Scenario: Creating a new user
      Given that <name> does not exist in the User directory
      When the user creates a new account for <name>
      Then a confirmation message indicates success for the account creation

      Examples: New Users
         |  Name     |
         |  David    |
         |  Candice  |

   Scenario: Editing an existing user
      Given that <name2> exists in the User directory
      When the user edits account information for <name2>
      Then a confirmation message indicates success for the changes made

      Examples:  Existing Users
         |  Name2   |
         |  Tracy   |
         |  Austin  |

---

EXAMPLE TEST CASE #2 – Homepage

TITLE
Homepage

PRECONDITIONS

• Client site: https://www.random.notreal
• References: https://somegoogledoc.testisfake

STEPS

1. Open test page.
2. Activate the "test" button.
3. Scroll to the middle of the page.

EXPECTED RESULTS

• Page should open without error.
• Opens new page without error.
• Page should scroll without error.

GHERKIN CONVERSION STEP 1 – TEST CASE ANALYSIS

This looks like a smoke test, so it won’t have a lot of information. We appear to have three separate checks happening here, but the first one is just that the webpage opens properly. All the future tests rely on this happening, so we can chunk that to the Background. We can bypass this as a test because if it’s an issue the test will fail in our Background anyways.

The feature we seem to be testing is the Test button (despite the title saying homepage), which has two different checks, one pre-activation and one post. That makes two scenarios under that feature. We don’t appear to have any variables or items to parametrize.

GHERKIN CONVERSION STEP 2 – FEATURE

No description needed here, very straightforward.

Feature: Test Button

GHERKIN CONVERSION STEP 3 – BACKGROUND AND RULE

Depending on circumstance, we could parametrize the “testing page”, but we keep it vague here so that it’s not dependent on the website URL never changing.

Background:
   Given a web browser has the testing page open.

GHERKIN CONVERSION STEP 4 – SCENARIO or SCENARIO OUTLINES

The Given part of our steps is do define a precondition, which we already have put in the Background. Because of the simplicity of this test, we could also ignore using background for the two scenarios and just repeat. Whatever you feel reads cleaner.

Scenario: Test Button generates content
   When the Test button is activated
   Then a new page opens without any errors

Scenario: Webpage scrolls properly
   Given a new page is open from the test button
   When the user scrolls down the page
   Then no errors are generated

FINAL RESULT

Feature: Test Button

   Background:
      Given a web browser has the testing page open.

   Scenario: Test Button generates content
      When the Test button is activated
      Then a new page opens without any errors

   Scenario: Webpage scrolls properly
      Given a new page is open from the test button
      When the user scrolls down the page
      Then no errors are generated

-- RayFlynn - 12 Aug 2020