KeyInjectionScope

Artifact: androidx.compose.ui:ui-test

View Source

Added in 1.2.0

Common/AllAndroid/JVM

• Cmn

  interface KeyInjectionScope : InjectionScope

---

The receiver scope of the key input injection lambda from performKeyInput.

All sequences and patterns of key input can be expressed using the two fundamental methods of this API - keyDown and keyUp. All other injection functions are provided as abstractions built on top of these two methods in order to improve test code readability/maintainability and decrease development time.

The entire event injection state is shared between all perform.*Input methods, meaning you can continue an unfinished key input sequence in a subsequent invocation of performKeyInput or performMultiModalInput.

All events sent by these methods are batched together and sent as a whole after performKeyInput has executed its code block.

When a key is held down - i.e. the virtual clock is forwarded whilst the key is pressed down, repeat key down events will be sent. In a fashion consistent with Android's implementation, the first repeat key event will be sent after a key has been held down for 500ms. Subsequent repeat events will be sent at 50ms intervals, until the key is released or another key is pressed down.

The sending of repeat key events is handled as an implicit side-effect of advanceEventTime, which is called within the injection scope. As such, no repeat key events will be sent if MainTestClock.advanceTimeBy is used to advance the time.

See also
InjectionScope

Summary

Public functions
Boolean	isKeyDown(key: Key) Checks if the given key is down.	Cmn
Unit	keyDown(key: Key) Sends a key down event for the given key.	Cmn
Unit	keyUp(key: Key) Sends a key up event for the given key.	Cmn

Public properties
Boolean	isCapsLockOn Indicates whether caps lock is on or not.	Cmn
Boolean	isNumLockOn Indicates whether num lock is on or not.	Cmn
Boolean	isScrollLockOn Indicates whether scroll lock is on or not.	Cmn

Extension functions
Unit	KeyInjectionScope.pressKey(key: Key, pressDurationMillis: Long) Holds down the given key for the given pressDurationMillis by sending a key down event, advancing the event time and sending a key up event.	Cmn
Unit	KeyInjectionScope.withKeyDown(key: Key, block: KeyInjectionScope.() -> Unit) Executes the keyboard sequence specified in the given block, whilst holding down the given key.	Cmn
Unit	KeyInjectionScope.withKeyToggled(key: Key, block: KeyInjectionScope.() -> Unit) Executes the keyboard sequence specified in the given block, in between presses to the given key.	Cmn
Unit	KeyInjectionScope.withKeysDown(keys: List<Key>, block: KeyInjectionScope.() -> Unit) Executes the keyboard sequence specified in the given block, whilst holding down the each of the given keys.	Cmn
Unit	KeyInjectionScope.withKeysToggled(keys: List<Key>, block: KeyInjectionScope.() -> Unit) Executes the keyboard sequence specified in the given block, in between presses to the given keys.	Cmn

Extension properties
Boolean	KeyInjectionScope.isAltDown Verifies whether either of the alt keys are down.	Cmn
Boolean	KeyInjectionScope.isCtrlDown Verifies whether either of the control keys are down.	Cmn
Boolean	KeyInjectionScope.isFnDown Verifies whether the function key is down.	Cmn
Boolean	KeyInjectionScope.isMetaDown Verifies whether either of the meta keys are down.	Cmn
Boolean	KeyInjectionScope.isShiftDown Verifies whether either of the shift keys are down.	Cmn

