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
orBut
when you have multiple instances of a particular step. For instance, if you have threeGiven
circumstances that you want to establish, you could use theGiven
keyword for the first one, and theAnd
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.
- 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:
andScenario:
, are entered automatically, ready for your customization. - 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.
- 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 theFeature:
andScenario:
keywords. As described above, this space is reserved for comment or explanatory text. - On the
Scenario:
line, enter a descriptive name for the Scenario. Optionally, you can add additional description for the Scenario on the lines following theScenario:
keyword and before the step keywords. - Enter
Given
,When
, andThen
keywords, followed by descriptive text for each of these steps. Remember, you can include multiple instances of each type of keyword (or useAnd
orBut
) 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. - 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.
- 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.
- 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.