Tags

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

About

You assign tags to features and scenarios to organize and run them by some criteria. For example, you can use tags to specify the operating system or environment in which the test should run, the browser that the test should check, the application subsystem or functionality that should be tested, and so on. You can then iterate through the list of features and scenarios, check their tags and run the features and scenarios that match your conditions.

Set a tag

You set tags in the Gherkin editor. Enter them before the feature or scenario description. Tags use a simple @tag syntax:

Tags in TestComplete Gherkin editor

As you can see in the image above, you can assign multiple tags, if needed. Simply separate them with spaces and make sure to put @ before each tag.

Notes

  • You can apply tags to the following Gherkin elements:

    • Feature
    • Scenario
    • Scenario Outline (or Scenario Template)
    • Examples

    Test steps cannot be tagged.

  • Tag names are case-sensitive. For example, @reports and @Reports are different tags.

  • Tag names cannot include spaces.

  • Tag names cannot include parentheses.

  • A tag you set for a Feature applies to all Scenarios of this Feature.

    A tag set for a Scenario Outline (or Scenario Template) applies to the Examples element in this Scenario Outline (Scenario Template).

  • The Scenario Outline (or Scenario Template) elements can have multiple Examples. By using tags you can run tests for a this or that set of data:

    Gherkin

    Gherkin

    Scenario: Test the Login screen
     Given The Login form is on screen
     When I enter "userName" and "password"
     Then I should see "message"

     @tag1
     Examples:
     |userName|password|message  |
     |user1   |pswd1   |Msg 1 ...|
     |user2   |pswd2   |Msg 2 ...|

     @tag2
     Examples:
     |userName|password|message  |
     |user3   |pswd3   |Msg 3 ...|
     |user4   |pswd4   |Msg 4 ...|

    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.

Run by tag

Option 1 – Run from the UI

  • In the Project Explorer, right-click the project node, and then click  Run @<tag_name> (if the Project Explorer panel is hidden, select View > Project Explorer from the main menu to display it):

    Run scenarios by tag

    Click the image to enlarge it.

    This command will run all the features and scenarios that have the specified tag set for them.

Option 2 – Run as a test item

You can make a “tag run” test item and run features and scenarios by a tag along with other project tests as part of your project run:

  1. Open the Execution Plan editor of your project. To do this, right-click the project and select Edit > Execution Plan from the context menu, or double-click the Execution Plan node in the Project Explorer:

    Opening the Execution Plan editor

    Click the image to enlarge it.

  2. In the editor, create a new test item.

  3. Click the ellipsis button in the Execution entry column and select the desired tag in the subsequent dialog:

    Run by tag from the Execution Plan editor

    Click the image to enlarge it.

    TestComplete will add the “tag run” to the test item list. It will run all the tests that match the selected tag when you run the entire project or if you run the test item to which the “tag run” is linked:

    Tag run in the list of test items

Option 3 - Run from the command line

To run feature files and scenarios by tag, you can use a command line like this one:

TestComplete.exe project-suite-file /project:project-name /test:"@tag1" /run

– or –

TestComplete.exe project-suite-file /project:project-name /tags:"@tag1" /run

For more information on other arguments, see TestComplete Command Line.

Run by tag expression

Some frameworks, like Cucumber, can run a combination of tags like @tag1 and @tag2, or @tag1 and not @tag3. To do this in TestComplete, run your BDD tests as test items, or write script code that will check tags of features and scenarios and will run them from script.

Option 1 - Run as test item

  1. Open the Execution Plan editor of your project. To do this, right-click your project in the Project Explorer and select Edit > Execution Plan from the context menu, or double-click the Execution Plan node.

  2. In the editor, click New Test Item or New Child Test Item to add a new test item to your project.

  3. Click the ellipsis button in the Execution entry column, and in the subsequent dialog, select [Tag Expressions]:

    Run BDD tests by tag expression - Start step

    Click the image to enlarge it.

    This indicates that a test item will run tests that match a tag expression.

  4. To set a tag expression, click the ellipsis button in the Parameters cell and specify the desired tag expression in the Value cell in the subsequent dialog:

    Run BDD tests by tag expression - Enter the expression

    Click the image to enlarge it.

    You can either enter the expression, or specify a project or project suite variable that stores the expression:

    Run BDD tests by tag expression - Select a variable storing the expression

    Click the image to enlarge it.

    Click OK to save the changes.

Option 2 - Run from script

The script function below demonstrates how to check tags from script code. It iterates through the features and scenarios in your project and runs those features and scenarios that have the @Win10 tag assigned and don’t have the @LoginForm tag assigned. The main function to run is RunByTag(). The function that checks the tags is checkBDDItem(). If you copy this code to your tests, re-write the checkBDDItem() function to check the condition you need.

When checking tags, make sure to specify @ before the tag name.

JavaScript, JScript
Python
VBScript
DelphiScript
C++Script, C#Script

JavaScript, JScript

