Identifying Properties¶

Identifying properties are element properties that are used to look up the element during test execution. A loosely formulated example: "Suitest, find me an element that has a blue background color with the text 'Settings' in it". The blue background and the text "Settings" is what we call the identifying properties.

In different situations different identifying properties are suitable. For example if there are many elements with blue background on the page, the blue background property alone may no longer be a good choice for identifying property, since it does not identify the element uniquely.

When choosing the right set of identifying properties your goal should be to find the one producing the most unambiguous results. You should consider the following:

Will this set of identifying properties select the correct element?
Will it work if the application pops-up a message, user is logged out, etc.
Is it page-specific or will it work on other pages/views as well?
Is it stable enough to survive minor or major application updates?

CSS selector¶

CSS selectors are a query language that allow selecting an element based on its current set of attributes and other properties. CSS selectors are applicable to HTML-based apps only. Basic example of CSS selectors:

#someId - selects an element with an id attribute someId.
.someClassName - selects elements having a class name attribute someClassName.
div - selects all div tags on the page.
[data-title="Hello"] - selects elements with a data-title attribute having a particular value (in this case Hello).
.someClass, .someOtherClass - selects element having either of the specified classes.

Multiple CSS Selectors can be combined together for narrowing down the matching set.

div.someClassName - selects div tags having a class someClassName.
div .someClassName - Notice the white space! Selects elements having class name someClassName and placed inside a div tag.
div > .someClassName - selects elements with class someClassName which are direct descendants of a div tag.

You can easily find a lot of information about CSS selectors on the Internet. W3Schools provides a nice overview. Some types CSS selector have a tendency to be fragile when it comes to application changes. You should consider finding an element which is resistant to app changes, meaning that the CSS selector would remain the same even when changes to the application are done, such as adding new elements.

Escaping unusual class names¶

Due to HTML5 providing you the ability to add unusual symbols or reserved CSS symbols into the class names, you will have to escape them when using CSS selectors. Take care when adding elements with these unusual names to the element repository.

Examples of unusual class names:

class="#"
class="##"
class="♥"
class="©"
class="{}"
class="“‘’”"
class="⌘⌥"
class="{}"
class="[attr=value]"

Some examples of escaping in CSS selectors:

.\3A \`\( {}
matches elements with class=":`("

.\31 a2b3c {}
matches elements with class="1a2b3c"

#\#fake-id {}
matches the element with id="#fake-id"

#-a-b-c- {}
matches the element with id="-a-b-c-"

#© {}
matches the element with id="©"

XPath query¶

XPath is a query language for addressing parts of an XML document, and selecting an element based on the expression.

Note: below are only a couple examples of what can be done with this powerful query language.

Absolute XPath¶

Absolute XPath is one way to use XPath for selecting elements on most platforms. For example:

/ScrollViewer/ScrollContentPresenter/Border

Will match Border elements with ancestors ScrollViewer and ScrollContentPresenter. Absolute XPath can be very fragile when it comes to app structure changes, as XPath will become invalidated.

Relative XPath¶

This feature is currently not supported on:
Roku - using Standard IL

If you want to identify an element on Roku by relative XPath, please try Roku Lite instead.

Relative XPath expressions are a powerful tool to find specific elements based on indexing, properties or both.

Beware: Node names and attributes are case sensitive meaning that element StackPanel and stackPanel are two different elements.

By index¶

<StackPanel>
    <Button name="first" />
    <StackPanel>
        <Button name="second" />
        <Button name="third" />
    </StackPanel>
</StackPanel>

Using the example above, select the second Button element of any parent like so:

//Button[2]

Output: <Button name="third" />

Alternative is to find all Button elements and then select the second one like so:

(../..//Button)[2]

Output: <Button name="second" />

By properties¶

This feature is currently not supported on:
Roku - using Standard IL

If you want to identify an element on Roku by XPath together with a Property related only to the given element, you can combine the XPath and Attributes identifiers. If you need to identify parent elements based on Property, please try Roku Lite instead.

<StackPanel>
    <Button name="first" />
    <StackPanel>
        <Button name="second" id="bigButton" />
        <Button name="third" />
    </StackPanel>
</StackPanel>

Search for an element by its properties like so:

//Button[@name="first"]

Output: <Button name="first" />

More properties can be used by using and operator. For example:

//Button[@name="second" and @id="bigButton"]

Output: <Button name="second" id="bigButton" />

It is not necessary to just use the = operator, the following can also be used:

 >
 >=
 <
 <=
 !=

Use it in the following way:

//Button[@opacity>0.2]

By property and index¶

This feature is currently not supported on:
Roku - using Standard IL

If you want to identify an element on Roku by XPath together with an Index and Property related only to the given element, you can combine the XPath, Index and Attributes identifiers. If you need to identify an element using Index and Property of a parent element, please try Roku Lite instead.

Combine properties and index to narrow down your expressions even further like so:

//Button[@name="btn-name"][3]

Alternatively search through all elements and then select the second one which matches the expression.

(../..//Button[@name="btn-name"])[2]

Wildcard¶

The wildcard can be used in case the element just needs to match a specific property or index.

//*[@name="bigButton"]
//*[2]

Element attributes¶

Element attributes are a powerful way for creating unique and robust selectors. You can use any element attribute that is displayed in the view structure tool and you can combine multiple attributes together.

Example: someAttribute=someValue,someOtherAttribute=someOthervalue will match elements having both attributes with the specified values.

Xbox (One, Series X/S) Native applications have a notion of automationID and automationName attributes which are intended specifically for test automation. Convince your development team to specify meaningful values for these attributes and use them in your test scenarios. You can find more information about setting unique automation properties in Visual Studio Docs.

Text content¶

Selects elements that contain the specified text. Please note that this identifying property is case-sensitive.

Example: Settings will match elements with text content equal to "Settings" (elements containing "settings" will not be matched)

Element Position¶

Please note that in case of Android WebView applications, the coordinates and sizes entered by the user are supposed to be in CSS Pixels and not the device pixels. Suitest automatically recalculates the number based on device's screen pixel density.

Selects elements at the position specified in pixels relative to the top left corner of the screen. Please note that the pixel values are absolute and are calculated at runtime, so this selector will not be suitable for element that changes position for some reason.

Example: 200,150 will match elements located at 200 px from the left corner and 150 px from the top corner of the screen.

Element Size¶

Selects elements having a particular size specified in pixels as width,height. Please note that the pixel values are absolute and are calculated at runtime. This selector may not be suitable for elements changing their size for some reason.

Example: 100,50 will match elements which are 100 px wide and 50 px tall.

Element Color¶

Elements color is using two formats.

RGBA : rgba(0,0,0, 0.0) to rgba(255,255,255, 1.0)
Hex : #ffffff,#00ff00,#000099

Link text¶

Comparing the inserted string with texts of all links. Searches for exact match, case sensitive.

Partial link text¶

Comparing the inserted string with texts of all links. Searches for a substring match, case sensitive.

Index¶

If all other identifying properties match more than one element the index allows to specify which element from the set should be used.

Example: CSS selector div matches all the div tags on the page. Specifying the set index to be 2 will match the second div tag.

Previous:
Adding or editing an element Next:
Multiplatform apps