Keys, screen and rotation¶
Examples are in Python
Kotlin has the same methods in camelCase (press_back → pressBack, set_orientation →
setOrientation). Kotlin + JUnit 5 shows this
page's examples in Kotlin.
These are on Device: they act on the device as a whole, not on an element.
Keys¶
| Method | What happens on the device |
|---|---|
press_back(), press_home(), press_key(code) |
a key event (press_key takes an Android key code, such as 66 for Enter) |
type_text(value) |
types into whatever has input focus (Text) |
keyboard_shown() |
whether any soft keyboard is on screen (also info().keyboard_shown) |
hide_keyboard() |
hides it with one Back key. No keyboard: nothing is sent, so Back never reaches the app |
The screen and the lock screen¶
| Method | What happens on the device |
|---|---|
wake(), sleep() |
turn the screen on or off (the WAKEUP / SLEEP keys; nothing happens when it already is). Waking does not dismiss the lock screen |
dismiss_keyguard() |
dismisses a lock screen that has no PIN, pattern or password (none showing: nothing is sent). A secure one fails with ACTION_REJECTED / KEYGUARD_SECURE before any input: Tap never unlocks it |
info() reports screen_on, keyguard_locked and keyguard_secure.
System panels¶
open_notifications() and open_quick_settings() open the notification shade or quick
settings through the system's accessibility action, as a swipe down from the status bar would.
Only whether the system accepted it is reported, so wait for what you need in the panel.
press_back() closes it; from quick settings, Android 14 first goes back to the notification
shade, so press it twice.
Elements in the panel belong to com.android.systemui: reach them with
device.app("com.android.systemui") or device.screen. While a panel is still sliding open or
closed, the system can accept the action and ignore it: app.await_animation_end() before
opening another one.
device.open_quick_settings()
device.screen.wait(desc("Wi-Fi")).visible()
device.press_back()
To read notifications, there is no need to open the shade: see Notifications and toasts.
Clipboard¶
set_clipboard(text) and clipboard() write and read the device clipboard as plain text (an
empty one reads as ""), without moving focus away from the app. On Android 12+ a read shows
the system's "Tap Driver pasted from your clipboard" notice.
Rotation¶
| Method | What happens on the device |
|---|---|
set_orientation(orientation) |
PORTRAIT or LANDSCAPE: chooses the screen geometry and freezes sensor rotation, on portrait-natural phones and landscape-natural tablets alike |
set_display_rotation(rotation) |
NATURAL, LEFT, UPSIDE_DOWN or RIGHT: an exact clockwise rotation relative to the device's natural orientation, frozen |
unfreeze_rotation() |
releases the sensor lock without selecting a new rotation |
from tap_e2e import DisplayRotation, Orientation
device.set_orientation(Orientation.LANDSCAPE)
app.wait(res("two_pane")).visible()
device.set_display_rotation(DisplayRotation.RIGHT)
device.unfreeze_rotation() # optional: detach restores the device's own settings anyway
Rotation calls fail only when Android refuses the rotation (ACTION_REJECTED). They wait up to
two seconds for the display to turn, but an app that locks its own orientation can keep it where
it was without that being an error: assert what you need, for example
info().display_rotation; info().auto_rotate says whether the sensor turns the display (false
while a rotation is frozen).
Before the session's first rotation call, the server captures the device's auto-rotate settings, and detach restores them. A failed restore is a visible detach failure and quarantines the device rather than leaving it changed silently.
Where am I?¶
foreground_activity() returns the activity on top as ForegroundActivity(package_name,
class_name), or None when none is showing (a lock screen): use it to check where a
notification, a deep link or a back press landed. info() returns the rest of the device's
state (Screenshots and artifacts).