Finding objects#
Commands that find objects in your app, and wait for them to appear or disappear. They
are all methods of AltDriver and return AltObjects. Most take a
By selector and a value, such as By.NAME and "PlayButton". To
search only below an object you already have, see
FindObjectFromObject.
With By.PATH, an index picks among the objects that match and share a parent, counting
from 0: //Button/Text[1] is the second object named Text under Button. See
Searching by path.
Each command shows its signature and an example in every language; pick a language in any tab and the others switch with it.
Commands on this page#
Command |
What it does |
|---|---|
Finds the first object that matches a selector. |
|
Finds every object that matches a selector. |
|
Finds the first object whose name, tag, layer, component, text or id contains the value, such as |
|
Finds every object whose name, tag, layer, component, text or id contains the value. |
|
Finds the object at a position on the screen. |
|
Returns every object in the loaded scenes, including objects marked |
|
Waits until an object that matches a selector exists, and returns it. |
|
Waits until an object whose name, tag, layer, component, text or id contains the value exists, and returns it. |
|
Waits until no object matches a selector, for example until a loading screen closes. |
Find#
Commands that return the objects that exist right now. A command that returns one object fails with ObjectNotFoundException when nothing matches; one that returns a list returns an empty list. See Errors.
In Java, these commands take their parameters in an AltFindObjectsParams
(AltGetAllElementsParams for GetAllElements, which has no by and value):
new AltFindObjectsParams.Builder(AltDriver.By by, String value)
.withCamera(By cameraBy, String cameraValue) // default By.NAME, ""
.isEnabled(boolean enabled) // default true
.build()
new AltGetAllElementsParams.Builder()
.withCamera(By cameraBy, String cameraValue) // default By.NAME, ""
.isEnabled(boolean enabled) // default true
.build()
FindObject#
Finds the first object that matches a selector. Fails with ObjectNotFoundException when no object matches.
AltObject FindObject(
By by,
string value,
By cameraBy = By.NAME,
string cameraValue = "",
bool enabled = true)
Example
// Tap the Play button in the main menu.
var playButton = altDriver.FindObject(By.NAME, "PlayButton");
playButton.Tap();
AltObject findObject(AltFindObjectsParams params)
Example
// Tap the Play button in the main menu.
AltObject playButton = altDriver.findObject(
new AltFindObjectsParams.Builder(AltDriver.By.NAME, "PlayButton").build());
playButton.tap();
alt_driver.find_object(
by,
value,
camera_by=By.NAME,
camera_value='',
enabled=True)
Example
# Tap the Play button in the main menu.
play_button = alt_driver.find_object(By.NAME, "PlayButton")
play_button.tap()
${alt_object}= Find Object locator_strategy locator camera_by='NAME' camera_value='' enabled=True
Example
# Tap the Play button in the main menu.
${play_button}= Find Object NAME PlayButton
Tap Object ${play_button}
Parameters
Name |
Type |
Default |
Description |
|---|---|---|---|
|
C#, Java, Python: |
required |
What to match the value against: name, path, tag, layer, component, text or id. See By selector. |
|
|
required |
The value to look for, such as the object’s name or path. |
|
C#, Java, Python: |
|
How to find the camera that works out the objects’ screen positions ( |
|
|
|
The camera to use, matched with |
|
|
|
|
Returns
AltObject: The first object that matches.
Note
When several objects match, which one is first depends on the hierarchy. Make the selector specific enough to match only the object you want, for example with a path.
See also: FindObjects · FindObjectWhichContains · WaitForObject
FindObjects#
Finds every object that matches a selector.
List<AltObject> FindObjects(
By by,
string value,
By cameraBy = By.NAME,
string cameraValue = "",
bool enabled = true)
Example
// Count the hearts left in the health bar.
var hearts = altDriver.FindObjects(By.PATH, "//HealthBar/Heart");
int lives = hearts.Count;
AltObject[] findObjects(AltFindObjectsParams params)
Example
// Count the hearts left in the health bar.
AltObject[] hearts = altDriver.findObjects(
new AltFindObjectsParams.Builder(AltDriver.By.PATH, "//HealthBar/Heart").build());
int lives = hearts.length;
alt_driver.find_objects(
by,
value,
camera_by=By.NAME,
camera_value='',
enabled=True)
Example
# Count the hearts left in the health bar.
hearts = alt_driver.find_objects(By.PATH, "//HealthBar/Heart")
lives = len(hearts)
${alt_objects}= Find Objects locator_strategy locator camera_by='NAME' camera_value='' enabled=True
Example
# Count the hearts left in the health bar.
${hearts}= Find Objects PATH //HealthBar/Heart
${lives}= Get Length ${hearts}
Parameters
Name |
Type |
Default |
Description |
|---|---|---|---|
|
C#, Java, Python: |
required |
What to match the value against: name, path, tag, layer, component, text or id. See By selector. |
|
|
required |
The value to look for, such as the object’s name or path. |
|
C#, Java, Python: |
|
How to find the camera that works out the objects’ screen positions ( |
|
|
|
The camera to use, matched with |
|
|
|
|
Returns
List<AltObject> (C#), AltObject[] (Java), list of AltObject (Python, Robot): The objects that match, or an empty list.
See also: FindObject · FindObjectsWhichContain · GetAllElements
FindObjectWhichContains#
Finds the first object whose name, tag, layer, component, text or id contains the value, such as Enemy for Enemy01. Fails with ObjectNotFoundException when no object matches.
AltObject FindObjectWhichContains(
By by,
string value,
By cameraBy = By.NAME,
string cameraValue = "",
bool enabled = true)
Example
// Find an enemy (Enemy01, Enemy02...) and its position on the minimap camera.
var enemy = altDriver.FindObjectWhichContains(By.NAME, "Enemy",
cameraBy: By.NAME, cameraValue: "MinimapCamera");
var onMinimap = enemy.GetScreenPosition();
AltObject findObjectWhichContains(AltFindObjectsParams params)
Example
// Find an enemy (Enemy01, Enemy02...) and its position on the minimap camera.
AltObject enemy = altDriver.findObjectWhichContains(
new AltFindObjectsParams.Builder(AltDriver.By.NAME, "Enemy")
.withCamera(AltDriver.By.NAME, "MinimapCamera")
.build());
Vector2 onMinimap = enemy.getScreenPosition();
alt_driver.find_object_which_contains(
by,
value,
camera_by=By.NAME,
camera_value='',
enabled=True)
Example
# Find an enemy (Enemy01, Enemy02...) and its position on the minimap camera.
enemy = alt_driver.find_object_which_contains(
By.NAME, "Enemy", camera_by=By.NAME, camera_value="MinimapCamera")
on_minimap = enemy.get_screen_position()
${alt_object}= Find Object Which Contains locator_strategy locator camera_by='NAME' camera_value='' enabled=True
Example
# Find an enemy (Enemy01, Enemy02...) and its position on the minimap camera.
${enemy}= Find Object Which Contains NAME Enemy
... camera_by=NAME camera_value=MinimapCamera
${on_minimap}= Get Screen Position ${enemy}
Parameters
Name |
Type |
Default |
Description |
|---|---|---|---|
|
C#, Java, Python: |
required |
What to match the value against: name, path, tag, layer, component, text or id. See By selector. |
|
|
required |
The text that the object’s name, tag, layer, component, text or id contains. |
|
C#, Java, Python: |
|
How to find the camera that works out the objects’ screen positions ( |
|
|
|
The camera to use, matched with |
|
|
|
|
Returns
AltObject: The first object that matches.
Note
With By.PATH, the value is used as a path, as in FindObject. To match part of a name in a path, use contains(), as in //Canvas//*[contains(@name,Enemy)].
See also: FindObject · FindObjectsWhichContain · WaitForObjectWhichContains
FindObjectsWhichContain#
Finds every object whose name, tag, layer, component, text or id contains the value.
List<AltObject> FindObjectsWhichContain(
By by,
string value,
By cameraBy = By.NAME,
string cameraValue = "",
bool enabled = true)
Example
// List every save slot (SaveSlot1, SaveSlot2...), including the hidden empty ones.
var slots = altDriver.FindObjectsWhichContain(By.NAME, "SaveSlot", enabled: false);
foreach (var slot in slots)
Console.WriteLine(slot.name);
AltObject[] findObjectsWhichContain(AltFindObjectsParams params)
Example
// List every save slot (SaveSlot1, SaveSlot2...), including the hidden empty ones.
AltObject[] slots = altDriver.findObjectsWhichContain(
new AltFindObjectsParams.Builder(AltDriver.By.NAME, "SaveSlot")
.isEnabled(false)
.build());
for (AltObject slot : slots)
System.out.println(slot.name);
alt_driver.find_objects_which_contain(
by,
value,
camera_by=By.NAME,
camera_value='',
enabled=True)
Example
# List every save slot (SaveSlot1, SaveSlot2...), including the hidden empty ones.
slots = alt_driver.find_objects_which_contain(By.NAME, "SaveSlot", enabled=False)
for slot in slots:
print(slot.name)
${alt_objects}= Find Objects Which Contain locator_strategy locator camera_by='NAME' camera_value='' enabled=True
Example
# List every save slot (SaveSlot1, SaveSlot2...), including the hidden empty ones.
${slots}= Find Objects Which Contain NAME SaveSlot enabled=${False}
FOR ${slot} IN @{slots}
${name}= Get Object Name ${slot}
Log ${name}
END
Parameters
Name |
Type |
Default |
Description |
|---|---|---|---|
|
C#, Java, Python: |
required |
What to match the value against: name, path, tag, layer, component, text or id. See By selector. |
|
|
required |
The text that the objects’ name, tag, layer, component, text or id contains. |
|
C#, Java, Python: |
|
How to find the camera that works out the objects’ screen positions ( |
|
|
|
The camera to use, matched with |
|
|
|
|
Returns
List<AltObject> (C#), AltObject[] (Java), list of AltObject (Python, Robot): The objects that match, or an empty list.
Note
With By.PATH, the value is used as a path, as in FindObject. To match part of a name in a path, use contains(), as in //Canvas//*[contains(@name,Enemy)].
See also: FindObjects · FindObjectWhichContains
FindObjectAtCoordinates#
Finds the object at a position on the screen. Returns null (None in Python and Robot Framework) when there is none.
AltObject FindObjectAtCoordinates(AltVector2 coordinates)
Example
// See what a tap on the Play button would hit, such as a popup in front of it.
var playButton = altDriver.FindObject(By.NAME, "PlayButton");
var hit = altDriver.FindObjectAtCoordinates(playButton.GetScreenPosition());
Console.WriteLine(hit?.name ?? "nothing");
AltObject findObjectAtCoordinates(
AltFindObjectAtCoordinatesParams params)
new AltFindObjectAtCoordinatesParams.Builder(Vector2 coordinates)
.build()
Example
// See what a tap on the Play button would hit, such as a popup in front of it.
AltObject playButton = altDriver.findObject(
new AltFindObjectsParams.Builder(AltDriver.By.NAME, "PlayButton").build());
Vector2 position = playButton.getScreenPosition();
AltObject hit = altDriver.findObjectAtCoordinates(
new AltFindObjectAtCoordinatesParams.Builder(position).build());
System.out.println(hit != null ? hit.name : "nothing");
alt_driver.find_object_at_coordinates(coordinates)
Example
# See what a tap on the Play button would hit, such as a popup in front of it.
play_button = alt_driver.find_object(By.NAME, "PlayButton")
hit = alt_driver.find_object_at_coordinates(play_button.get_screen_position())
print(hit.name if hit else "nothing")
${alt_object}= Find Object At Coordinates coordinates
Example
# See what a tap on the Play button would hit, such as a popup in front of it.
${play_button}= Find Object NAME PlayButton
${position}= Get Screen Position ${play_button}
${hit}= Find Object At Coordinates ${position}
Log ${hit}
Parameters
Name |
Type |
Default |
Description |
|---|---|---|---|
|
C#: |
required |
The position, in screen pixels, such as an object’s |
Returns
AltObject: The object at that position, or null (None) if there is none.
Note
AltTester® looks for a UI object first, with EventSystem.RaycastAll. If none is there, it casts a ray with Physics.Raycast and Physics2D.Raycast, and returns the object hit closest to the camera.
See also: FindObject
GetAllElements#
Returns every object in the loaded scenes, including objects marked DontDestroyOnLoad.
List<AltObject> GetAllElements(
By cameraBy = By.NAME,
string cameraValue = "",
bool enabled = true)
Example
// List every object in the loaded scenes, active or not.
var elements = altDriver.GetAllElements(enabled: false);
foreach (var element in elements)
Console.WriteLine(element.name);
AltObject[] getAllElements(AltGetAllElementsParams params)
Example
// List every object in the loaded scenes, active or not.
AltObject[] elements = altDriver.getAllElements(
new AltGetAllElementsParams.Builder().isEnabled(false).build());
for (AltObject element : elements)
System.out.println(element.name);
alt_driver.get_all_elements(
camera_by=By.NAME,
camera_value='',
enabled=True)
Example
# List every object in the loaded scenes, active or not.
elements = alt_driver.get_all_elements(enabled=False)
for element in elements:
print(element.name)
${elements}= Get All Elements camera_by='NAME' camera_value='' enabled=True
Example
# List every object in the loaded scenes, active or not.
${elements}= Get All Elements enabled=${False}
FOR ${element} IN @{elements}
${name}= Get Object Name ${element}
Log ${name}
END
Parameters
Name |
Type |
Default |
Description |
|---|---|---|---|
|
C#, Java, Python: |
|
How to find the camera that works out the objects’ screen positions ( |
|
|
|
The camera to use, matched with |
|
|
|
|
Returns
List<AltObject> (C#), AltObject[] (Java), list of AltObject (Python, Robot): Every object found, or an empty list.
Note
It is the same as FindObjects with the path //*. To get only some objects, use FindObjects with a selector.
See also: FindObjects
Wait#
Commands that wait until an object appears or disappears. They look for the object every interval seconds, and fail with WaitTimeOutException when timeout runs out. See Errors.
The default timeout is 20 seconds (the DEFAULT_WAIT of the Robot Framework
library). If you set an implicit timeout with
SetImplicitTimeout, the waits use it in place of
that default.
In Java, these commands take an AltWaitForObjectsParams, which wraps the
AltFindObjectsParams of the object to wait for:
new AltWaitForObjectsParams.Builder(AltFindObjectsParams altFindObjectsParams)
.withTimeout(double timeout) // default 20
.withInterval(double interval) // default 0.5
.build()
WaitForObject#
Waits until an object that matches a selector exists, and returns it. Fails with WaitTimeOutException if none appears within timeout seconds.
AltObject WaitForObject(
By by,
string value,
By cameraBy = By.NAME,
string cameraValue = "",
bool enabled = true,
double timeout = 20,
double interval = 0.5)
Example
// Wait up to 30 seconds for the main menu to load, then tap Play.
var playButton = altDriver.WaitForObject(By.NAME, "PlayButton", timeout: 30);
playButton.Tap();
AltObject waitForObject(AltWaitForObjectsParams params)
Example
// Wait up to 30 seconds for the main menu to load, then tap Play.
AltFindObjectsParams play =
new AltFindObjectsParams.Builder(AltDriver.By.NAME, "PlayButton").build();
AltObject playButton = altDriver.waitForObject(
new AltWaitForObjectsParams.Builder(play).withTimeout(30).build());
playButton.tap();
alt_driver.wait_for_object(
by,
value,
camera_by=By.NAME,
camera_value='',
timeout=20,
interval=0.5,
enabled=True)
Example
# Wait up to 30 seconds for the main menu to load, then tap Play.
play_button = alt_driver.wait_for_object(By.NAME, "PlayButton", timeout=30)
play_button.tap()
${alt_object}= Wait For Object locator_strategy locator camera_by='NAME' camera_value='' timeout=DEFAULT_WAIT interval=0.5 enabled=True
Example
# Wait up to 30 seconds for the main menu to load, then tap Play.
${play_button}= Wait For Object NAME PlayButton timeout=30
Tap Object ${play_button}
Parameters
Name |
Type |
Default |
Description |
|---|---|---|---|
|
C#, Java, Python: |
required |
What to match the value against: name, path, tag, layer, component, text or id. See By selector. |
|
|
required |
The value to look for, such as the object’s name or path. |
|
C#, Java, Python: |
|
How to find the camera that works out the objects’ screen positions ( |
|
|
|
The camera to use, matched with |
|
|
|
|
|
C#, Java: |
|
Seconds to wait before failing with |
|
C#, Java: |
|
Seconds between two searches. Keep it smaller than |
Returns
AltObject: The first object that matches, once it exists.
Note
In Python and Robot Framework, timeout and interval come before enabled, so pass enabled by name.
See also: WaitForObjectWhichContains · WaitForObjectNotBePresent · FindObject
WaitForObjectWhichContains#
Waits until an object whose name, tag, layer, component, text or id contains the value exists, and returns it. Fails with WaitTimeOutException if none appears within timeout seconds.
AltObject WaitForObjectWhichContains(
By by,
string value,
By cameraBy = By.NAME,
string cameraValue = "",
bool enabled = true,
double timeout = 20,
double interval = 0.5)
Example
// Wait for the end-of-level message, such as "Victory!" or "Victory in 3 moves".
var message = altDriver.WaitForObjectWhichContains(By.TEXT, "Victory");
string text = message.GetText();
AltObject waitForObjectWhichContains(AltWaitForObjectsParams params)
Example
// Wait for the end-of-level message, such as "Victory!" or "Victory in 3 moves".
AltFindObjectsParams victory =
new AltFindObjectsParams.Builder(AltDriver.By.TEXT, "Victory").build();
AltObject message = altDriver.waitForObjectWhichContains(
new AltWaitForObjectsParams.Builder(victory).build());
String text = message.getText();
alt_driver.wait_for_object_which_contains(
by,
value,
camera_by=By.NAME,
camera_value='',
timeout=20,
interval=0.5,
enabled=True)
Example
# Wait for the end-of-level message, such as "Victory!" or "Victory in 3 moves".
message = alt_driver.wait_for_object_which_contains(By.TEXT, "Victory")
text = message.get_text()
${alt_object}= Wait For Object Which Contains locator_strategy locator camera_by='NAME' camera_value='' timeout=DEFAULT_WAIT interval=0.5 enabled=True
Example
# Wait for the end-of-level message, such as "Victory!" or "Victory in 3 moves".
${message}= Wait For Object Which Contains TEXT Victory
${text}= Get Text ${message}
Parameters
Name |
Type |
Default |
Description |
|---|---|---|---|
|
C#, Java, Python: |
required |
What to match the value against: name, path, tag, layer, component, text or id. See By selector. |
|
|
required |
The text that the object’s name, tag, layer, component, text or id contains. |
|
C#, Java, Python: |
|
How to find the camera that works out the objects’ screen positions ( |
|
|
|
The camera to use, matched with |
|
|
|
|
|
C#, Java: |
|
Seconds to wait before failing with |
|
C#, Java: |
|
Seconds between two searches. Keep it smaller than |
Returns
AltObject: The first object that matches, once it exists.
Note
With By.PATH, the value is used as a path, as in WaitForObject.
In Python and Robot Framework, timeout and interval come before enabled, so pass enabled by name.
See also: WaitForObject · FindObjectWhichContains
WaitForObjectNotBePresent#
Waits until no object matches a selector, for example until a loading screen closes. Fails with WaitTimeOutException if one still matches after timeout seconds.
void WaitForObjectNotBePresent(
By by,
string value,
By cameraBy = By.NAME,
string cameraValue = "",
bool enabled = true,
double timeout = 20,
double interval = 0.5)
Example
// Wait up to a minute for the loading screen to close, then tap Play.
altDriver.WaitForObjectNotBePresent(By.NAME, "LoadingScreen", timeout: 60);
altDriver.FindObject(By.NAME, "PlayButton").Tap();
void waitForObjectToNotBePresent(AltWaitForObjectsParams params)
Example
// Wait up to a minute for the loading screen to close, then tap Play.
AltFindObjectsParams loading =
new AltFindObjectsParams.Builder(AltDriver.By.NAME, "LoadingScreen").build();
altDriver.waitForObjectToNotBePresent(
new AltWaitForObjectsParams.Builder(loading).withTimeout(60).build());
altDriver.findObject(
new AltFindObjectsParams.Builder(AltDriver.By.NAME, "PlayButton").build()).tap();
alt_driver.wait_for_object_to_not_be_present(
by,
value,
camera_by=By.NAME,
camera_value='',
timeout=20,
interval=0.5,
enabled=True)
Example
# Wait up to a minute for the loading screen to close, then tap Play.
alt_driver.wait_for_object_to_not_be_present(By.NAME, "LoadingScreen", timeout=60)
alt_driver.find_object(By.NAME, "PlayButton").tap()
Wait For Object To Not Be Present locator_strategy locator camera_by='NAME' camera_value='' timeout=DEFAULT_WAIT interval=0.5 enabled=True
Example
# Wait up to a minute for the loading screen to close, then tap Play.
Wait For Object To Not Be Present NAME LoadingScreen timeout=60
${play_button}= Find Object NAME PlayButton
Tap Object ${play_button}
Parameters
Name |
Type |
Default |
Description |
|---|---|---|---|
|
C#, Java, Python: |
required |
What to match the value against: name, path, tag, layer, component, text or id. See By selector. |
|
|
required |
The value to look for, such as the object’s name or path. |
|
C#, Java, Python: |
|
How to find the camera that works out the objects’ screen positions ( |
|
|
|
The camera to use, matched with |
|
|
|
|
|
C#, Java: |
|
Seconds to wait before failing with |
|
C#, Java: |
|
Seconds between two searches. Keep it smaller than |
Returns
Nothing.
Note
It returns as soon as no object matches, so it also passes when the object never existed. To be sure the object came and went, wait for it with WaitForObject first.
In Python and Robot Framework, timeout and interval come before enabled, so pass enabled by name.
See also: WaitForObject