About Keyword Testing

Applies to TestComplete 14.90, last modified on June 15, 2021

This topic explains the basic concepts of keyword-driven tests in TestComplete and briefly describes how to create, record, modify, run and debug these tests. The topic contains the following sections:


Keyword-driven tests consist of keywords that define the action to be performed by the test. Each keyword corresponds to an individual action like mouse click, selection of a menu item, keystrokes, opening or closing a window and so on. So, a series of keywords correspond to the actions a user performs during the test. The testing approach that uses these tests is called keyword-driven testing. We skip the word “-driven”, so in TestComplete UI and documentation this testing approach is called keyword testing and keyword-driven tests are called simply keyword tests.

In TestComplete, the keywords (actions) that make up a keyword test are called operations. Each operation has a number of parameters that define the details of the action to be performed.

Keyword tests you create with TestComplete are stored in the Keyword Testing collection of your TestComplete project. The tests are shown as child elements of the collection in the Project Explorer.

Keyword-driven tests in the Project Explorer panel


Creating keyword tests is available in TestComplete regardless of the license you have. The following plugins must be enabled in TestComplete (they are installed and enabled by default during the TestComplete installation):

  • Keyword Testing
  • Keyword Test Editor

You can check whether the plugins are installed and active in the Common section of the File > Install Extensions dialog. If the plugins are not listed there, re-install TestComplete.

Create and edit keyword tests

You can create keyword tests in several ways:

  • The easiest way is to record a keyword test.

  • You can add an empty keyword test to your project and then add operations to the test manually or by recording them.

  • You can add existing keyword tests to your project.

For detailed information on recording and adding keyword tests to your project, see Creating and Recording Keyword Tests.

After recording or creating an empty keyword test, you can modify it in the Keyword Test editor:

KDTest Editor

Operations, their parameters and result values

TestComplete provides a number of operations that you can use in your keyword tests. The operations that you can add to your test are shown in the Operations list on the left of the Keyword Test editor:

Operations list

Operations are organized into a number of categories. For example, operations of the Logging category let you post messages and images to the test log. By using operations of the Checkpoints category you can execute various verification actions from your tests. Operations of the Test Actions category let you simulate different test actions over your tested application, call script routines or just short code snippets and run other tests (for instance, low-level procedures) from your keyword test. You can even run other keyword tests from your test.

For more information about available operations, see Operation Reference.

Keyword test operations have parameters that let you specify input values for the action to be performed. An operation may not have parameters, if the action does not need additional parameters.

You specify operation parameters in special dialogs which are displayed when you add the operation to your keyword test. You can also modify the parameters any time later by using the dialogs and in-place editors provided by the Keyword Test editor. For detailed information on parameters of an operation, see the operation’s description.

To specify parameters, you can use values of different kinds: string or integer constants, code expressions, keyword test parameters, properties of onscreen objects and so on. This is described in the Specifying Operation Parameters topic. We recommend that you read it when modifying the parameter values.

Some keyword test operations can return result values. TestComplete offers special means that let you check the operation’s result from your keyword tests. For more information on this, see Checking Operation Result.

TestComplete uses special grouping nodes to organize operations that were executed subsequently and dealt with the same window or processes. These operations are displayed as child nodes of the window or process node and these window or process nodes are called grouping nodes:

Grouping Nodes

Grouping nodes do not perform any actions, they do not have parameters and do not return values. They are used to make the structure of keyword tests clearer and easy to understand. TestComplete creates these nodes automatically during test recording, if you perform several actions on the same window or process, or at design time, if you append several operations that work with the same window or process in a series.

The maximum number of group nodes that can be displayed in the Keyword Test editor is specified by the Maximum depth option. In order not to display grouping nodes in the Keyword Test editor, use the Group operations setting. If this option is disabled, the operations will be displayed without grouping nodes.

Some keyword test operations (for instance, the Log Message, Delay and Comment operations) do not have nodes. If you add such operations to a test, they may break the current group node. To avoid this, TestComplete allows you to specify keyword test operations that do not break operation groups when they are added to a test. There is the Operations that do not affect grouping setting that is used for this purpose. When this setting is enabled, the operations that are added to a group do not break the group node. They are displayed as child items of that node. If you try to add operations at the beginning or at the end of a node, they will jump out of the group.

To group the operations in your test, you can also use the Group operation.

Running tests

You can execute keyword tests in any of the following ways:

  • You can run the test as your project’s test item.

  • If a test has one or more tags assigned, TestComplete will run it when you run tests by tags. See Tags.

  • You can run the test from the Project Explorer panel.

  • You can run the test from the Keyword Test editor. Here you can either run the entire test, an individual operation or a part of the test starting from one particular operation to the end of the test.

  • You can run a keyword test from another keyword test.

  • You can run keyword tests from scripts.

