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

By.NAME

with this name

Capsule

By.TAG

with this tag

Player

By.LAYER

on this layer

UI

By.COMPONENT

that have a component of this type

Button

By.TEXT

that show this text

Start

By.ID

whose InstanceId or AltId is this value. Every object has a unique id, so this finds one object or none

8756

By.PATH

at this path in the object hierarchy; see Searching by path

//Canvas/Panel/*

The selector and the value are passed the same way in every language:

var children = altDriver.FindObjects(By.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

/Canvas

a root object named Canvas

//Canvas

objects named Canvas anywhere in the hierarchy

//Canvas/Panel

objects named Panel that are direct children of a Canvas

//Canvas//Text

objects named Text anywhere below a Canvas

*

any object

..

the parent of the object before it

[@name=Panel]

objects whose property has this value. The properties are @name, @tag, @layer, @component, @id and @text

[contains(@name,Cub)]

objects whose name contains the string; contains(@text,...) works the same for text

[@tag=UI][@layer=UI]

objects that match every condition

[n]

the n-th of the objects that match, among those with the same parent. [0] is the first, [1] the second, [-1] the last

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
  • 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&A is not escaped.

  • //Q\\&A is 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.

Add AltId