Keyword Tests

Applies to TestComplete 15.65, last modified on July 17, 2024

In TestComplete, in keyword-driven tests, every test action (a mouse click, keystroke, and so on) is described by a keyword.


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. The operations can have parameters 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


You can create keyword tests with any type of license and with any set of TestComplete modules.

If the keyword tests are not available in TestComplete, check if the following plugins are enabled in the File > Install Extensions dialog (these plugins are installed and enabled by default during the TestComplete installation):

  • Keyword Testing
  • Keyword Test Editor

You can find the plugins in the Common group. 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. You can view the operations in the Operations list on the left of the Keyword Test editor:

Operations list

Operations are organized into 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 various test actions over your tested application, call script routines or code snippets, and run other tests from your keyword test. For more information about available operations, see:

Operation Reference

To find the needed operation faster, you can filter the operation list. Start typing the operation name or a short description of the action to perform, and TestComplete will filter the list of operations to match the typed text. For example, the image below shows the list of operations that match the “click button” search request:

Searching for keyword test operations
Operation parameters

Keyword test operations can have parameters that specify input values for the action to be performed. You specify operation parameters in 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 of the Keyword Test editor. For detailed information on parameters of an operation, see the operation’s description.

Operation parameters can take values of various types: 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.

Operation results

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.

Grouping operations

In keyword tests, operations that run subsequently and simulate user actions over the same tested object or process are grouped together. These operations are displayed as child nodes of the tested object or process node:

Grouping Nodes

Grouping nodes do not perform any actions, they do not have parameters and do not return values. Grouping is used to make the structure of keyword tests clearer and easy to understand.

Operations are grouped automatically.

The maximum number of group nodes that can be displayed in the Keyword Test editor is specified by the Maximum depth option. To show operations without grouping nodes in the Keyword Test editor, disable the Group operations setting.

Some keyword test operations (for instance, the LLog Message, Delay and Comment operations) cannot have nodes. If you add such operations to a test, they may split the current group node. To avoid this, you can specify keyword test operations that do not split groups. To do this, use the Operations that do not affect grouping setting. When this setting is enabled, the operations added to a group do not split the group and 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 be added outside of the group.

You can add custom groups to your tests by using the Group operation.

Running tests

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

  • As your project’s test item.

  • If a test has one or more tags assigned, you can run it by tags. See Tags.

  • Manually, from the Project Explorer panel.

  • Manually, from the Keyword Test editor.

    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.

  • From another keyword test.

  • From scripts.

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

For detailed information on running keyword tests, 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 helps easily re-use existing tests and perform various testing actions with minimum effort.

You can add parameters to a test and set their default values on the Parameters page of the Keyword Test editor or using the Add Parameter wizard.

Specify the parameter values before you run the test:

  • If you run a keyword test as a project’s test item, specify the parameters in the execution plan. See Execution Plan Editor - Properties Panel.

  • If you run a keyword test from another keyword test, specify the parameters as the parameters of the appropriate operation that will run the test.

  • If you run a test from script code, specify the test parameters in the script code.

If parameters have default values, you can omit them when calling the test.

For detailed information on test parameters, see:

Keyword Test Parameters

Keyword test variables

You can use variables in keyword tests, for example, to assign values to operation parameters, store various values and references to objects, and pass data from one operation to another during the test run. 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.

You can change the variable values by using the Set Variable Value operation. 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, 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

To debug keyword tests, you can use ordinary and conditional breakpoints, 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.

During the debugging, you can use the Locals, Watch List, Call Stack, Breakpoints panels.

For detailed information on debugging, 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 new to TestComplete or when you need to create a simple test quickly.

However, the number of actions you can perform in keyword tests by using the 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 create custom keyword test operations and use them in your tests. You can do this by using script extensions. 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

TestComplete 15 Documentation
Project Items

Highlight search results