Using Hooks

Applies to TestComplete 14.70, last modified on April 22, 2021

About

Hooks are special script functions that run before or after you execute a BDD script or a feature file. If you have a programming background, you can consider them as event handlers.

TestComplete supports the following hooks:

Hook Description

BeforeFeature

The test engine calls this hook before executing of a feature file (that is, before you run all the scenarios defined in this file).

AfterFeature

This hook works after execution of a feature file.

BeforeScenario

The test engine calls this hook before execution of a BDD scenario. If you run a feature file that contains multiple scenarios, the test engine will call this hook for every scenario.

AfterScenario

The test engine calls this hook after execution of a BDD scenario. If you run multiple scenarios, the test engine will call this hook for every scenario.

Syntax

You can define hooks in any script unit that belongs to the same project as your BDD scenario or feature file. Here are the examples of simple hook syntax:

JavaScript

BeforeFeature(function (feature){
  // Perform some action before running a feature file, for example:
  Log.Message("Before running the " + feature.Name + "feature file");
})
 

AfterFeature(function (feature){
 // Perform some action after executing a feature file, for example:
  Log.Message("The " + feature.Name + " feature file has been executed");
})
  

BeforeScenario(function (scenario){
  // Perform some action before running a scenario, for example:
  Log.Message("Before running the " + scenario.Name + "scenario");
})


AfterScenario(function (scenario){
  // Perform some action after executing a scenario, for example:
  Log.Message("The " + scenario.Name + " scenario has been executed");
})

Python

@beforefeature
def someFunc(feature):
  # Perform some action before running a feature file, for example:
  Log.Message("Before running the " + feature.Name + "feature file")

  
@afterfeature
def someFunc(feature):
  # Perform some action after executing a feature file, for example:
  Log.Message("The " + feature.Name + " feature file has been executed")

  
@beforescenario
def someFunc(scenario):
  # Perform some action before running a scenario, for example:
  Log.Message("Before running the " + scenario.Name + "scenario")

  
@afterscenario
def someFunc(scenario):
  # Perform some action after executing a scenario, for example:
  Log.Message("The " + scenario.Name + " scenario has been executed")

VBScript

' [BeforeFeature]
Sub SomeFunc(feature)
  ' Perform some action before running a feature file, for example:
  Log.Message("Before running the " + feature.Name + "feature file")
End Sub


' [AfterFeature]
Sub SomeFunc(feature)
  ' Perform some action after executing a feature file, for example:
  Log.Message("The " + feature.Name + " feature file has been executed")
End Sub


' [BeforeScenario]
Sub SomeFunc(scenario)
  ' Perform some action before running a scenario, for example:
  Log.Message("Before running the " + scenario.Name + "scenario")
End Sub


' [AfterScenario]
Sub SomeFunc(scenario)
  ' Perform some action after executing a scenario, for example:
  Log.Message("The " + scenario.Name + " scenario has been executed")
End Sub

DelphiScript

  // DelphiScript does not support BDD.

C++Script, C#Script

BeforeFeature(function (feature){
  // Perform some action before running a feature file, for example:
  Log["Message"]("Before running the " + feature["Name"] + "feature file");
})
 

AfterFeature(function (feature){
 // Perform some action after executing a feature file, for example:
  Log["Message"]("The " + feature["Name"] + " feature file has been executed");
})
  

BeforeScenario(function (scenario){
  // Perform some action before running a scenario, for example:
  Log["Message"]("Before running the " + scenario["Name"] + "scenario");
})


AfterScenario(function (scenario){
  // Perform some action after executing a scenario, for example:
  Log["Message"]("The " + scenario["Name"] + " scenario has been executed");
})

As you can see, all the hook functions use only one parameter. It is either the Scenario or Feature scripting object that corresponds to the scenario or feature being run, and the test engine passes this parameter to the hook. You can use it to check the name of the scenario or feature you run, and then perform or skip certain actions for some scenarios or features. See below for examples.

What actions to perform in hooks

Before... hooks

In Before... hooks, you can perform some initialization actions, for example:

  • In BeforeScenario, you can post an image of your application’s window to the test log to be aware of the application state before running a scenario.

    Example

  • In BeforeFeature, you can read a data file that is used by multiple scenarios in your feature file.

    Example

  • In BeforeFeature, you can set up a database connection used by scenarios in your feature file.

    Example

After... hooks

In After... hooks, you can perform some finalization actions, for example:

  • In AfterScenario, you can post an image of the tested application’s window to the test log to get information on the application status at the end of the scenario run.

    Example

  • In AfterFeature (or even in AfterScenario), you can send a notification to your teammates about completion of the run.

    Example

  • In AfterFeature, you can close a database connection that your scenarios used.

    Example

Tip

Remember that if you open a connection or file, or allocate some other resource at the beginning of the run, you need to close this collection or file, or release the resource at the end of the run.

Note, however, that it is quite possible that the After... hooks will not run. This might happen if an error occurs during the test run and the Playback > On error property of your test project is set to Stop project or Stop current item. In this case, TestComplete will stop the test run and will not reach the code in your After hook that releases an allocated resource.

To work around the issue, set the On error property to Continue running, or create an OnLogError event handler and release the allocated resources in it. See also Handling Events - Overview.

Tagged hooks

You can assign tags to feature files and scenarios, and run scenarios and files by tags. You can also make hooks work only for those feature files and scenarios that have specific tags assigned, that is, you can implement tagged hooks. To do this, check the scenario’s or feature file’s tags at the beginning of the hook function and run the hook body depending on the result of the check. The sample hook code below demonstrates how you can implement this. The sample hooks work only for those scenarios that have the @tagA tag assigned, and don’t have @tagB assigned:

JavaScript, JScript

BeforeScenario(function (scenario){
  // param1 contains the Scenario object
  if (scenario.Tags.Contains("@tagA") &&
      !scenario.Tags.Contains("@tagB")) {
   // Run the hook code
   // ...
  }
})

Python

@beforescenario
def someFunc(scenario):
  if scenario.Tags.Contains("@tagA") and not scenario.Tags.Contains("@tagB"):
    # Run the hook code
    # ...

VBScript

' [BeforeScenario]
Sub SomeFunc(scenario)
  ' param1 contains the Scenario object
  If scenario.Tags.Contains("@tagA") And _
     Not scenario.Tags.Contains("@tagB") Then
   ' Run the hook code
   ' ...
  End If
End Sub

DelphiScript

// DelphiScript does not support BDD.

C++Script, C#Script

BeforeScenario(function (scenario){
  // scenario contains the Scenario object
  if (scenario["Tags"]["Contains"]("@tagA") &&
      !scenario["Tags"]["Contains"]("@tagB")) {
   // Run the hook code
   // ...
  }
})

To adopt this example to another hook, simply replace BeforeScenario with the desired hook name. For information on working with tags, see Tags.

More notes

  • The actions you perform in hooks functions are not reflected in feature files and scenarios and are hidden for their authors (in some organizations, BDD scenarios are written by subject matter experts or product managers, while test steps are automated by the QA team or automation engineers). This might be important if the test authors should know about the initialization actions the BeforeScenario or BeforeFeature hooks perform. To make these actions more visible to the authors, you can suggest that they use the Background keyword in BDD tests.

  • You can define multiple hook functions of the same time, for example, multiple scripts functions as a BeforeScenario hook. TestComplete will execute them all. However, their execution order is not configurable.

  • TestComplete ignores the result value of hook functions.

Highlight search results