By selector#
Every command that finds or waits for objects takes a By selector and a value. The selector says
which property of the objects to match the value against. For the commands themselves, see
Finding objects; for which selector to pick, see
Choosing a selector.
Selector types#
There are seven selectors:
Selector |
Finds objects |
Example value |
|---|---|---|
|
with this name |
|
|
with this tag |
|
|
on this layer |
|
|
that have a component of this type |
|
|
that show this text |
|
|
whose InstanceId or AltId is this value. Every object has a unique id, so this finds one object or none |
|
|
at this path in the object hierarchy; see Searching by path |
|
The selector and the value are passed the same way in every language:
var children = altDriver.FindObjects(By.PATH, "//Canvas/Panel/*");
AltFindObjectsParams params = new AltFindObjectsParams.Builder(AltDriver.By.PATH,
"//Canvas/Panel/*").build();
AltObject[] children = altDriver.findObjects(params);
children = alt_driver.find_objects(By.PATH, "//Canvas/Panel/*")
Find The Children Of Panel
${children}= Find Objects PATH //Canvas/Panel/*
Searching by path#
A path selects objects by where they are in the hierarchy, in the style of XPath. It always starts
with / or //.
Path syntax#
Syntax |
Selects |
|---|---|
|
a root object named |
|
objects named |
|
objects named |
|
objects named |
|
any object |
|
the parent of the object before it |
|
objects whose property has this value. The properties are |
|
objects whose name contains the string; |
|
objects that match every condition |
|
the n-th of the objects that match, among those with the same parent. |
Important
The indexer works as in XPath: [n] picks the n-th of the objects that match the selectors
and share a parent, not the n-th child of an object.
Examples#
The examples search the sample hierarchy below. Select a path to highlight the objects it finds.
FindObjects returns all of them; FindObject returns the first one it reaches, marked in orange.
Sample hierarchy
- Main Camera Camera AudioListener tag MainCamera id 1062
- Canvas Canvas CanvasScaler GraphicRaycaster layer UI id 2310
- Panel Image layer UI id 8756
- Title “Main menu” Text layer UI id 8802
- Button Image Button layer UI id 8814
- Text “Start” Text layer UI id 8820
- Button Image Button layer UI id 8832
- Text “Options” Text layer UI id 8838
- Button Image Button layer UI id 8850
- Text “Quit” Text layer UI id 8856
- Text “v1.0” Text layer UI id 8868
- Panel Image layer UI id 9104
- Title “Options” Text layer UI id 9110
- SoundToggle Toggle layer UI id 9122
- Label “Sound” Text layer UI id 9128
- Button Image Button layer UI id 9140
- Text “Back” Text layer UI id 9146
- Panel Image layer UI id 8756
- Player CapsuleCollider PlayerController tag Player id 3400
- Cube BoxCollider tag Enemy id 4210
- Cube (1) BoxCollider tag Enemy id 4228
- CubeSpawner CubeSpawner id 4300
found by FindObjects returned by FindObject
Paths
Within each object, FindObject checks its direct children before the objects below them, so the
first object it returns isn’t always the highest one in the hierarchy. When several objects match,
make the path specific enough to find only the one you want.
Escaping characters#
Some characters in a selector value must be escaped:
;and&separate and end requests (these are the defaults; you can change them in the server settings). Left unescaped, they make the whole request invalid and can shut down the server.!,[,],(,),/,\,.and,are part of the path syntax. Left unescaped, they can make the search return the wrong object or nothing.
To escape a character, put \\ before it:
//Q&Ais not escaped.//Q\\&Ais escaped.
\\ is how you write one backslash in a C#, Java or Python string, and in Robot Framework: the
path that reaches the app is //Q\&A, and that single backslash escapes the &. In a string that
takes backslashes as they are, such as a C# @"..." string or a Python r"..." string, write
one backslash: @"//Q\&A".
AltId#
An AltId is a unique identifier that AltTester® Unity SDK stores in a component on an object, so
a test can find the object by an id that stays the same from one run to the next. By.ID matches
it, as well as the InstanceId Unity assigns at run time.
Important
Only objects that are in a scene when the app is built get an AltId. Objects created while the app runs don’t have one.
To give every object an AltId, choose Add AltId to every object from the AltTester® menu in the Unity Editor.
