Headless prototypes¶
Headless mode lets the prototype tool run with no Android device, emulator or iOS simulator, for
example in CI, a container or a Linux sandbox. AutoMobile holds the prototype in memory on a
virtual device and you read it as a web page.
Turn it on¶
Start AutoMobile with --headless, or set AUTOMOBILE_HEADLESS=1 in its environment. Restart a
daemon that is already running so it picks the mode up. Headless mode is never chosen
automatically.
What works¶
show,patch,dismiss,status,inspectandawaitEventtake the same arguments as on a device.tapOnandsendKeysact on the shown prototype (see Events).- Mock backends (
defineBackend,mock,mockPath),screenMap,shareand test sessions. - The accessibility findings a successful
showorpatchreturns. automobile:prototype/<id>/webreturns the prototype as one HTML page in a device frame (see Prototype web preview), andautomobile:prototype/native?id=<id>returns the files that embed it in an app.
Every result includes virtualDevice:
| Field | Meaning |
|---|---|
deviceId |
automobile-virtual-prototype. |
renderer |
web: the prototype is drawn only by the web page, not on a screen. |
unsupportedCapabilities |
Device features the virtual device cannot emulate (see below). |
What is refused¶
save,listSaved,deleteSaved,open,clearStorage,simulate,installApp,listAppsanduninstallAppfail with “needs a real device”.displayfails: there is one display.- A spec that needs a capability in
unsupportedCapabilitiesfails with the same error an older device gives. Examples:window.persistence: "device"orwindow.layer: "app"(prototype_window_options_v1), element anchors,appearance: "light"/"dark", blur backdrops, custom shaders, dead taps,via: "device"requests, platform modules such as haptics and clipboard, storage and timers. Remove the feature, or run on a device.
Without window.chrome, a show reports chrome: "bar", as on a device without
prototype_window_chrome_v1.
Events¶
tapOn and sendKeys act on the shown prototype, so awaitEvent returns their events as it does
on a device.
tapOntakes atext,textAny,elementIdortestTagselector (elementIdandtestTagmatch a node’sidortestTag). It taps the first visible node that matches. Hidden nodes, closed dialogs and sheets, other pager pages and stack screens below the top cannot be tapped. While a dialog, bottom sheet, drawer or menu is open, only its own nodes can be tapped.- A tap on a node goes to the nearest enclosing node that handles taps. Switches, checkboxes and chips toggle their state key. So does a list item with a trailing switch or checkbox. A dialog’s confirm and dismiss buttons and a snackbar’s action close it. Tab bar and bottom nav items select their tab.
- Text selectors match what the device shows:
{key}placeholders filled from state, and a text field’s current value. A search bar’s results can be tapped only while it is expanded. sendKeyswithtypeandclearcommands writes to thetextFieldorsearchBarthat atapOnfocused, or that itsselectornames. The field’s currentmaxLengthis applied, as on a device. Aselectorthat names anything other than a text field fails without tapping it. Typing fails once the focused field is hidden or disabled; focus it again.- A tap whose state write the prototype would reject, such as a number into a text field’s key, fails and nothing changes.
- The result lists
events(sequence,kind,name) andvirtualDevice.handled: falsemeans the tap reached nothing that handles it, or the control is disabled.
These actions run on a tap: emit (context from state, page, data or value),
setState, toggle, increment, decrement, setPage, push, pop, popToRoot, replace,
dismiss and hideKeyboard. An emit context over 4096 bytes is cut and flagged
contextTruncated, as on a device. A tap whose actions include anything else fails with “cannot run”,
and nothing changes. That includes request, data actions, platform, timers, emit with
requireValid, and stacks with routes or route params. Run those on a device.
Not supported in headless mode:
tapOnwithsibling,container,index,subtext,ensureChecked,display, a non-defaultselectionStrategy, anaccessibilityLinkselector, or anactionother than tap (a positivedurationmeanslongPress).sendKeyswith a non-defaultselectionStrategy.layer: "app"ontapOnor asendKeysselector: there is no app below the prototype. Omitlayeror passlayer: "prototype".visibleWhenorenabledWhenconditions ondata,platformorvalidaround the target: the input fails with “cannot decide”. Run it on a device.sendKeyskeycommands.- Nodes inside
repeattemplates. tapAtand screenshots: there is no rendered layout to tap or capture. Readautomobile:prototype/<id>/webto see the page.
Taps in the web page itself change only the page.