Tags

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

You can annotate your test scripts with tags to organize and run them by some criteria. For example, you can assign tags to all scripts working with certain feature or running in certain environments, and then easily run all the tests for that feature or environment. Tags also help you assign custom test case names to your script tests (see below).

Set a tag

To assign a tag to a script function, type a comment with the tag name in the Code Editor right before the function definition:

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

JavaScript, JScript

//@OpenWebStore
function OpenWebStore()
{
  …
}

// This test searches for a product
// @AllTests @FindProduct
function FindProduct()
{
  …
}

//@AllTests
//@Add-to-cart @low-priority
function AddToCart()
{
  …
}

Python

#@OpenWebStore
def OpenWebStore():
  …

# This test searches for a product
# @AllTests @FindProduct
def FindProduct():
  …

#@AllTests
#@Add-to-cart #low-priority
def AddToCart():
  …

VBScript

'@OpenWebStore
Sub OpenWebStore()
  …
End Sub

' This test searches for a product
' @AllTests @FindProduct
Sub FindProduct()
  …
End Sub

'@AllTests
'@Add-to-cart @low-priority
Sub AddToCart()
  …
End Sub

DelphiScript

//@OpenWebStore
procedure OpenWebStore();
begin
  …
end;

// This test searches for a product
// @AllTests @FindProduct
procedure FindProduct();
begin
  …
end;

//@AllTests
//@Add-to-cart @low-priority
procedure AddToCart();
begin
  …
end;

C++Script, C#Script

//@OpenWebStore
function OpenWebStore()
{
  …
}

// This test searches for a product
// @AllTests @FindProduct
function FindProduct()
{
  …
}

//@AllTests
//@Add-to-cart @low-priority
function AddToCart()
{
  …
}

Notes:

  • The tag line should be a comment line.

  • Tag names use the syntax like this: @tag-name. Don’t put a space between @ and the tag name.

  • Don’t use spaces, nor parentheses in tag names. These characters have special meaning. To keep readability, you can use hyphens whenever you need a space.

  • Tag names are case-sensitive. That is, @reports and @Reports are different tags.

  • To assign multiple tags to a function, either enter tag names separated with spaces in a line (start each tag with @) , or use multiple lines, or both. See the example above.

  • A tag name should be the first word in a comment. Otherwise, TestComplete will not recognize that tag:

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

    JavaScript, JScript

    // @OpenWebStore              ← Correct
    function OpenWebStore()
    …

    // Some text @FindProduct     ← Incorrect
    function FindProduct()
    …

    Python

    # @OpenWebStore              ← Correct
    def OpenWebStore():
      …

    # Some text @FindProduct     ← Incorrect
    def FindProduct():
      …

    VBScript

    ' @OpenWebStore              ← Correct
    Sub OpenWebStore()
    …

    ' Some text @FindProduct     ← Incorrect
    Sub FindProduct()
    …

    DelphiScript

    // @OpenWebStore              ← Correct
    procedure OpenWebStore();
    …

    // Some text @FindProduct      ← Incorrect
    procedure FindProduct();
    …

    C++Script, C#Script

    //@OpenWebStore              ← Correct
    function OpenWebStore()
    …

    // Some text @FindProduct     ← Incorrect
    function FindProduct()
    …

  • Tag lines should reside right before the function definition. TestComplete processes tags starting from the function declaration line upwards, until it reaches the first line that does not contain tags. Therefore, don’t put empty lines between the tag lines and function declaration. Don’t mix tag lines with non-tag ones.

Run by tag

Option 1 – From the UI

  • In the Project Explorer panel, right-click the project node and then select a tag from the Run submenu (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.

    TestComplete will run all the tests – scripts, keyword tests, BDD scenarios and BDD features – that match the selected tag.

Option 2 – Run as a test item

  1. Open the Test Items page of your project. To do this, right-click the project node in the Project Explorer and then select Edit > Test Items from the context menu, or double-click the project in the Project Explorer and then switch to the Test Items tab.

    Opening the Test Items page of the project editor

    Click the image to enlarge it.

  2. On the Test Items page, add a new test item to your project.

  3. In the Execution entry column, click the ellipsis button and select the needed tag in the subsequent Select Test dialog:

    Run by tag from the Test Items page of the project 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

When you run this test item or when you run the entire project, the test engine will execute all the tests that match the specified tag.

Option 3 – From the command line

To run tests that match a tag, use the /test argument or the /tags argument to specify the needed tag:

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

– or –

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

To learn about TestComplete command line arguments, see TestComplete Command Line.

Run by tag expression

Option 1 – Run as a test item

  1. Open the Test Items page of your project editor. To do this, double-click your project in the Project Explorer and then go to the Test Items tab, or right-click the project node and select Edit > Test Items from the context menu.

  2. On the Test Items page, 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. In the subsequent dialog, select [Tag Expressions]:

    Run BDD tests by tag expression - Start step

    Click the image to enlarge it.

  4. Click the ellipsis button in the Parameters column. Specify the desired tag expression in the Value column of 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.

  • 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)

Option 2 – Run from the command line

To run script tests and BDD 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

To learn about TestComplete command-line arguments, see TestComplete Command Line.

Test order

Whenever you run tests by tags or tag expressions, the test order is not set, that is, the test engine runs the tests in an arbitrary order. If the order matters, you need to run tests in another way. For example, you can create test items, one for each test. Test items run in the explicit order – from top to bottom. See the description of the Test Items page.

Test Results

After running all the tests that match the specified tag or tag expression, TestComplete will collect their results in a single log and show the results grouped by the test names:

Running TestComplete tests that match a tag or tag expression: Test results

Click the image to enlarge it.

Stop tests on errors

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

  • If the tests were run from the TestComplete UI or from the command line, the behavior will depend on the project’s Playback > On error property.

  • If the tests were run as a test item (specified on the project’s Test Items page), the behavior will depend on the test item’s On error property (you set it on the Test Items page).

Depending on the appropriate property value, TestComplete can do one of the following:

  • Continue the test run.

  • Stop the current test run and proceed with the next test matching the tag or tag expression.

  • Stop the entire test 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 tests by tags.

Custom test names

When you run tests by tags, the test engine considers every test as a test case and appends all these tests to the Summary report in the test log. For script tests, it uses the names of script routines you have in the Code Editor.

If these names are not descriptive enough, you can assign tags of the following kind to your script tests:

@"Custom test case name"

Unlike the tag names described above, this custom name can contain spaces. The test engine will use such strings as test case names in the Summary report:

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

JavaScript, JScript

//@OpenWebStore
//@"Open Web Store test"    ← Custom test case name
function OpenWebStore() {
  …
}

Python

#@OpenWebStore
#@"Open Web Store test"    ← Custom test case name
def OpenWebStore():
  …

VBScript

'@OpenWebStore
'@"Open Web Store test"    ← Custom test case name
Sub OpenWebStore()
  …
End Sub

DelphiScript

//@OpenWebStore
//@"Open Web Store test"    ← Custom test case name
procedure OpenWebStore();
begin
  …
end;

C++Script, C#Script

//@OpenWebStore
//@"Open Web Store test"    ← Custom test case name
function OpenWebStore() {
  …
}

Note: If you specify several test case names, TestComplete will use the one that was specified last.

See Also

Script Tests
Run Scripts

Highlight search results