Why finding unused mapping items

As testing progresses and you create more and more tests, the Name Mapping registry in your project can become large. It is quite possible that it contains obsolete mapping objects for windows and controls that don’t exist in the tested application anymore and that your tests don’t use. You may want to remove these unused items from the Name Mapping list to make it clearer. TestComplete can help you with this.

TestComplete can collect information on usage of Name Mapping items in your tests, and then display this information in the Name Mapping editor. So, you can easily find unused items and remove them. See below for more information on this.

Video Tutorial

1. Collect statistics

To make a well-founded decision on removing mapping objects, you need to collect reliable statistics on their use. To command TestComplete to collect usage data, you can set certain TestComplete options or use a special command-line argument.

Options dialog

In TestComplete, select Tools > Options from the main menu.

In the subsequent Options dialog, select Engines > Name Mapping on the left. You will see the Name Mapping options on the right.
Select the Collect usage statistics check box and specify the name of the file to which TestComplete will save the usage data:

Click the image to enlarge it.

For information on selecting the file location, see the notes below.
Click Save to apply the changes.

The described options are stored on the computer, where TestComplete is installed. If you use your NameMapping project item on other machines, you need to set the options on these machines too. See below for details.

TestExecute includes similar options for collecting usage data.

Command line

In the TestComplete or TestExecute command line, use the /UsageStatistics (or /US) option followed by the statistics file name:

"C:\Program Files (x86)\SmartBear\TestComplete 14\Bin\TestComplete.exe" "C:\Work\My Suite\My Project.mds" /run /US:"\\server\folder\NM-usage.stat"

"C:\Program Files (x86)\SmartBear\TestExecute 14\Bin\TestExecute.exe" "C:\Work\My Suite\My Project.mds" /run /US:"\\server\folder\NM-usage.stat"

For information on selecting the file location, see the notes below.

This command-line option overrides the settings you set in the Options dialog of TestComplete or TestExecute. However, the command-line option is active during one TestComplete session (or one TestExecute session) only, while settings you set in the dialog work for multiple sessions and multiple projects.

Notes

After you enabled the options, the test engine starts collecting information on what Name Mapping items are used in your tests. Every time your keyword or script test addresses a mapped object, TestComplete increases the internal counter for that object. When you address a child object, TestComplete increases the counters for this child object and for all its parent objects.
TestExecute also includes options for collecting usage data. If you run your tests with TestExecute, you need to activate the options in TestExecute, as well.
To gather reliable statistics, you need collect as much information on mapped objects usage as possible. The settings you set in the Options dialog are machine-specific. They will be active on the computer, where you set the options, and in the product (TestComplete or TestExecute), in which you set the options. If you run your tests on other computers, or if your NameMapping project item is shared with other projects that run on other computers, you need to activate the options on all these computers, as well.

Setting options on multiple machines can be a time-consuming task. Using the command-line option often seems to be a more convenient approach. We recommend using it to those who have lots of test machines or run automated tests from Jenkins, Bamboo, or other similar systems.
It’s important that you specify the same file name on all the machines if you use multiple computers. If you enter different names, you will get statistics in different files, and there is no way to merge them.
It’s worth placing the statistics file in some shared folder, so all the TestComplete and TestExecute instances that you use for testing have access to this file.
Both TestComplete and TestExecute save the gathered data to the file on exit.
To delete gathered data, click Clear Statistics in the Options dialog.

2. Run your tests

After you enabled the Collect usage statistics option, run your tests for some time. If you use multiple computers, run your tests on all these machines. A good practice is to run different test scenarios and use different input data to ensure that your runs cover as many test commands as possible.

3. View statistics

To view gathered statistics:

Open your project in TestComplete. Open the NameMapping editor.
In the editor, expand the Mapped Objects section (by default, it is collapsed), right-click anywhere within it and select Show usage from the context menu:

The Mapped Objects tree will display markers next to mapping objects to indicate their usage in tests:

