7.11. Object Map

7.11.1. The Concept of the Object Map
7.11.2. Squish's Object Map

This section introduces the concept of an automatic object map (often called a GUI object map in QA literature), and how Squish implements this concept.

7.11.1. The Concept of the Object Map

The object map is designed to make it easier to maintain test scripts when the application under test changes its object hierarchy or its object names.

Squish's Object Map holds the names of all the application objects that are used in recorded test scripts or that have been added manually or through the use of the Spy tool.

Test scripts access objects by name, either using real names (also known as multi-property names), symbolic names (sometimes called qualified names), and in some cases using hierarchical names. When Squish records tests it always uses symbolic names, and stores these names in the Object Map along with their corresponding real (or in some cases hierarchical) names.

Symbolic names always begin with a colon, for example, :Card Type:_QComboBox. As this example suggests, symbolic names often take the form of some identifying text followed by an underscore and then the object's type. Real (multi-property) names are braces enclosed strings that contain one or more space separated property-name=property-value pairs, and where the property values themselves might be symbolic names. For example, the real name {buddy=':Make Payment.Card Type:_QLabel' type='QComboBox' unnamed='1' visible='1'} includes a buddy key that refers to another AUT object by that object's symbolic name (:Make Payment.Card Type:_QLabel). Real names usually have at least one property (most often type). Some of the properties are those of the object, and some are “artificial” properties—of which the most important are listed in Real (Multi-Property) Name Properties (Section 7.10.5). Squish also supports another naming scheme—hierarchical names. This is deprecated for all toolkits except for Tk where hierarchical names are the only kind available (since they are a perfect match for Tk's own object naming scheme). Hierarchical names look similar to symbolic names but they don't start with a colon—for example, addressbook\\.tcl.dialog.buttonarea.ok.

When we write tests by hand we can identify our objects using real or symbolic names, perhaps using symbolic names for most of the objects in our tests, and real names in those cases where the extra features they offer are needed. For example, if we are creating a test that is similar to one we have recorded, we might copy and paste symbolic names from the recorded script (or from the Object Map). But in some cases it is more convenient to use real names since they support inexact as well as exact property matching. For example, some applications change their window title bar's caption to show the current filename, and in such cases being able to do an inexact match against the caption is very convenient. (See Improving Object Identification (Section 7.10) for more about inexact property matching.)

When Squish runs a test it looks up objects using their real name, so when it encounters a symbolic name it looks that name up in the Object Map to find the corresponding real name, whereas if it encounters a real name it uses it directly. (Thanks to Squish's use of name caching there is no discernable difference in performance when using either kind of name.)

If one of an object's identifying properties (for real, i.e., multi-property names) changes, or if the object's name, or the name of one of its parent objects (for symbolic, i.e., qualified names) changes, the object's real name becomes invalid and Squish will be unable to access the object.

To solve this problem we can edit the Object Map. In the common case where we are using a symbolic name and one of the object's identifying properties has changed, we can find the symbolic name in the object map and edit the corresponding real name to match the changed property. This does not require us to change any of our test code that uses the symbolic name—although if we've used the real name in our scripts we would have to apply the same change to the real name in our scripts as we applied to the real name in the Object Map.

[Tip]Real (Multi-Property) Names vs. Symbolic Names

Although we are free to use real or symbolic names in our scripts, it is better from a maintenance point of view to use symbolic names where possible. This is because if a change is needed it can normally be made just once in the Object Map to the real name that corresponds to the symbolic name we are using, rather than everywhere the symbolic name is used in our tests. Of course, sometimes it is useful to use real names—for example, if we need to use inexact property matching; however, even this can often be achieved by editing the Object Map and changing properties of a symbolic name from exact to wildcard or regular expression matches.

For more information about Squish's object naming mechanism see Object Name Generation (Section 7.12).

7.11.2. Squish's Object Map

Squish automatically creates and maintains an Object Map for every test suite. Here we will explain how to share an Object Map, and how to edit Object Maps to account for changes to the AUT as discussed above.

7.11.2.1. Creating an Object Map

Whenever Squish records a test case, it creates an Object Map for the suite if one does not already exist, or it uses the existing one—and in either case it adds a symbolic name–real name pair for every object that is accessed in the course of the recording, unless that pair is already in the map (for example, due to being added in a previous recording or earlier in the current recording).

The Object Map is saved in the test suite's root directory, in a file called objects.map, and is shared by all the test suite's tests.

In some cases it is more convenient to store the Object Map elsewhere, particularly if we want to share it between test suites. This can be done by editing the test suite's suite.conf file (which is in the test suite's root directory). Simply add a new key=value pair using the key, OBJECTMAP, and with the value set to the shared object map's path and filename. The path value can be an absolute or relative path. Here is an example that uses an absolute path:

OBJECTMAP = C:\shared\myobjects.map

(It is also possible to share scripts and test data between test suites; see How to Create and Use Shared Data and Shared Scripts (Section 5.23) for more details.)

7.11.2.2. Editing an Object Map

Object Maps are stored as plain text (using the UTF-8 encoding), so it is possible to edit them using a plain text editor. However, we recommend editing the Object Map through the Squish IDE. The Squish IDE's Object Map editor will ensure that the Object Map is not accidentally corrupted (as might happen when hand editing), and also provides some very convenient features that make editing easier—in particular an area for adding and editing object properties.

If you are starting from scratch and want to write tests by hand and to use symbolic names, there are several approaches you can take:

  • In many cases the easiest and quickest approach is to record a dummy test where you make sure that you interact with every object that you plan to use in your hand written tests. During the recording Squish will populate the Object Map, so when it comes to writing your tests you can simply copy and paste the symbolic (or real) names that you need as you need them.

  • Alternatively, you could just Spy the application's window—this will cause the Spy to populate its Object tree with all the application's objects, and then you can right-click each object you are interested in and use the context menu that pops up to add the object to the Object Map. (And of course you could use the Spy tool's Object Picker to spy individual objects if you just needed to add a few of them to the Object Map.)

  • Another approach is to edit the Object Map manually, inserting your own symbolic names—you can use any names you like providing the properties you set for each one uniquely identifies the object and matches an actual object in the application. (New Squish users are recommended to use one of the other approaches—once you have seen a few Object Maps in practice you'll be ready to use this approach.)

As noted earlier, if an object's symbolic name becomes invalid (for example, due to a change in its object name or one of its parents' object names), you can edit the Object Map, changing the properties associated with the symbolic name to match those that have changed. You can use the How to Use the Spy (Section 5.21.3) tool to find the object in the AUT's user interface and add the object (under a new symbolic name, since some aspect of it has changed), to the Object Map. You can then look up the new symbolic name in the Object Map to find out what its property values are, and change the original symbolic name's properties to match. This way, scripts that use the original symbolic name will continue to run correctly, because Squish will look up the symbolic name in the Object Map and then derive the real name from the (now corrected) properties.

When the Object Map is visible when the Spy is actively spying the application under test, it is possible to check which names in the Object Map are valid. To do this, select one or more symbolic names in the Object Map, then right-click to pop up the context menu and choose the Check Object Existence context menu option to check the selected symbolic names.

It is also possible to edit an object's symbolic name in the Object Map. Beware that if you do this, then you must change every occurrence of this name in every test script that uses the Object Map where you changed the symbolic name, replacing the old name with the new one throughout. If you don't do this, then the scripts that use the old (and now no longer existing) name, will fail.

For information about handling the Object Map programmatically in test scripts see Object Map Functions (Section 6.3.11). For information about manipulating the Object Map using the Squish IDE see the Object Map view (Section 8.2.9).