Binding Script Functions to Test Steps

Applies to TestComplete 15.47, last modified on January 20, 2023

About

When you command TestComplete to run a BDD scenario, it runs script functions associated with test steps of this scenario:

Running script functions linked to test steps

To determine which script function to use for a test step, you use binding expressions in your code. You specify them before the script function. The expression syntax depends on the scripting language you use in your project:

JavaScript, JScript

Given("My app has started", function (){
  // ...
});

Given("The Login form is visible", function (){
  // ...
});

When("I enter {arg} and {arg}", function (param1, param2){
  // ...
});

Then("I see the message {arg}, {arg}", function (param1, param2){
  // ...
});

Python

@given("My app has started")
def step_impl():
  # ...

@given("The Login form is visible")
def step_impl():
  # ...

@when("I enter {arg} and {arg}")
def step_impl(param1, param2):
  # ...

@then("I see the message {arg}, {arg}")
def step_impl(param1, param2):
  # ...

VBScript

' [Given My app has started]
Sub My_app_has_started()
  ' ...
End Sub

' [Given The Login form is visible]
Sub The_Login_form_is_visible()
  ' ...
End Sub

' [When I enter {arg} and {arg}]
Sub I_enter_and(param1, param2)
  ' ...
End Sub

' [Then I see the message {arg}, {arg}]
Sub I_see_the_message__(param1, param2)
  ' ...
End Sub

DelphiScript

  // DelphiScript does not support BDD.

C++Script, C#Script

Given("My app has started", function (){
  // ...
});

Given("The Login form is visible", function (){
  // ...
});

When("I enter {arg} and {arg}", function (param1, param2){
  // ...
});

Then("I see the message {arg}, {arg}", function (param1, param2){
  // ...
});

As you can see, the binding expression includes the step type (Given, When, Then) and a substring that matches the test step description. The And and But steps should use the Given, When, or Then type depending on the step type they belong to.

Matching steps

  • When searching for a script function to use, TestComplete compares the test step description in the BDD scenario and the substring in the binding expression. The substring and description should match.

  • If TestComplete fails to find the matching script function, it posts an error message to the test log.

  • If it finds several script functions matching the same test step, it posts an error message to the log as well.

Expression syntax

In the simplest case, the linking substring coincides with the test step description. TestComplete also supports {arg} placeholders for parameters and regular expressions in substrings.

Test step description

In a linking expression, you can specify exactly the same description of a test step as the one specified in your BDD scenario. For instance, for the following test step –

Gherkin

Scenario: ...
Given The Login form is visible
When ...

– you can using the following binding expression:

JavaScript, JScript

Given("The Login form is visible", function (){
  // ...
});

Python

@given("The Login form is visible")
def step_impl():
  # ...

VBScript

' [Given The Login form is visible]
Sub The_Login_form_is_visible
  ' ...
End Sub

DelphiScript

  // DelphiScript does not support BDD tests.

C++Script, C#Script

Given("The Login form is visible", function (){
  // ...
});

All the literals in linking expressions are case-sensitive.

Regular expressions

To use the same script function for different test steps, you can mark varying parts of step descriptions with regular expressions. For example:

JavaScript, JScript

When("I enter .* and .*", function (){
  // ...
});

Python

@when("I enter .* and .*")
def step_impl():
  # ...

VBScript

' [When I enter .* and .*]
Sub I_enter_john1_and_password2
  ' ...
End Sub

DelphiScript

  // DelphiScript does not support BDD tests.

C++Script, C#Script

When("I enter .* and .*", function (){
  // ...
});

To extract some part of a step description and pass it to the script function as a parameter, enclose the regular expression in braces:

JavaScript, JScript

// Note that use of braces and parameters
When("I enter (.*) and (.*)", function (param1, param2){
  // ...
});

Python

# Note that use of braces and parameters
@when("I enter (.*) and (.*)")
def step_impl(param1, param2):
  # ...

VBScript

' Note that use of braces and parameters
' [When I enter (.*) and (.*)]
Sub I_enter_and(param1, param2)
  ' ...
End Sub

DelphiScript

// DelphiScript does not support BDD tests.

C++Script, C#Script

// Note that use of braces and parameters
When("I enter (.*) and (.*)", function (param1, param2){
  // ...
});

The examples above use the .* expression to designate an arbitrary substring: the . token (period) matches any character, and * (asterisk) matches any number of repetitions. Below are examples of some frequently-used tokens:

Some frequently-used tokens

TestComplete uses the regular expression syntax adopted for JavaScript regular expressions. Use this syntax regardless of the script language your TestComplete uses. For complete information on the supported tokens, see –

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions

If a step description contains parameter placeholders (like {arg}), TestComplete doesn’t apply regular expressions to the description.

{arg} parameters

If a test step has parameters, you can replace them with the {arg} placeholder, for instance:

JavaScript, JScript

When("I enter {arg} and {arg}", function (param1, param2){
  // ...
});

Python

@when("I enter {arg} and {arg}")
def step_impl(param1, param2):
  # ...

VBScript

' [When I enter {arg} and {arg}]
Sub I_enter_and(param1, param2)
  ' ...
End Sub

DelphiScript

// DelphiScript does not support BDD tests.

C++Script, C#Script

When("I enter {arg} and {arg}", function (param1, param2){
  // ...
});

Cucumber parameter types like {int}, {float} or {string} will also work, but we recommend using {arg}.

Note that a description can contain both {arg} placeholders and regular expression tokens. If TestComplete finds a placeholder, it does not handle regular expressions in the description.

Check binding on step update

  • If you change a step description in a BDD scenario, then, most likely, you will have to change the binding expression in your script code. Though you can use regular expressions to make binding expressions more prone to changes, we recommend that you check the binding settings whenever you change test step descriptions in the Gherkin editor.

  • Note that literals in linking expressions are case-sensitive, so you need to update the expressions even if you just replaced upper-case letters with lower-case letters in step descriptions.

See Also

Behavior-Driven Development (BDD) With TestComplete
Parameterize BDD Tests

Highlight search results