Using Hooks

Applies to TestComplete 14.10, last modified on June 5, 2019

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

Here is an example of the BeforeScenario hook definition. To use other hooks, replace BeforeScenario with the designed hook type:

JavaScript

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

})

Python

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

VBScript

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

End Sub

DelphiScript

  // DelphiScript does not support BDD.

C++Script, C#Script

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

})

All the hook functions use one parameter –

JavaScript

BeforeScenario(function (param1){
  // ...
})

Python

@beforescenario
def someFunc(param1):
  # ...

VBScript

' [BeforeScenario]
Sub SomeFunc(param1)
  ' ...
End Sub

DelphiScript

  // DelphiScript does not support BDD.

C++Script, C#Script

BeforeScenario(function (param1){
  // ...
})

The test engine uses it to pass the Scenario or Feature scripting object that corresponds to the scenario or feature being run 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.

    Show Example

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

    Show Example

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

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

    Show Example

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

    Show Example

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

    Show 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 test 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 (param1){
  // param1 contains the Scenario object
  if (param1.Tags.Contains("@tagA") &&
      !param1.Tags.Contains("@tagB")) {
   // Run the hook code
   // ...
  }
})

Python

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

VBScript

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

DelphiScript

// DelphiScript does not support BDD.

C++Script, C#Script

BeforeScenario(function (param1){
  // param1 contains the Scenario object
  if (param1["Tags"]["Contains"]("@tagA") &&
      !param1["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