Debugging a failing test#

When a test fails, the question is almost always one of three: is the object there?, is it reachable?, or is the app still answering? AltTester® Desktop can answer all three while the app is running, which is faster than reading a stack trace.

This page is a diagnostic workflow. For what each control does, see the Inspector reference <../reference/inspector.html>_.

Start from the exception#

The exception narrows the search before you open anything.

Exception

Start here

ObjectNotFoundException / WaitTimeOutException

Is the object there? — below.

Object found, but the interaction did nothing

Is it reachable?

CommandResponseTimeoutException

Is the app answering?

NoAppConnected / connection errors

The app never registered. Check the Connected Apps list on the connection screen before anything else.

Is the object there?#

  1. Connect to the app and reproduce the state the test was in when it failed. Setting Time Scale to 0 freezes the game so you can inspect a moment that normally passes too quickly.

  2. Search the Objects Hierarchy using the same strategy your test used — the search box takes By.Name, By.Text, By.Id, By.Tag, By.Layer, By.Component and By.Path, so you can reproduce the selector exactly rather than approximating it.

What you find tells you what to fix:

Result

Diagnosis

Nothing, with the test’s selector

Try a different strategy. If By.NAME finds it but By.PATH did not, the hierarchy moved — see Choosing a selector.

Nothing, with any strategy

You are in the wrong scene, or the object does not exist yet. Check Manage Scenes.

Found, but greyed out or only visible once you enable Show disabled objects in Settings

The object is inactive, or an ancestor is. Finds match only objects active in the hierarchy by default, so a correct selector still returns nothing. Changing the selector will not fix this — the test needs to wait for the object to become active.

Found, and several objects share the name

FindObject returns the first match, which may not be the one you mean. Narrow with By.COMPONENT or scope the search to a parent.

Is it reachable?#

If the object exists but a Click or Tap had no effect, the object is not in the state the interaction needs.

  1. Select the object and read Element Details. World Coordinates and Screen Coordinates tell you where the interaction actually landed — an object positioned off screen still exists and is still found.

  2. Open its components and look at the fields and properties that gate interaction — a button’s interactable, a canvas group’s blocksRaycasts, an animator’s current state.

  3. Turn Live Update on and interact with the game directly. If the same action works by hand but not from the test, the difference is usually timing: the test acted before the object was ready. Wait for the property you just looked at rather than for the object. See Writing reliable tests <../../../sdk/latest/pages/guides/writing-reliable-tests.html>_.

Note

Anything you can read in the Fields or Properties column can be waited on with WaitForComponentProperty. Element Details is, in effect, a catalogue of the conditions available to you.

Is the app answering?#

CommandResponseTimeoutException means the app did not reply at all — this is not a selector problem.

  • Check the status of the app in the Connected Apps list. It reports whether the app is connected and flags problems such as the app not being in the foreground.

  • Confirm the app is not minimised or backgrounded. Some engines stop rendering and servicing commands when the window is not visible.

  • Check whether a previous run left a driver connected. Your license limits concurrent connections, and an abandoned driver occupies one.

  • Lower Max framerate slows every command; if a suite started timing out after someone changed it, that is the cause.

Important

Live Update competes with command execution. If a suite times out only while someone is watching the app in AltTester® Desktop, turn Live Update off — it is not needed for a test run.

Reproducing the selector before you commit it#

The most reliable way to write a selector is not to write it. Find the object in the hierarchy, select it, and read the value straight off Element Details — Name, AltId, Path, and each Component with its Assembly are exactly the values the By strategies take.

The Recorder does the same job for whole interactions: perform the steps by hand and read back the generated commands, which are guaranteed to use selectors that resolved against the running app.

Logs#

If none of the above explains it, the logs will. Open the Support panel using the info icon in the bottom-right corner to reach them; the directory is the one set as Path for AltTester® Related Files in Settings.

Include these when reporting a problem — see Report issues <../project/report-issues.html>_.