If your test takes parameters, you may need to specify them before running the test. See below.

For detailed information, see Running Keyword Tests.

For information on how to output data from the test and obtain its result, see Setting and Checking a Keyword Test Result.

Parameters of Keyword Tests

A keyword test can have one or more parameters that let you pass additional values to the test before running it. This feature helps you easily re-use existing tests and perform various testing actions with minimum efforts.

The way in which you specify test’s parameters depends on the way, in which you run the test:

  • If you run a keyword test as a project’s test item, then you can specify the parameters’ values in the Test Parameters dialog (it is called from the Execution Plan editor and is used to specify parameters of keyword tests and script routines that are run as test items).

  • If you run a keyword test from another keyword test, you specify the parameters in the Operation Parameters dialog which is shown when you add the test running operation to your keyword test.

  • If you run a test from script code, then you can specify the test’s parameters from script code.

Parameters may have default values. In this case, you can omit them when calling the test.

You create test parameters and specify their default values on the Parameters page of the Keyword Test editor or using the Add Parameter wizard.

For detailed information on test parameters, see Keyword Test Parameters.

Keyword Test Variables

A keyword test can have one or more variables. We call these variables keyword test variables. Using these variables you can assign values to operation parameters, store various values and references to objects and pass data from one operation to another during the test execution. You can also use these variables to output data from your keyword test.

You create keyword test variables, specify their type and default values in the Variables page of the Keyword Test editor or using the Add Variable wizard.

TestComplete provides the Set Variable Value operation that lets you change the variable’s value from your keyword tests. The keyword test variables are also accessible from scripts.

Keyword test variables do not save their values between test runs. Before running a keyword test, TestComplete initializes the variables with their initial values that you specified on the Variables page.

For detailed information on working with variables of this kind, see Keyword Test Variables.

Keyword Test Tags

A keyword test can have one or more tags assigned to it:

Keyword test with tags specified

Click the image to enlarge it.

You use tags to filter tests when specifying a run sequence for your project. This way, you can run only those tests that match a particular tag or a group of tags. See Tags.

Debugging Keyword Tests

TestComplete includes the keyword test debugger that supports powerful debugging features. You can set ordinary or conditional breakpoints on individual operations of your test, run the test to the cursor, trace into or step over tests that are called from your test, explore the values of the test variables in the Evaluate dialog and perform other actions.

All of the panels that are involved in debugging - Locals, Watch List, Call Stack, Breakpoints - support the keyword test debugger. Furthermore, the script and keyword test debuggers are tightly integrated, so, for instance, if you debug a keyword test, you can trace into the script routine that is called from this test and continue debugging script code. Similarly, if you debug a script that runs a keyword test, you can trace into this test and debug it.

For detailed information on debugging services provided by TestComplete, see Debugging Tests.

Keyword Tests vs. Scripts

A keyword test is similar to a script routine. Like the routine, it can have variables and parameters. It contains operations that, like function calls in script code, let you perform various actions during the test.

Like script routines, keyword tests can be used as event handlers. With keyword tests you can handle events that occur in TestComplete and in any ActiveX object that implements the IDispatch interface and belongs to a tested application. For detailed information on event handling in TestComplete and using keyword tests as event handlers, see About Events and Event Handling.

The benefit of keyword tests is that in many cases it is easier and faster to create them than to write the script equivalent. To create keyword tests you do not have to know the specifics of certain scripting languages. So, you can use keyword tests if you are an inexperienced TestComplete user or when you need to create a simple test quickly.

However, the number of keyword test operations is limited and sometimes it may be more convenient to run script code to perform tasks. Also, the scripting engine provides a lot of objects and offers more powerful functionality than keyword test operations. So, you can use scripts to run some complex portions of your tests or perform those actions that do not have keyword test analogues.

You can convert your keyword test to script to see how to perform this or that action with scripting objects. For complete information on this, see Converting Keyword Tests to Scripts.

Creating Custom Keyword Test Operations

You can extend the set of available operations by creating your own operations. You can create operations using the script extensions technology. For more information, see Creating Keyword Test Operations.

TestComplete includes the Log Attributes operation that is implemented with the help of script extensions. You can find the operation’s source code in the AQAScriptExtensions.tcx file that is located in the <TestComplete>\Bin\Extensions\ScriptExtensions folder. This file is a ZIP archive that has the .tcx extension. So, you can use any zip archiver to unpack files from it. For information on the extension’s files, see Pre-Installed Script Extensions.

See Also

Keyword Tests

Highlight search results