In TestComplete, you create BDD scenarios in Gherkin – a plain-text language that uses some keywords to organize descriptions into scenarios, test steps and other blocks.
Basic structure
A typical test in Gherkin has features, scenarios and test steps:
Gherkin
Feature: Check the User Profile settings
Check all the ways to open the settings form.
Check the edit features.
Scenario: Test the Login screen
Given The tested app is running
And The Login form is on screen
When I enter JohnSmith in the Name edit box
And I enter no password
And I click Sign In
Then I should see 'Hi, John Smith' in the toolbar
Feature
This is the first element in a Gherkin file. It corresponds to some subsystem or to a larger feature of the tested application. The Feature element groups the scenarios that relate to the feature. The feature description has no special meaning. It just provides information on the tested functionality and may set some common rules or behavior.
Scenario (or Example)
These elements correspond to usage scenarios of the tested application, for instance, to check the price of some product, to get a report in certain format, and so on.
The Scenario and Example keywords are interchangeable. You can use any keyword you like.
Given, When, Then
These elements are called test steps:
-
Givencorresponds to some pre-condition or requirement, for instance, the state of the tested application or some screen status. -
Whencorresponds to user actions over the tested application. -
Thendescribes the expected result.
Each test step can contain multiple parts that are conjuncted via the And or But element (see the example above). A possible alternative to using the And and But elements is to repeat the Given, When or Then element multiple times:
When automating BDD tests in TestComplete, you create script functions for each test step. If a step consists of several parts, you write a script function for each part.
The test step description is used to bind the test step to a script function. If you change the description, you may need to change the binding script statements. See Create Test Step Scripts.
All the test steps (Given, When, Then) are optional. You can skip any of them, if needed. For instance, the scenario below doesn’t have the When step:
Gherkin
Scenario: Check the indicator
Given My app is running and recording is on
Then I should see a flashing icon in the tray
Notes
-
Both feature and scenario descriptions can be multiline. The text in the first line after the
FeatureandScenariokeywords is called the feature or scenario name. The other lines are called a feature description (or scenario description). -
Each .feature file can have only one
Featureelement. -
The keyword names are case-sensitive:
Gherkin
Scenario: ... # Correct
scenario: ... # ErrorTestComplete doesn’t highlight erroneous keywords in the Gherkin editor.
-
TestComplete supports Gherkin keywords written in native languages.
More elements
Background
You use the Background element to specify addition conditions that should be checked before the Given conditions of any scenario:
Gherkin
Feature: My feature description
Background:
Given The tested application is up and running
Tip: The Background condition should be short so that your teammates creating scenarios remember it.
Scenario Outline (or Scenario Template)
You may need to run the same scenario with different parameters. For example, if you are checking a New Order screen in your application, you may want to run tests with different input data to cover various usage scenarios. The Scenario Outline and Scenario Template elements help you do this. These elements are interchangeable. You use them to create scenarios that will run in a loop taking different parameters on each iteration. Here is a sample scenario template:
Gherkin
Scenario Outline: Check discounts
Given The list of orders is clear
And I select Edit > New Order from the main menu
And The New Order form is visible
When I enter <Count> in the Quantity text box
Then The Discount label should display the <Percent> value
Examples:
| Count | Percent |
| 10 | 7 |
| 20 | 10 |
| 30 | 15 |
When running this test, TestComplete will run the test steps several times. Every time, the placeholders in the test step descriptions will be replaced with the Count and Percent values from the Examples table. The < and > symbols designate the placeholders.
If an error occurs during a scenario outline run, TestComplete will behave according to the BDD > Stop the entire Scenario Outline if any example fails property of your project. It will stop the current example run and proceed to the next example of the scenario outline, or it will stop the run entirely.
| Note: |
If you want the test engine to treat each scenario example as a separate test case and display log information for each executed example individually in the Log Details and Summary panels, enable the Treat each example in Scenario Outline as a separate test case project setting. |
For more information on creating such tests, see Parameterize BDD Tests.
Comments
Lines that start with # are considered as comments:
Gherkin
Feature: My feature ...
# Some comment
Scenario:My scenario ....
You can also put a comment at the end of some line:
Gherkin
Feature: My feature ...
Scenario: My scenario ... # Some comment
""" (doc strings) and | (data tables)
If you need to pass a long string to a test step, you use the following syntax:
Gherkin
Scenario: Check email reports
Given I sent an email report
"""
Header: Ordered Items
Content: The attached file contains a list of items ordered last week ...
"""
When ...
These strings are called doc strings or PyStrings (the marker """ came from Python). They help you move long strings from test step descriptions to subsequent lines and display this text in a more readable form. The script function that implements this test step functionality will receive the long string as the last parameter. See Parameterize BDD Tests.
To pass a list or table parameter to a test step, you use the following syntax:
Gherkin
Scenario: Test login data
When We use the following credentials:
| userName | password | message |
| john | abc123 | Error |
| kira | e@45D! | OK |
| jack | xyz 98 | Error |
| sasha | | Error | # No password
Then The Login screen should display proper messages
The script function that implements the test step’s functionality will receive the table as the last parameter. For more information on this, see Parameterize BDD Tests.
Parameters
To specify parameters in test step descriptions, use double-quote ( " ) or single-quote ( ' ) characters:
Gherkin
Scenario: Check the Login form
Given My app has started
And the Login form is visible
When I enter "userName" and "password"
Then I should see the message "Welcome", "userName"
Script functions that you create for these test steps should have parameters that will contain the specified values. The expression that links script functions to test steps should use the {arg} placeholder for the parameters. For example, the script code for the When and Then test steps in the example above can look in the following way:
JavaScript, JScript
When("I enter {arg} and {arg}", function (param1, param2){
// ...
});
Then("I should see the message {arg}, {arg}", function (param1, param2){
// ...
});
Python
@when("I enter {arg} and {arg}")
def step_impl(param1, param2):
# ...
@then("I see the message {arg}, {arg}")
def step_impl(param1, param2):
# ...
VBScript
' [When I enter {arg} and {arg}]
Sub I_enter_and(param1, param2)
' ...
End Sub
' [Then I should see the message {arg}, {arg}]
Sub I_should_see_the_message__(param1, param2)
' ...
End Sub
DelphiScript
// DelphiScript doesn’t support BDD.
C++Script, C#Script
When("I enter {arg} and {arg}", function (param1, param2){
// ...
});
Then("I should see the message {arg}, {arg}", function (param1, param2){
// ...
});
Don’t forget to add parameters to linking expressions and script functions, or generate script code for test steps from the Gherkin editor.
For more information on parameters, see Parameterize BDD Tests.
Tags (@)
You use tags to organize features and scenarios logically based on some criteria. You can then select and run all the features and scenarios defined in your project by some tag or tag combination.
You specify tags by using the @ symbol. You can assign multiple tags, if needed:
Gherkin
@tag1
Feature: ...
@tag-2 @some other tag @Tag3
Scenario: ...
If a tag is assigned to a feature, it is also assigned to the scenarios defined in the feature file. For instance, the Scenario element in the example above will have the tags @tag1, @tag-2@Tag3, and @some other tag (tag names can include spaces).
For complete information on assigning tags and running tests by tags, see Tags.
See Also
Gherkin Keywords in Native Languages
Behavior-Driven Development (BDD) With TestComplete
Gherkin Editor