Wear OS emulators¶
AutoMobile drives a Wear OS emulator with the same tools it uses on a phone. This guide covers setup, watch-specific behaviour, and what is out of scope.
Note
Verified on a Wear OS 7.0 emulator (API 37 android-wear-signed image, wearos_small_round
profile, 384x384), including sleep/wake and the watch face’s ambient state. Other images, square
watches and physical watches are unverified.
Create the emulator¶
Install a Wear OS system image, then ask for a watch and let AutoMobile create it:
# Use API 34 or newer; API 37 is the verified one.
sdkmanager "system-images;android-37.0;android-wear-signed;arm64-v8a"
{ "platform": "android", "formFactor": "watch", "createIfMissing": true }
Pass that to startDevice. AutoMobile creates the AVD with the round wearos_small_round profile
from an installed image:
- Image tags in order of preference:
android-wear-signed,android-wear,android-wear-cn. - The newest API level in your
minOsVersion/maxOsVersionrange, with an ABI your machine can run.
A phone, tablet or foldable request never gets a Wear image. If no Wear image in the range is
installed, the error names the sdkmanager command to run; AutoMobile downloads nothing. Asking
again reuses the watch instead of creating another.
To pick the screen shape, add requires.screenRound:
{
"platform": "android",
"formFactor": "watch",
"createIfMissing": true,
"requires": { "screenRound": false }
}
truematches only a round profile, andfalseonly a square one. AutoMobile skips an existing watch of the other shape and creates one withwearos_small_roundorwearos_square.- A watch whose profile names no shape never satisfies
screenRound. - Leave it out to accept any watch and create a round one.
- On anything but an Android watch request,
screenRoundfails without creating a device.
You can still create the AVD by hand:
# List device profiles and pick one.
avdmanager list device | grep -i wear
avdmanager create avd \
--name wear-37-round \
--package "system-images;android-37.0;android-wear-signed;arm64-v8a" \
--device wearos_small_round
emulator -avd wear-37-round
Image and profile ids vary by SDK version and host architecture (use x86_64 on an Intel host).
Take them from sdkmanager --list and avdmanager list device.
AutoMobile classifies the emulator as watch from the system-image tag (android-wear) or a
wear_/wearos_ profile id. The device description then shows formFactor: "watch", and a device
requires clause can ask for it. The device resources also report traits.formFactor: "watch" when
the build announces it in ro.build.characteristics.
What to expect¶
Tools that need only adb and the accessibility tree work unchanged. On the verified emulator:
| Tool | Result |
|---|---|
startDevice, listDevices |
Pass: the emulator is adopted and reported as formFactor: "watch" |
observe |
Pass: view hierarchy, screenshot and isScreenRound |
launchApp, terminateApp, listApps |
Pass |
tapOn, tapAt |
Pass, including rows at the bottom edge of a round screen |
swipeOn, swipeOn with lookFor |
Pass: touch drags scroll watch lists |
pressButton back, home |
Pass (see below) |
rotaryScroll |
Pass (see below) |
performanceTrace |
Pass |
prototype show, dismiss, save |
Pass (see below) |
The screen is small, and a round display cuts off content near the corners. Use swipeOn with
lookFor to scroll until the element is visible, then tapOn to open it. Taps on round watch
lists land, because each row’s centre lies inside the visible circle, edge rows included.
observereportsisScreenRoundon a watch:trueon a round display,falseon a square one, absent when unreadable.observealso reportssurfaceon a watch:tile,watchface,launcherorapp. It is absent when AutoMobile cannot identify the surface, including the notification tray.pressButtonbackacts like the Wear OS swipe from the left edge. It closes the current screen, and repeated presses return to the watch face.pressButtonhomefrom inside an app returns to the watch face. From the watch face it opens the app list, as the platform does.
Scrolling with the crown¶
rotaryScroll scrolls the way the watch crown does, which most watch lists and pickers expect.
Enable it with setToolEnabled (see Dynamic Tools).
{ "name": "rotaryScroll", "arguments": { "delta": 3 } }
delta: crown detents, a whole number from -50 to 50 and not 0. Positive scrolls content down.- The tool tries
input rotaryencoder scroll, then the emulator console, then a vertical swipe. It reads the screen back after each.successistrueonce one of them changed the screen.methodnames it andattemptslists every try. - A list already at its end does not change, so it reports
success: false. - On a device that is not a Wear OS watch, AutoMobile still sends the input. The result carries
warningCode: "not_watch"and awarning. Phones usually ignore rotary input, so useswipeOnthere or run the test on a Wear OS image.
On the verified emulator, input rotaryencoder scroll moves plain and curved lists both ways, and
the console attempt always fails. Check attempts on other images. swipeOn with lookFor still
scrolls with touch swipes on a watch.
Notifications¶
On a watch, systemTray drives the Wear OS notification stream instead of the phone shade. Before
opening the stream, AutoMobile dismisses any alert covering the watch with Back.
openswipes the stream up from the bottom edge and reportsopened: trueonce the stream is on screen.closegoes back and reportsclosed: trueonly after the stream is gone.- Both fail when the screen does not change. When the stream is already in the requested state,
they succeed with
skipped: true.
list and clearAll require notification.appId. find, tap, dismiss, list and clearAll
scroll the stream from its top. AutoMobile scrolls an already-open stream back to the top first and
leaves it open afterwards. If it cannot reach the top within awaitTimeout, the action fails with
notification_not_found instead of scanning from the middle. list instead returns no cards,
flagged as below.
listreturns each card once with its app label,title,body,textsandbounds. Theidisnullandactionsis empty. WithoutawaitTimeoutit scans for up to 30 s, enough for a typical stream.- When a
listscan stops early, it still succeeds with the cards read so far andincomplete: true. ItsincompleteReasonisdeadline(time ran out),page_limit(too many pages) orrewind(the top was out of reach, so no cards). Retry with a largerawaitTimeoutto read the rest. tapopens the card, then tapstapActionLabel(or the card’s title or body) in the expanded card. It scrolls the stream when the action sits below the screen edge. If that text is not a single clickable target, it collapses the card and fails rather than guessing. Retry with an explicittapActionLabel.dismissswipes the card sideways, and taps the X button when the swipe only reveals it (Wear OS 7). It reportsdismissal_unconfirmedunless it confirms the removal. WithappId, one of the app’s active notifications with the card’s title and body must go away. Otherwise one fewer such card must show. Of two identical cards, removing one counts.clearAlltaps the stream’s Clear all only when every active notification belongs toappId. Otherwise, or whentitleorbodynarrows it, it dismisses matching cards one by one.
Inline replies¶
Set notification.replyText on tap to reply inline. The text must be a single word with no
whitespace; AutoMobile rejects multi-word text before typing anything. The reply then:
- Defaults the action label to Keyboard input. An explicit
tapActionLabeloverrides it. - Types the text and commits it with the keyboard’s Space key, so Gboard appends one trailing space.
- Verifies the typed text, taps Send, and restores the stream.
If the text does not land, it retries a few times, then fails without sending. If the keyboard, Space key or Send button is unavailable, re-observe and retry.
Watch face and screen rules¶
The stream opens only from the watch face. Every action that opens it first leaves the app list
(with back) or an app in front (with home). It closes the stream back onto the watch face
afterwards.
- If the watch face does not come back, the action fails without the open gesture. Press the watch’s side button and retry.
- If closing the stream after
dismissorclearAllleaves the app list in front, the action reportsdismissal_unconfirmedwith itsdismissedCount. Pressbackto return to the watch face. - AutoMobile refuses a tap target whose centre falls outside the round display. Scroll it into view.
- Every action captures the configured action screenshot or accessibility audit from the final screen, as on a phone.
Ambient power state¶
Enable ambient with setToolEnabled (see Dynamic Tools), then call:
{ "name": "ambient", "arguments": { "action": "enter" } }
Use action: "exit" to wake the device. On a watch, enter sends KEYCODE_SLEEP and exit sends
KEYCODE_WAKEUP. The tool then reads wakefulness and the watch face’s ambient state once.
The tool runs only on a Wear OS watch. On a phone, tablet, TV or automotive device it returns an
error naming the form factor and changes nothing. When the device does not report its form factor,
AutoMobile accepts a session recorded as a watch and refuses any other. Check formFactor with
listDevices.
| Result field | Value |
|---|---|
ambient |
true or false as the watch face reports it, or "unknown" without watch-face state |
watchFaceVisible |
Whether the watch face is on screen, when ambient is known |
wakefulness |
Awake, Dozing or Asleep, when readable |
reason |
Why the call failed, with success: false |
| Action | Succeeds when | When ambient is "unknown" (does not prove ambient mode) |
|---|---|---|
enter |
ambient is true |
wakefulness is Dozing or Asleep |
exit |
ambient is false and wakefulness is Awake |
wakefulness is Awake |
- If
enterleaves wakefulnessAwake, a stay-awake setting (svc power stayon true) probably keeps the display on. Turn it off and retry. - If
watchFaceVisibleisfalse, an app is in front of the watch face. - For visual proof, take a screenshot after
enter: the watch face renders dimmed in ambient. - Command failures return an error. Check the device connection before retrying.
Tiles, watch faces and complications¶
wearSurface adds, removes and shows tiles, reads and sets watch faces, and fills complication
slots. See Wear OS tiles and watch faces.
Prototypes¶
prototype show renders on a watch with the phone overlay and components, without rotary input.
A successful show on a watch reports screenRound, which explains clipped corner content. On a
round display, AutoMobile insets the dismiss control and non-fullscreen windows into the square
inscribed in the circle, so they stay tappable. On a watch, save with pin: true keeps the save
and reports pinned: "unsupported".
Not supported¶
- Physical watches: only Wear OS emulators are matched and created.
- Listing the tiles in the carousel, and listing complication providers.
- Tapping a notification’s expanded content or action buttons without a clickable label or
notification.replyText(see Notifications). - Hardware wake by tilt or touch, and a paired phone and watch.
- Watch-specific prototype components and round-aware prototype layout.