Tags

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

You can annotate your test scripts with tags to organize and run them by some criteria. For example, you can assign tags to all tests working with certain feature or running in certain environments, and then easily run all the tests for that feature or environment.

Set a tag

  1. In the keyword test editor, if the Tags text box on the toolbar is not visible, click to show it.

  2. In the Tags edit box, type the needed tag in the following format:

    @tag-name

    Keyword test with tags specified

    Click the image to enlarge it.

    If you need multiple tags, separate them with spaces and start each tag with the @ character.

  3. Save the changes.

Notes:

  • A tag name should start with the @ character. Don’t put spaces between @ and the tag name, or anywhere in the tag name. Spaces are used as tag separators.

  • Don’t use parentheses in tag names. They have a special meaning.

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

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 Execution Plan editor of your project. To do this, right-click the project node in the Project Explorer and then 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 Execution Plan editor, 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 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

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 Execution Plan editor of your project. To do this, double-click the Execution Plan node in the Project Explorer or right-click the project node and select Edit > Execution Plan from the context menu.

  2. In the Execution Plan 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. 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 Execution Plan editor.

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

See Also

Keyword Tests
Keyword Tests
About Keyword Test Editor

Highlight search results