Inherited functions
From androidx.compose.ui.unit.Density open Int Dp.roundToPx() Convert Dp to Int by rounding Cmn open Int TextUnit.roundToPx() Convert Sp to Int by rounding Cmn open Dp Int.toDp() Convert an Int pixel value to Dp. Cmn open Dp Float.toDp() Convert a Float pixel value to a Dp Cmn open DpSize Size.toDpSize() Convert a Size to a DpSize. Cmn open Float Dp.toPx() Convert Dp to pixels. Cmn open Float TextUnit.toPx() Convert Sp to pixels. Cmn open Rect DpRect.toRect() Convert a DpRect to a Rect. Cmn open Size DpSize.toSize() Convert a DpSize to a Size. Cmn open TextUnit Int.toSp() Convert an Int pixel value to Sp. Cmn open TextUnit Float.toSp() Convert a Float pixel value to a Sp Cmn
From androidx.compose.ui.unit.FontScaling open Dp TextUnit.toDp() Convert Sp to Dp. Cmn open TextUnit Dp.toSp() Convert Dp to Sp. Cmn
From androidx.compose.ui.test.InjectionScope Unit advanceEventTime(durationMillis: Long) Adds the given durationMillis to the current event time, delaying the next event by that time. Cmn open Offset percentOffset(x: Float, y: Float) Creates an Offset relative to the size of the node we're interacting with. Cmn

Inherited properties
From androidx.compose.ui.unit.Density Float density The logical density of the display. Cmn
From androidx.compose.ui.unit.FontScaling Float fontScale Current user preference for the scaling factor for fonts. Cmn
From androidx.compose.ui.test.InjectionScope open Float bottom The y-coordinate for the bottom of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Offset bottomCenter The center of the bottom edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Offset bottomLeft The bottom left corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Offset bottomRight The bottom right corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Offset center The center of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Offset centerLeft The center of the left edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Offset centerRight The center of the right edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Float centerX The x-coordinate for the center of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Float centerY The y-coordinate for the center of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Long eventPeriodMillis The default time between two successive events. Cmn open Int height The height of the node in px. Cmn open Float left The x-coordinate for the left edge of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Float right The x-coordinate for the right edge of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Float top The y-coordinate for the bottom of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Offset topCenter The center of the top edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Offset topLeft The top left corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn open Offset topRight The top right corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Cmn ViewConfiguration viewConfiguration The ViewConfiguration in use by the SemanticsNode from the SemanticsNodeInteraction on which the input injection method is called. Cmn IntSize visibleSize The size of the visible part of the node we're interacting with in px, i.e. its clipped bounds. Cmn open Int width The width of the node in px. Cmn

Public functions

isKeyDown

Cmn

fun isKeyDown(key: Key): Boolean

Checks if the given key is down.

Parameters
key: Key	The key to be checked.

Returns
Boolean	true if the given key is pressed down, false otherwise.

keyDown

Cmn

fun keyDown(key: Key): Unit

Sends a key down event for the given key.

If the given key is already down, an IllegalStateException will be thrown.

Parameters
key: Key	The key to be pressed down.

keyUp

Cmn

fun keyUp(key: Key): Unit

Sends a key up event for the given key.

If the given key is already up, an IllegalStateException will be thrown.

Parameters
key: Key	The key to be released.

Public properties

isCapsLockOn

Cmn

Added in 1.2.0

val isCapsLockOn: Boolean

Indicates whether caps lock is on or not.

Note that this reflects the state of the injected input only, it does not correspond to the state of an actual keyboard attached to the device on which a test is run

isNumLockOn

Cmn

Added in 1.2.0

val isNumLockOn: Boolean

Indicates whether num lock is on or not.

Note that this reflects the state of the injected input only, it does not correspond to the state of an actual keyboard attached to the device on which a test is run

isScrollLockOn

Cmn

Added in 1.2.0

val isScrollLockOn: Boolean

Indicates whether scroll lock is on or not.

Note that this reflects the state of the injected input only, it does not correspond to the state of an actual keyboard attached to the device on which a test is run

Extension functions

pressKey

Cmn

Artifact: androidx.compose.ui:ui-test

View Source

fun KeyInjectionScope.pressKey(
    key: Key,
    pressDurationMillis: Long = DefaultKeyPressDurationMillis
): Unit

Holds down the given key for the given pressDurationMillis by sending a key down event, advancing the event time and sending a key up event.

If the given key is already down, an IllegalStateException will be thrown.

