One commonly encountered problem is that many applications change the texts used by some widgets. For instance, a button's text might change from Pause to Resume and back again, or the application might put the name of the current file or workspace in the main window's title bar caption. For example, lets assume that we have the following real name for a fictional MainWindow object in our application with the title “AddressBook v1.3 - google contacts.dat”:

{'windowTitle': 'AddressBook v1.3 - google contacts.dat', 'type':'MainWindow'}

This multiple property name will match the first object in the application which is of type MainWindow and whose title matches the one shown above.

Such names work perfectly well in most situations and they are generated automatically when recording a test (see Object Name Generation (Section 7.12) for more information on that topic). Unfortunately, since the windowTitle changes, this can break object names that point to it or its children.

If we wanted to make the MainWindow's real name more general, we could remove the property entirely, or use the Wildcard or the RegularExpression matching options. From the Object Map Editor, one can be selected by double-clicking on the Equals operator between the property and the value in a real name, as shown below:

Changing the matching operator in a real name property.

We can see how these object names are represented by looking at the Scripted Object Map's suite_xyz/shared/scripts/names.(py|pl|rb|tcl|js) file, as shown below:

MainWindow_Wildcard = {"type": "MainWindow", "windowTitle": Wildcard("Address Book*")}
MainWindow_Regex =    {"type": "MainWindow", "windowTitle": RegularExpression("Address Book.*")}

export var mainWindowWildcard = {"type": "MainWindow", "windowTitle": new Wildcard("Address Book*")};
export var mainWindowRegex =    {"type": "MainWindow", "windowTitle": new RegularExpression("Address Book.*")};

our $mainwindow_wildcard = {"type" => "MainWindow", "windowTitle" => wildcard("Address Book*")};
our $mainwindow_regex =    {"type" => "MainWindow", "windowTitle" => regularExpression("Address Book.*")};

MainWindow_Wildcard = {:type => "MainWindow", :windowTitle => Wildcard.new("Address Book*")}
MainWindow_Regex =    {:type => "MainWindow", :windowTitle => RegularExpression.new("Address Book.*")}

set MainWindow_Wildcard [::Squish::ObjectName type MainWindow windowTitle {-wildcard {Address Book*}}]
set MainWindow_Regex    [::Squish::ObjectName type MainWindow windowTitle {-regularexpression {Address Book.*}}]

In a real world situation, you would not need both of these entries - they are equivalent. Both real names specify that the windowTitle must begin with “Address Book” followed zero or more other characters.

The Wildcard version uses * for the wildcard, and it stands for zero or more of any characters. The RegularExpression version uses dot (.) to match a single character, and star (*) as a quantity-modifying meta-character that applies to the thing before it, making it "zero or more" in quantity. These both should match “AddressBook - Untitled” and also “AddressBook - MyAddresses.adr”.

This kind of matching can be used in all situations, and is the only kind of matching that is allowed for type and for properties whose value is an object (i.e., is specified using a real name). Here is an example:

{"type": "LineEdit", "visible": 1, "buddy": {"text": "Phone:", "type": "QLabel"}}

This real name is used to identify an object of type LineEdit that has a visible set to true (1) and that has an associated label—a buddy—which in turn is specified using another real name.

The Wildcard syntax is used for inexact matches. This kind of matching cannot be used for the type property or for symbolic object names.

When wildcard matching is in use the ?, *, [, ], and \ characters all take on special meanings and are not matched literally. All other characters are matched literally.

Here is a real name containing a wildcard:

{'type' : 'LineEdit', 'visible':'1',
 'buddy': {'type':'Label', 'text':Wildcard("Name*\?"} }

This real name is used to identify an object of type LineEdit that has a visible property set to true (1) and that has an associated label—a buddy—which in turn is specified using another real name. But here, the buddy's label text is specified using Wildcard matching and must contain the text “Name” followed by zero or more other characters followed by a literal “?”.

Here's a real name containing a RegularExpression property match:

{'caption': RegularExpression('UsefulApp v[1-9].[0-9] - ?*.[dD][aA][tT]'),
 'type': 'MainWindow'}

Here, caption must have a value that starts with the literal text “UsefulApp v” followed by a digit (but not including zero), then a period, then another digit, then a space, a hyphen, and a space, and then at least one character (indicated by the ?), then zero or more other characters (due to the *), followed by “.dat” (in upper- or lower-case). Notice that if we had specified the filename part of the caption as *.[dD][aA][tT] it would have matched the suffix alone, i.e., “.dat” since the * symbol can match zero characters. By starting with the ? we ensure that at least once character is matched in front of the suffix.

The RegularExpression syntax is used for inexact matches. This kind of matching cannot be used for the type or for properties whose value is an object (i.e., is specified using another real or symbolic name). Regex matching allows us to write more sophisticated—and potentially harder to understand and maintain—matching expressions than can be achieved using wildcard syntax. For this reason, we recommend using wildcard matching where possible simply because it is easier, both to read and write.

	Different Regular Expression Syntaxes
	In Squish for Web editions, the regex syntax is the same as the one supported by JavaScript. Documentation for this syntax is available from Regular-Expressions.info and w3schools.com. For all other Squish editions the Qt QRegExp syntax is used—this is documented here: QRegExp.

Which properties does a particular object have that can be used for identifying an object? The answer is not straightforward because the properties are discovered dynamically.

To take the Qt toolkit as a typical example: Squish exposes all the object's base class's properties (i.e., QObject's properties), also any object-type-specific properties that have been added by the supplier or by the AUT (e.g., through subclassing), and finally some artificial properties that are especially useful to Squish.

In general, any of an object's properties is potentially usable for identifying it (e.g., in a real name for calls to the findObject and waitForObject functions). However, only the non-artificial properties are suitable for use in verifications (e.g., in calls to the test.compare function and other test module functions).

To find out what an object's non-artificial properties are, either look up the object's type in its toolkit's documentation, or use the Spy. To use the Spy begin by launching the AUT (see the Launch AUT action (Section 8.1.1.22)), then interact with the AUT until the relevant AUT object is visible. At this point context switch back to the Squish IDE and invoke the pick action (see the Application Objects view (Section 8.2.1)); and pick the object of interest. Now all the object's non-artificial properties will be shown in the Properties view (Section 8.2.12). To find out the object's artificial properties, invoke the context menu on the object in the Application Objects view (Section 8.2.1) and copy its real name to the clipboard: any properties in the real name that are not listed in the Properties view (Section 8.2.12) are artificial properties.