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:

Given corresponds to some pre-condition or requirement, for instance, the state of the tested application or some screen status.
When corresponds to user actions over the tested application.
Then describes 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 Feature and Scenario keywords 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 Feature element.
The keyword names are case-sensitive:

Gherkin

Gherkin

Scenario: ... # Correct

scenario: ... # Error

TestComplete 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.

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

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.

Gherkin Syntax in TestComplete

Basic structure

Feature

Scenario (or Example)

Given, When, Then

Notes

More elements

Background

Scenario Outline (or Scenario Template)

Comments

""" (doc strings) and | (data tables)

Parameters

Tags (@)

See Also