Creating Tests with Gherkin

When you create tests with Gherkin in Eggplant Functional, you will describe your test scenario at a high level by using specific Gherkin keywords along with natural language. The result should be test files that are easily readable and explain the feature being tested, the various scenarios used in testing it, and the expected outcome for each scenario.

The steps in your Gherkin code are linked to SenseTalk handlers, which perform the actions against your systems under test (SUTs). When you have developed a Gherkin test in "human readable" language, it's then easy to generate the necessary SenseTalk handlers.

Definition of a Feature

The Gherkin implementation in Eggplant Functional follows the standard rules for the language. The basics of using Gherkin are described here, but for more complete information, check the Gherkin Reference from Cucumber.

Your Gherkin test is created in a Feature, which is stored as a .feature file. Each line of the Feature must generally start with a Gherkin keyword, or be blank.

The first line begins with the keyword Feature:. Note that the colon (:) is part of the keyword. The Feature: keyword can be followed by a name or description on the same line. You can use lines following this keyword for additional description or explanation of what the feature is expected to do or test.

ノート

Any additional lines used for description must not begin with a recognized Gherkin keyword. This exception to the rule that every line begins with a keyword applies only to lines following the Feature: and Scenario: keywords that you are using as comment text.

Scenarios fill out the rest of the Feature. A Scenario describes a specific sequence that might be used to test the Feature. Typically, the Scenario begins by describing the initial or given circumstances, then describes the action or actions that will be taken, and ends by defining the expected outcome.

A Scenario begins with the keyword Scenario:. Again, the colon (:) is required as part of the keyword. The Scenario: keyword can be followed by a name or description on the same line. As with the Feature: keyword, you can use lines following this keyword for additional description or explanation of what the scenario is expected to do or test. Lines used for description must not begin with a recognized Gherkin keyword.

The Scenario is made up of steps, and the steps each begin with a Gherkin keyword followed by natural language that explains the purpose of the step. The keywords for steps are as follows:

• Given: Use this keyword to describe an initial circumstance or context. You can use multiple Given steps within the same Scenario, or omit this step.
• When: This keyword generally describes the event or action for the Scenario. You might think of this as the condition you are testing with this Scenario. You can include multiple When steps within the same Scenario, or omit this step.
• Then: This step describes the expected outcome for the Scenario, and as with the other keywords, you can include multiple Then steps, or omit this step. You typically want to state this step as an assertion for the expected result, and you will be testing this against the actual outcome.
• And, But: For readability, you can use the keywords And or But when you have multiple instances of a particular step. For instance, if you have three Given circumstances that you want to establish, you could use the Given keyword for the first one, and the And keyword for the additional two steps. See the example below.

With step keywords, you do not use a colon. Following the keyword, you add language on the same line that describes the specific step or test. This text can be whatever you like. It is not, strictly speaking, code, although it links to the SenseTalk handlers you will write to perform the tests, verifications, and other actions on your SUT.

A sample Scenario might look like this:

Scenario: Add two numbers on the Calculator app
  Given that the Calculator app is running and in focus
  And there is no current value in the calculator
  When you add 3 and 5
  Then the value displayed should be 8

You can add as many Scenarios to a Feature as you want. Typically, each Scenario describes a specific test of the Feature.

Scenarios are the basic test elements of Gherkin Features. However, Eggplant Functional supports several techniques that you can use to create more complex testing scenarios. For information about additional capabilities, see Advanced Gherkin Techniques.

Step by Step: Creating Gherkin Tests

Use the following guide to create tests with Gherkin code in the Eggplant Functional editor.

1. To create a new Feature, right-click in the Features pane of the Suite window, then select New Feature. On Mac OS X, you can also click the gear icon at the top of the pane and select New Feature. A new, untitled Feature opens in the editor. Note that the first lines of code, Feature: and Scenario:, are entered automatically, ready for your customization.
2. Provide a name for the .feature file by updating it in the Features pane. When you generate SenseTalk handlers for Scenario steps (step 6), Eggplant Functional puts them in a script of the same name, creating the script if it doesn't already exist. Note: If you name a Feature the same as a script that already exists in the suite, your generated handlers will get added to that script.
3. On the Feature: line, enter a descriptive name for the Feature so that anyone reading the file knows what it is designed to test. Optionally, add additional description in the lines between the Feature: and Scenario: keywords. As described above, this space is reserved for comment or explanatory text.
4. On the Scenario: line, enter a descriptive name for the Scenario. Optionally, you can add additional description for the Scenario on the lines following the Scenario: keyword and before the step keywords.
5. Enter Given, When, and Then keywords, followed by descriptive text for each of these steps. Remember, you can include multiple instances of each type of keyword (or use And or But) if it makes sense for the Scenario you are creating. You can also skip or omit any of the keyword steps—that is, the steps are not required.
6. To generate the SenseTalk handler to accompany a step, right-click the step and select Show or Generate Handler. The Script Editor opens with the appropriate handler highlighted. Note that if the script itself has not been created, Eggplant Functional creates the script with the same name as the .feature file. See Generating Handlers from Gherkin Steps for more information about how Eggplant Functional generates and names the handlers.
7. In the Script Editor, write your SenseTalk code for the handler to perform the required actions for the step. For detailed information about SenseTalk handlers, see Handlers and the "Handlers" section of Reusing Code.
8. Add additional Scenarios to the Feature as required, repeating steps four through seven.