— The object is used in tests.

— The object is presumably unused. This mark is based on gathered statistics that can be incomplete in some cases. See below for details.

— The object is used, but has child items that are (presumably) unused.

To find unused items, expand the items with the mark.

4. Remove unused items

Before deletion ...

Make sure that your tests really don’t use a mapping object. TestComplete marks objects as used or unused based on the data that the statistics file provides. This data can be incomplete for some reason, for example, if you didn’t check enough test scenarios (see below for more examples). By removing mapping items, you can make your tests fail. If you use the same NameMapping project item in several projects, then, by deleting items in one of the projects, you can destroy tests in other projects. Be careful!

To delete one unused item

Right-click the desired item in the Mapping Objects tree, and select Delete from the context menu.

To delete all unused items

Click Delete All Unused Items on the toolbar.

TestComplete will display a warning message asking for your confirmation. Click “Yes”. TestComplete will delete the items from the Mapping Objects tree.

Note:

Before the deletion, TestComplete will create a backup copy of your NameMapping file, so you can easily restore it later, if needed.
It displays a message box with the file name after the deletion is over.

Be careful

TestComplete reports unused items based on the gathered statistics. In some cases, it may report some items as unused while your tests actually use them. Deleting such items will cause your tests to fail. Understanding the cause of the problem and fixing it can take some time. So, be careful. If you share the NameMapping project item between several projects, then deleting the item in one of the projects can destroy tests in other projects. So, be extra careful in this case.

Here are some examples of the cases when an object can be mistakenly considered unused:

You didn’t run some of your tests. So, TestComplete will not collect the usage statistics for mapping items in these tests and will report these items unused. If you run more tests, then probably some of these mapping items will “become” used.
Your test has conditional statements (if… then… else or switch… case), and the tests you run don’t cover all these conditions. So, the mapping items in the uncovered blocks will be considered unused.
Your test has some commands with mapping items commented out. This might happen, for example, if you comment out commands because of an issue in the tested application to make your test pass. If other commands don’t use these “commented” objects, TestComplete will report these objects as unused.
You use a NameMapping project item on multiple computers, but set different statistics files in TestComplete (or TestExecute) options on these computers. In this case, your file will contain data for one project only.
Your project uses a shared NameMapping project item, and —
- You didn’t run other projects that use this project item, or
- You didn’t collect statistics for them (this is possible if the projects run on other computers, or with another tool).
So, the statistics file has data for your project only, which means the data is incomplete in this case.

Recommendation

To decrease the number of erroneous decisions, don’t rush into removing mapping items. Run your tests multiple times to get reliable statistics. Run as many test scenarios as possible to cover as much test code as possible. Before the deletion, make sure that your tests really don’t use the items that are reported as unused. Check other projects that use your NameMapping project item.

What if I removed an item by mistake?

If you are still in the Name Mapping editor, you can undo the deletion immediately by selecting Edit > Undo from the main menu or by clicking Undo on the main toolbar.
If you have run your tests and found an error, you can map the needed object or objects again. See Mapping From Screen and other topics of the Name Mapping section.
If you removed mapping items by using the “Delete All Unused Items” toolbar command, TestComplete created a backup copy of the NameMapping file. You can replace your NameMapping file with that backup copy.

See instructions
See instructionsSee instructions
1. Close your project in TestComplete.
2. Locate your Name Mapping file (.tcNM) in a file manager. To do this, you can right-click the NameMapping item in your project and then click Show in Explorer.
3. Locate the backup file that TestComplete has created before deleting objects. TestComplete displays the backup file name in a message box that is shown after the deletion. It has the .bak extension. TestComplete creates this backup file in the same folder, in which the NameMapping file is located.
4. Replace the current Name Mapping file with the backup file.

Exit the 'Show usage' mode

Right-click anywhere in the Mapped Objects tree and select Show usage from the context menu again.

— or —
Click at the top of the Name Mapping editor.

Find and Remove Unused Mapping Items