// Run features and scenarios (@Win10 and not @LoginForm)
function RunByTag(){
  // Iterate through features
  for(i = 0; i < Features.Count; i++) {
    var feature = Features.Item(i);
    // Call a custom function to check feature tags
    if (checkBDDItem(feature))
      feature.Run();
    else
      // Iterate through feature scenarios
      for(j = 0; j < feature.Scenarios.Count; j++) {
        scenario = feature.Scenarios.Item(j)
        // Call a custom function to check scenario tags
        if (checkBDDItem(scenario))
          scenario.Run();
      }
  }
}

// Check feature and scenario tags
function checkBDDItem(BDDItem) {
  return BDDItem.Tags.Contains("@Win10") && !BDDItem.Tags.Contains("@LoginForm");
}

Python

# Run features and scenarios (@Win10 and not @LoginForm)
def RunByTag():
  # Iterate through features
  for i in range(0, Features.Count):
    feature = Features.Item[i]
    # Call a custom function to check feature tags
    if checkBDDItem(feature):
      feature.Run()
    else:
      # Iterate through feature scenarios
      for j in range(0, feature.Scenarios.Count):
        scenario = feature.Scenarios.Item[j]
        # Call a custom function to check scenario tags
        if checkBDDItem(scenario):
          scenario.Run()

# Check feature and scenario tags
def checkBDDItem(BDDItem):
  return BDDItem.Tags.Contains("@Win10") and not BDDItem.Tags.Contains("@LoginForm")

VBScript

' Check feature and scenario tags
Function CheckBDDItem(BDDItem)
  CheckBDDItem = BDDItem.Tags.Contains("@Win10") And Not BDDItem.Tags.Contains("@LoginForm")
End Function

' Run features and scenarios (@Win10 and not @LoginForm)
Sub RunByTag
  ' Iterate through features
  For i = 0 to Features.Count - 1
    Set Feature = Features.Item(i)
    ' Call a custom function to check feature tags
    If CheckBDDItem(Feature) Then
      Feature.Run
    Else
      ' Iterate through feature scenarios
      For j = 0 to Feature.Scenarios.Count - 1
        Set Scenario = Feature.Scenarios.Item(j)
        ' Call a custom function to check scenario tags
        If CheckBDDItem(Scenario) Then
          Scenario.Run
        End If
      Next 
    End If
  Next
End Sub

DelphiScript

  // DelphiScript does not support BDD functionality.

C++Script, C#Script

// Run features and scenarios (@Win10 and not @LoginForm)
function RunByTag(){
  // Iterate through features
  for(i = 0; i < Features["Count"]; i++) {
    var feature = Features["Item"](i);
    // Call a custom function to check feature tags
    if (checkBDDItem(feature))
      feature["Run"]();
    else
      // Iterate through feature scenarios
      for(j = 0; j < feature["Scenarios"]["Count"]; j++) {
        scenario = feature["Scenarios"]["Item"](j)
        // Call a custom function to check scenario tags
        if (checkBDDItem(scenario))
          scenario["Run"]();
      }
  }
}

// Check feature and scenario tags
function checkBDDItem(BDDItem) {
  return BDDItem["Tags"]["Contains"]("@Win10") && !BDDItem["Tags"]["Contains"]("@LoginForm");
}

For information on accessing features and scenarios in scripts, see Scripting (BDD).

Option 3 - Run from the command line

To run features and scenarios that match a tag expression, use the /tags command-line argument:

TestComplete.exe project-suite-file /project:project-name /tags:"@tag1 or (@tag2 and @tag3)" /run

For more information on other arguments, see TestComplete Command Line.

Notes on the expression syntax:

  • Use @ before tag names, that is, use @tag1 rather than tag1.

  • To combine tags, use the and, or and not operations, for example:

    @tag1 or @tag2
    @tag1 and not @tag3
    not @tag5

    These operations don’t depend on the scripting language you use in your TestComplete project. That is, for example, in JavaScript projects you should use and, or and not rather than &&, || and !  —

    @tag1 and not @tag2  ← Correct!
    @tag1 && !@tag1      ← Incorrect!

  • If needed, you can use braces to group tags, for example:

    @tag1 and (@tag2 or @tag3)
    (@tag1 or not @tag2) and (not @tag3 or @tag4)

Stop on errors

If an error occurs during the run, TestComplete will post an error message to the test log. Its further behavior depends on the following:

  • If the features or scenarios were run from the TestComplete UI, from the command line, from a script test or keyword test, the behavior will depend on the project’s Playback > On error property.

  • If the features or scenarios were run as a test item (specified in the project’s Execution Plan editor), the behavior will depend on the test item’s On error property (you set it in the Execution Plan editor).

Depending on the appropriate property value, TestComplete can act in one of the following ways:

  • Continue the run.

  • Stop the current item run and proceed with the next scenario or feature matching the tag or tag expression.

  • Stop the current item and rerun it.

  • Stop the entire run.

For detailed information, see either the project’s Playback > On error property description or the test item’s property description, depending on the way you run your features and scenarios.

Tagged hooks

Hooks are special script functions that run automatically at the beginning or at the end of a scenario or feature file. You can make hooks work only for those scenarios and features files that have the needed tags assigned. For complete information on this, see Tagged Hooks.

See Also

Tagged Hooks
Behavior-Driven Development (BDD) With TestComplete

Highlight search results