Parameters
key: Key	The key to be pressed down.
pressDurationMillis: Long = DefaultKeyPressDurationMillis	Duration of press in milliseconds.

withKeyDown

Cmn

Artifact: androidx.compose.ui:ui-test

View Source

fun KeyInjectionScope.withKeyDown(key: Key, block: KeyInjectionScope.() -> Unit): Unit

Executes the keyboard sequence specified in the given block, whilst holding down the given key. This key must not be used within the block.

If the given key is already down, an IllegalStateException will be thrown.

Parameters
key: Key	The key to be held down during injection of the block.
block: KeyInjectionScope.() -> Unit	Sequence of KeyInjectionScope methods to be injected with the given key down.

withKeyToggled

Cmn

Artifact: androidx.compose.ui:ui-test

View Source

fun KeyInjectionScope.withKeyToggled(key: Key, block: KeyInjectionScope.() -> Unit): Unit

Executes the keyboard sequence specified in the given block, in between presses to the given key. This key can also be used within the block, as long as it is not down at the end of the block.

If the given key is already down, an IllegalStateException will be thrown.

Parameters
key: Key	The key to be toggled around the injection of the block.
block: KeyInjectionScope.() -> Unit	Sequence of KeyInjectionScope methods to be injected with the given key down.

withKeysDown

Cmn

Artifact: androidx.compose.ui:ui-test

View Source

fun KeyInjectionScope.withKeysDown(keys: List<Key>, block: KeyInjectionScope.() -> Unit): Unit

Executes the keyboard sequence specified in the given block, whilst holding down the each of the given keys. Each of the keys will be pressed down and released simultaneously. These keys must not be used within the block.

If any of the given keys are already down, an IllegalStateException will be thrown.

Parameters
keys: List<Key>	List of keys to be held down during injection of the block.
block: KeyInjectionScope.() -> Unit	Sequence of KeyInjectionScope methods to be injected with the given keys down.

withKeysToggled

Cmn

Artifact: androidx.compose.ui:ui-test

View Source

fun KeyInjectionScope.withKeysToggled(keys: List<Key>, block: KeyInjectionScope.() -> Unit): Unit

Executes the keyboard sequence specified in the given block, in between presses to the given keys. Each of the keys will be toggled simultaneously.These keys can also be used within the block, as long as they are not down at the end of the block.

If any of the given keys are already down, an IllegalStateException will be thrown.

Parameters
keys: List<Key>	The keys to be toggled around the injection of the block.
block: KeyInjectionScope.() -> Unit	Sequence of KeyInjectionScope methods to be injected with the given keys down.

Extension properties

isAltDown

Cmn

Artifact: androidx.compose.ui:ui-test

View Source

Added in 1.2.0

val KeyInjectionScope.isAltDown: Boolean

Verifies whether either of the alt keys are down.

Returns
Boolean	true if an alt key is currently down, false otherwise.

isCtrlDown

Cmn

Artifact: androidx.compose.ui:ui-test

View Source

Added in 1.2.0

val KeyInjectionScope.isCtrlDown: Boolean

Verifies whether either of the control keys are down.

Returns
Boolean	true if a control key is currently down, false otherwise.

isFnDown

Cmn

Artifact: androidx.compose.ui:ui-test

View Source

Added in 1.2.0

val KeyInjectionScope.isFnDown: Boolean

Verifies whether the function key is down.

Returns
Boolean	true if the function key is currently down, false otherwise.

isMetaDown

Cmn

Artifact: androidx.compose.ui:ui-test

View Source

Added in 1.2.0

val KeyInjectionScope.isMetaDown: Boolean

Verifies whether either of the meta keys are down.

Returns
Boolean	true if a meta key is currently down, false otherwise.

isShiftDown

Cmn

Artifact: androidx.compose.ui:ui-test

View Source

Added in 1.2.0

val KeyInjectionScope.isShiftDown: Boolean

Verifies whether either of the shift keys are down.

Returns
Boolean	true if a shift key is currently down, false otherwise.