When you run a Feature test, each step calls its associated SenseTalk handler. For detailed information about running Gherkin tests, see Running Gherkin Tests in Eggplant Functional.

Generating Handlers from Gherkin Steps

To generate a handler for a Gherkin step, right-click anywhere in the text of the step, then select Show or Generate Handler. If the handler already exists, the editor opens the associated script and highlights the first line of the handler.

If the handler doesn't exist, Eggplant Functional creates an empty handler in the appropriate script. That is, it creates the opening and closing code lines of the handler. You then need to write the specific SenseTalk code that you want the handler to perform.

The name of the handler is generated from the text of the Gherkin step, minus the keyword itself. Any spaces or special characters are converted to underscores (_). For example, if your step was

When
you enter the first number in the calculator app

the generated handler in the SenseTalk script looks like this:

to handle you_enter_the_first_number_in_the_calculator_app

end you_enter_the_first_number_in_the_calculator_app

If you change the text in Gherkin after you have generated the handler, you will need to update the handler name to match the new step name, or you can generate a new handler. If they don't match, when you run the test, the Gherkin code won't know what handler to call for the step.

In some cases, Eggplant Functional attempts to parameterize the handler based on text it finds in the Gherkin step. The rules for parameterization are as follows:

• Any string of digits is replaced with NUM.
• Anything in quotes is replaced with STR.
• Anything enclosed in angle brackets (< >) is replaced with VAR.

For example:

Gherkin: Given Logged in user is "Mike" SenseTalk: to handle logged_in_user_is_STR

Gherkin: Given There are 12 users in the system SensetTalk: to handle there_are_NUM_users_in_the_system

Gherkin: Given Flavor of the day is <flavor> SenseTalk: to handle flavor_of_the_day_is_VAR

When a parameter replacement is made in the handler title, a params statement is added to the generated handler with a similarly named parameter. In fact, the params statement can include multiple parameters if multiple replacements are made from the Gherkin step to the SenseTalk handler name.

For example, if the Gherkin step is

When
you enter username "Spike" and 1234 as the PIN

the generated SenseTalk handler looks like this:

to handle enter_username_STR_and_NUM_as_the_pin
params str1, num1

end enter_username_STR_and_NUM_as_the_pin

The code you write can take advantage of the values passed in the params statement, which you can use as variables in your code. The replaced value from your original Gherkin statement is the initial value of the variable.

For more information about taking advantage of parameterized values, see Scenario Outlines.

Handlers in the Associated Script or a Different Script

When you generate handlers from Gherkin steps, Eggplant Functional puts them in a script that has the same name as the .feature file. When you generate the first handler for a Feature, Eggplant Functional creates the script (a .script file) if a script of that name doesn't already exist in the suite.

However, if you have a script of the same name, your generated handlers from that Feature will be added to the existing script. Use care with your file names if you want to avoid writing to an existing script.

Sometimes you might want to use a different script for the handlers for a Feature. For instance, you might find that you have multiple Features that call an identical handler.

In such cases, you could include a #script reference within the Feature, followed by the script name you want to include. For instance:

#script GlobalHandlers
Feature Calculator App Test

In this example, the Feature looks for handlers in a script called GlobalHandlers as well as in a script that matches its own name. Note that using #script doesn't change where auto-generated handlers are created, so you would have to place handlers in the alternate script manually, being careful to maintain the correct naming scheme.

You can reference multiple scripts in this way. Each additional script must be listed on a separate line, preceded by #script:

#script GlobalHandlers
#script PrimaryScript
#script BobStuff
Feature Calculator App Test

Typically, you would place any #script references at the start of your Feature. However, technically, the line or lines can appear anywhere, as long as the line begins with #script.