Object identification

Use mechanisms built in to TruClient scripts to improve object identification.

In this topic:

Object identification overview

Object identification is one of the biggest challenges with recording and replaying Web 2.0 applications because objects can move or change content. The result is that when recorded objects change dynamically during replay, TruClient can lose the ability to automatically locate the object.

TruClient includes sophisticated mechanisms to overcome this challenge including the Highlight, Improve Object Identification, Replace Object and Related Object, and Object Identification Assistant options.

Suspend object selection mode

Highlight, Improve Identification, Replace, and Related Objects all require you to select an object in the application. There are cases in which various actions are required in the application to make the object visible such as mouse over and mouse click. In these cases, press CTRL+ALT+F6 to suspend the TruClient object selection mode until you've brought the object into view. Press CTRL+ALT+F6 again to select the object.

Back to top

Highlight an object

Regardless of which method of object identification is used, you can use the highlight button, located in the Object section of the step, to check if an object is visible in the application at any time. If the object is not found this may be an issue of pacing and timing. If the object cannot be found, an error message is displayed.

Back to top

Improve object identification

If the Highlight option fails, use the Improve Object Identification option, and re-select the original object.

This option is located in the Object section of the step, next to the ID Method dropdown. This lets TruClient relearn the properties of the object and compare them to the properties learned during recording. Based on the differences, you can make the necessary adjustments. Depending on how dynamic the application is, you may need to use the Improve Object Identification function more than once.

After you have done this, replay the step to verify that the problem has been solved.

Back to top

Use alternative steps

Alternative steps allow you to view instances in which there are multiple ways to perform the same user action in a step. If Improve Object Identification fails, try using one of the alternative steps.

For example, you may be clicking on an option in a dropdown list in which the text changes based on some value. If you try to click based on the text, the step may fail. If you use an alternative step that selects the item in the list based on the ordinal value of the option within the list, the click succeeds regardless of the text.

Steps that have alternative options are labeled with an alternative step symbol . Click it to view the alternative options for that step. Click the relevant alternative and select Back.

Below is a snapshot of a step in which the second item in a list box named "Desktop" was selected. The alternative steps feature gives you the option of defining the step based on clicking the link "Desktop", selecting the object "Desktop" from the list box, or selecting the first item in the list box.

Back to top

Modify the object identification method

You can modify the way TruClient identifies the object by modifying the object identification method in the Object section of the step properties. To modify the identification method for multiple steps, select the steps you want to modify, and in the context menu, select Change Object Identification Method and choose a method for the selected steps.

The following options are available:

ID Method	Description
Automatic	TruClient's default object identification method. The Automatic method allows TruClient to use its internal advanced algorithms to locate the object. If this method does not successfully find the object during replay, click the Improve Object Identification button and replay the script.
XPath	If Automatic identification fails, even after using Improve Identification or Related Objects (described below), try using the XPath identification method. This method identifies the object based on an XPath expression that defines the object in the DOM tree. Click the dropdown arrow next to the XPath edit box to select a suggested XPath for the object. You can manually modify the suggested path. To revert to one of the original expressions generated by TruClient, select one of the options from the dropdown again. For example, if you need to select the first search result, regardless of the term being searched for, using XPath identification may help. Note: If the object to identify is encapsulated in a web component, and you want to change the XPath expression, we recommend you do not manually modify it. Instead, click to generate a new XPath expression.
JavaScript	JavaScript code that returns an object. For example: document.getElementById("SearchButton") returns an element that has a DOM ID attribute of "SearchButton". Using the JavaScript identification method, you can write JavaScript code that references the returned document and can use CSS selectors and other standard functions. For example, the page returned by the server contains multiple links with the same "title" attribute (search results), and you want the script to randomly click on one of the available links. Object identification for this case, using the JavaScript identification method, may look something like this: var my_results = document.querySelectorAll('a[title="SearchResult"]'); random(my_results);
Descriptors	Enables you to identify an object by its properties in an editor. For details, see Descriptors.

Back to top

Modify the script timing

Sometimes objects may not be found because of timing and synchronization issues. For example, the script may be looking for an object that was in the application, but the script replayed too quickly and already progressed to another page. If you suspect that the object is not being found because of a timing or synchronization issue, you can insert Wait steps. For more information, see Insert Wait steps.

Back to top

Relate an object to other objects

If neither the Improve Object Identification function nor alternative steps solve the issue of object identification, try using the Related Objects option. Relating objects enables you to enhance object identification by telling TruClient about another “anchor” object, with a known position, relative to the required element.

If an object becomes difficult to identify on its own, you can label the object based on a different, more stable object. Relations are defined visually, relating objects according to their distance in pixels from other objects. Relations are defined per ID method, per object. If more than one relation is defined for an ID method of a given object, both relations must locate the same object for the step to pass. TruClient then uses this object to help locate the target object. To use this function, expand the step, select Object > Related Objects, and click the Add a new relation button. Follow the directions to create a relation. Verify that it has worked by highlighting both the object and its related object.

Back to top

Replace an object

If you selected the wrong object during recording, or an object has permanently changed, you can replace it with a different object without replacing the step. This deletes changes made to the original step such as relations.

1. Expand the step, select Object, and click the Replace button .

2. Select the new object and replay the script.

   TruClient removes any current knowledge of the object and learns the new object you selected.

Back to top

Learn about the object identification assistant

Object identification can fail during replay for several reasons. For each reason, TruClient launches the object identification assistant to try to resolve failed identification. If the object identification can be improved automatically, you may be prompted to confirm a change in the identification method. If you accept the change, TruClient changes the script, and the replay resumes.

Back to top

Cannot confirm object

TruClient suspects a specific object to be the required object but it cannot be positively identified. The suspected object is highlighted on the screen, and the assistant dialog box appears.

Options:

• Yes. The suspected (and highlighted) object is the correct object.
• Locate. The suspected object is not the right object. You need to identify the correct object in the application.
• Cancel. Stop the replay.

Back to top

Multiple objects found

TruClient found several objects that match the identification of the required object. All suspected objects are highlighted on the screen, and the following assistant dialog box appears:

Options:

• The correct object is one of the marked objects. Click the object in the application to specify the correct one.

• Locate. The suspected object is not one of the highlighted objects. You need to highlight the correct object in the application.

• Cancel. Stop the replay.

Back to top

Object not found

TruClient could not find the required object. The following assistant dialog box appears:

Options:

• Locate. Locate the object. You need to highlight the correct object in the application.

• Cancel. Stop the replay.

Back to top

Wrong level on step

TruClient found that a step in a higher level is needed for the identification of the object of current step. This is common for mouse over steps that are usually recorded in level 3 but might be needed for click steps that are recorded in level 1.

When TruClient recognizes this dependency during recording, the mouse over will move automatically to level 1.

When TruClient recognizes this dependency during replay, the assistant dialog box appears.

Options:

• Yes. Move the needed step to level 1.
• Cancel. Stop the replay.

Back to top

Non-standard upload of files

If the AUT implementation for file upload is not done in the standard way, the input element (which is dynamically created by inline script or script tag) is not supported for uploading a file. Instead, you can manually add a non-standard upload step to your script.

To manually add a non-standard upload step to your script:

1. Click Step, select Functions and drag the Generic Object Action step to the relevant location in your script.

2. In the application browser window, select the object to upload.

3. Expand the step, and change the step action type to Upload.

4. Set the required step parameters.

   

Limitations

The input element which is created in the DOM script tag is not attached to the DOM object.

Back to top

See also:

• Troubleshoot object identification
• Debug a TruClient script
• Descriptors