Descriptors for TruClient 2.0 scripts

This topic describes how to use the TruClient Descriptor editor to identify objects in your TruClient scripts.

About descriptors

Descriptors support object identification by specifying logical conditions for identifying the object. These include using the object's HTML and CSS properties (such as ID, Class, Position). Each condition contains a property, an operator, a value, and when applicable, optional arguments.

TruClient creates the descriptor conditions during recording, or when you select an object in the step editor.

You can use the Descriptor editor to improve or control identification, by adding or editing conditions. For example, you can edit a descriptor to:

Select a different menu item on each iteration, by parameterizing the menu text.
Identify one of several similar objects by its ordinal position on the page. You can also choose a different object each iteration, by parameterizing the ordinal position.
Add a condition that uses a property that TruClient does not record.
Delete properties that are not required and may change in a way irrelevant to identification.

Manually configure descriptors

You can configure a descriptor in an existing step in your script, or add a Generic object action step.

To configure a descriptor:

Click the More link in the step to open the Step Editor.
In the Object section, select Descriptors as the ID method.
From the Descriptors box, open the Object identification - Descriptors editor.
Set the value for the tagName condition.
Edit the existing conditions as required.
To add additional conditions, click New condition and define the condition parameters:
1. Select an object property. For details, see List of object properties.
2. Select an operator. For details, see List of operators.
3. Set the property value. The property value can be parameterized. For details, see Use parameters in TruClient 2.0 scripts.
If relevant, specify the Object ordinal.

When an element cannot be identified uniquely, you can use the Object ordinal to specify which occurrence to pick.

Note: The Object ordinal is 1-based.

For example, let's assume that you would like to identify the third row of the column in the table below. You cannot do it without setting the Object ordinal to 3, since all the columns look the same.
```
<table>
    <tr><td class”emptyrow”></td></tr>
    <tr><td class”emptyrow”></td></tr>	
    <tr><td class”emptyrow”></td></tr>
    <tr><td class”emptyrow”></td></tr>
</table>
```
You can also set the field to random ordinal, to randomly select from a set similar objects.
Click OK.
Click the highlight object button to verify that the object can be identified.

Use a custom property or attribute

You can use DOM attributes or JavaScript properties to identify an object. JavaScript properties are attached to the DOM object by JavaScript, or by the browser code during initialization. Both attributes and properties can be changed.

Differences between custom properties and custom attributes

The APIs to manipulate properties contain the dot operator. The attribute APIs use the “getAttribute”and “setAttribute” methods.
JavaScript properties cannot be set by the HTML markup.
JavaScript properties cannot be seen in the outerHTML/innerHTML strings of an element, but attributes can be seen in the strings.
The JSON.stringify function serializes a subset of JavaScript properties, but not DOM attributes.

List of object properties

The following table provides a list of object properties:

Property Category	Property	Value type	Description
Role	role	String	Standard role DOM attribute.
ID	id	String	Standard id DOM attribute.
Name	name	String	Standard name DOM attribute.
Class	class	Comma-separated string	A list of the class's stylesheet selectors.
Text	text	String	Inner text.
Label	text	String	Element label.
ARIA label	labeledby	White space separated string	Element ids used as labels for the object.
Title	title	White space separated string	Standard title DOM attribute.
Input type	input/type	String	Type attribute of an input element.
Input text	input/text/value	String	Text value of a text box.
Button value	input/button/value	String	Caption of a button.
Alternative text	alt	String	Alternative text for an element when the text property is not available.
Image source	img/sc	String	Standard src attribute of an image element.
Hyperlink	url protocol pathname search	String	Standard hyperlink properties.
Form action	form/action	String	Standard form action.
Form method	form/method	String	Standard form method DOM attribute.
Table columns	tr/cols	Number	Number of columns for table row elements.
Number	isNumber	Boolean	Determine if the textual content of the element is a number.
Currency	isCurrency	Boolean	Determine if the textual content of the element is a currency value.
Date	isDate	Boolean	Determine if the textual content of the element is a date value.
Time	is Time	Boolean	Determine if the textual content of the element is a time value.
DOM leaf	isLeaf	Boolean	Determine if the element is a tree leaf.
Custom Attribute	attributeA attributeB ... attributeZ	String	Custom DOM attribute with an arbitrary name.
Custom Property	propertyA propertyB ... propertyZ	Expected value is a string while the actual value can be any JS type	Custom JS property with an arbitrary name.

List of operators

The following table provides a list of operators:

Operator	Description
equalsIgnoreChars	Compares the object property to the value specified in the descriptor editor ignoring any characters specified in the Arguments section.
endsWith	The object property ends with the value specified in the descriptor editor.
equals	Compares the object property to the value specified in the descriptor editor. For example, for class, the class has all the style-sheet selectors in the value, and no others.
equalsIgnoreDigits	Compares the object property to the value specified in the descriptor editor, ignoring any numeric characters.
equalsIgnoreCase	Compares the object property to the value specified in the descriptor editor, ignoring case considerations.
equalsIgnoreDeviation	Slight deviations are ignored when comparing the object property to the value specified in the descriptor editor. Applicable only for metrics such as length and width.
startsWith	The object property begins with the value specified in the descriptor editor.
contains	The object property contains the full value specified in the descriptor editor. For example, for class, the class has all the style-sheet selectors in the value, and may have others.
contained	The object property contains the value specified in the descriptor editor. For example, for class, the class has at least one of the style-sheet selectors in the value, and may have others.
isRegExpMatch	The object property matches the regular expression specified as the value in the descriptor editor. The value is a JavaScript regular expression object.
isSubstring	The object property, for example `alt`, is a substring of the value specified in the value field. Example: If the object `alt` is "aaa" and the value specified in the descriptor editor is "aaab", the return value for the specific expression will be true.