Navigation graph¶
AutoMobile can learn which screens an app has and how they connect, then take the device straight to a screen by name. Three tools make up the workflow:
exploredrives the app on its own and records what it finds.getNavigationGraphshows the screens and transitions learned so far.navigateToreplays a learned path to a named screen.
Availability¶
The three tools are listed without --debug, but they are off by default and
need two things:
- The server runs with
--embedded-sdk. Screen names come from navigation events sent by the AutoMobile SDK embedded in the app under test, so an app without the SDK produces an empty or sparse graph. - The tools are enabled for your session. Declare them when you acquire the
device, or later with
setToolEnabled(see Dynamic Tools):
{
"name": "getAndroid",
"arguments": {
"enableTools": ["explore", "getNavigationGraph", "navigateTo"]
}
}
If the tools are missing from tools/list, check that the server was started
with --embedded-sdk and that they appear in the enabledTools of the response.
Platform support¶
| Platform | Support |
|---|---|
| Android | Supported. |
| iOS | Supported through the embedded iOS SDK. |
| tvOS | Not supported. navigateTo rejects tvOS devices. |
Building the graph¶
Launch the app first, then call explore:
{
"name": "explore",
"arguments": { "packageName": "com.example.app", "maxInteractions": 40 }
}
explore taps and swipes through the app until it reaches a limit or runs out
of new things to try. On an Android TV it instead moves D-pad focus to an
element and selects it, and records that as focusNavigate with select: true.
It interacts with the device, so run it on a test device and test account.
It never explores the on-screen keyboard. When a field opens the keyboard over
the app, explore presses back once to hide it, and it skips the keyboard’s
keys if it stays open. It also hides a keyboard its last interaction opened
before it returns. It does not retry an element whose tap or select left the
screen unchanged on that screen.
| Parameter | Default | Meaning |
|---|---|---|
packageName |
none | App to stay inside. It must be installed; if exploration leaves the app, it relaunches it. |
maxInteractions |
200 |
Stop after this many interactions. |
timeoutMs |
300000 |
Stop after this many milliseconds. |
strategy |
weighted |
breadth-first, depth-first, or weighted (scores elements by how likely they lead somewhere new). |
mode |
hybrid |
discover favors new elements, validate re-walks known transitions, hybrid balances both. |
resetToHome |
false |
Periodically press the device home button, then relaunch packageName. |
resetInterval |
15 |
Interactions between resets when resetToHome is on. |
dryRun |
false |
Plan without interacting. Returns inputMode, currentScreen, plannedInteractions, and estimatedCoverage. |
Start with a small maxInteractions and dryRun: true to see what explore
would tap before letting it run.
Result¶
| Field | Meaning |
|---|---|
interactionsPerformed |
Interactions actually made. |
screensDiscovered |
Screens added to the graph by this run. |
edgesAdded |
Transitions added by this run. |
coverage |
totalScreens, exploredScreens, and percentage. |
explorationPath |
Screens visited, in order. |
stopReason |
Why the run ended, such as the interaction or time limit. |
navigationGraph |
The recorded graph of packageName, whose appId names that app. |
graphTraversal |
In validate mode: which known transitions were re-walked and whether each held. |
explore is not the only source of the graph. Taps, swipes, and other
interaction tools you call yourself also record transitions while the tools are
enabled, so walking a flow by hand teaches the graph that flow.
Inspecting the graph¶
{ "name": "getNavigationGraph", "arguments": { "appId": "com.example.app" } }
Without appId, the graph of the device’s current foreground app is returned.
Pass appId whenever you know it, so a system screen in the foreground does not
redirect the read. This tool only reads and never touches the device.
| Field | Meaning |
|---|---|
requestedAppId, observedAppId |
The app you asked for and the app seen in the foreground. |
currentScreen |
The screen the graph believes the app is on, or null. |
nodeCount, edgeCount |
Screens and transitions in the graph. |
knownEdges, unknownEdges |
Transitions with and without a recorded action. A transition without one is replayed only as Back, when its destination was recorded at a shallower back-stack depth than its source; otherwise it is skipped. |
screens |
Each screen’s name, visitCount, and lastVisited. |
transitions |
Each transition’s from, to, type (tool, back, unknown), and the tool and args that caused it. |
Use the names in screens as navigateTo targets.
getNavigationGraph can also compare the graph with a prototype spec
(prototypeSpec or prototypeSpecPath, optionally with screenMapping or
screenMappingPath). The result adds prototypeDiff, listing matched screens,
prototype screens and transitions the app lacks, and app screens the prototype
lacks.
Labeling builds with their git revision¶
The graph records which app build reached each screen. By default it labels a
build v<versionCode> (<hash prefix>). To show branch@shortsha instead
(for example main@3f2a9c1), declare the git branch and full commit sha the app
came from. Builds that declare nothing keep the default label, and the
declaration never changes which builds AutoMobile tells apart.
On Android, add both values as manifest meta-data, typically filled from your Gradle build:
<application>
<meta-data android:name="dev.jasonpearson.automobile.build.gitBranch"
android:value="${gitBranch}" />
<meta-data android:name="dev.jasonpearson.automobile.build.gitSha"
android:value="${gitSha}" />
</application>
android {
defaultConfig {
manifestPlaceholders["gitBranch"] = providers.exec {
commandLine("git", "rev-parse", "--abbrev-ref", "HEAD")
}.standardOutput.asText.get().trim()
manifestPlaceholders["gitSha"] = providers.exec {
commandLine("git", "rev-parse", "HEAD")
}.standardOutput.asText.get().trim()
}
}
In a detached checkout, which is common on CI, git rev-parse --abbrev-ref HEAD
prints HEAD, so the build would be labeled HEAD@<sha>. On CI, take the branch
from the CI environment instead (for example GITHUB_HEAD_REF, or
GITHUB_REF_NAME on GitHub Actions), and leave both values out when no branch
is known.
On iOS, add the same two keys as strings to the app’s Info.plist, for example
from a build phase that runs git rev-parse. AutoMobile labels iOS builds on
simulators only.
Declare both values. The branch must be 1–255 characters and the sha 7–64 hexadecimal characters. Use a full 40-character sha: Android reads an all-digit short sha as a number and ignores it. AutoMobile ignores an invalid pair.
The label takes effect the next time AutoMobile observes the app after you install it. Rebuilding the same version and content from a later commit updates the label.
Going to a screen¶
{ "name": "navigateTo", "arguments": { "targetScreen": "Settings" } }
navigateTo finds the shortest known path from the current screen and replays
the recorded action for each step, checking that each step lands on the
expected screen. Steps explore recorded on an Android TV replay as the same D-pad
focus moves and select.
| Field | Meaning |
|---|---|
success |
true only when the device ended on targetScreen. |
currentScreen |
Where the device is now. |
stepsExecuted |
Steps replayed. |
path |
Steps taken on a completed replay. |
partialPath |
Steps taken before a replay stopped early. |
error |
Why navigation failed. Failed calls are also marked as tool errors. |
If the device is already on the target, the call succeeds with
"Already on target screen" and no steps.
Through one transition¶
{
"name": "navigateTo",
"arguments": {
"targetScreen": "Settings",
"viaTransition": { "from": "Home", "to": "Settings", "toolName": "tapOn" }
}
}
viaTransition makes the last step exactly that recorded transition. The call
first goes to from by any known path, then replays only that transition, even
when other transitions also join the two screens. to must equal
targetScreen. Pick the transition by toolName (null for a Back
transition) or by a getNavigationGraph edge edgeId; with neither, any
transition from from to to qualifies. A pinned call never tries another
transition: if the transition is missing or its replay does not land on to,
success is false and currentScreen says where the device stopped.
Limits¶
- A path is only as good as its recorded actions. Changed UI, dynamic content, feature flags, or a different login state can break a step that worked before.
- Transitions are one-way. Learning
Home→Settingsdoes not teachSettings→Homeunless that direction was also recorded. - Cold-starting or clearing an app’s data makes the graph forget which screen that app was on, so the next action does not create a false transition.
- The graph is saved per app and kept across server restarts. Stale transitions stay until a later run corrects them.
Errors and what to do¶
| Error | What to do |
|---|---|
Package not installed: <app> |
Install the app, then call explore again. |
Could not confirm that <app> is installed |
The installed-app listing was incomplete. Retry. |
Cannot determine current screen. No navigation events recorded yet. |
Interact with the app once (or run explore), and confirm the app embeds the SDK and the server runs with --embedded-sdk. |
No known path from "A" to "B". Known screens: ... |
Check the target name against the list. If it is right, walk from A to B once by hand or run explore from A to record a path. A note about ignored transitions means some edges had no recorded action. |
Failed to execute step N: ... or Navigation did not reach "B"; currently on "C" |
A recorded step no longer works. Call observe, recover to a known screen, and run explore with mode: "validate" to refresh the graph. |
Not trying a fallback edge: ... no longer confirmed on "A" |
A dialog or other app is in the way. Dismiss it, then call navigateTo again. |
No replayable recorded transition ... or Transition N (...) is not in the navigation graph |
The pinned transition is not recorded for this app. Call getNavigationGraph and pick a listed edge. |
Navigation timeout (30 seconds) |
The replay took too long. Check partialPath and currentScreen, then retry from there. |
stopReason starts with Left target app |
Exploration kept leaving the app (for example, through an external link) and could not get back. Check the app opens with launchApp, then run again with a lower maxInteractions. |