androidx.xr.compose.testing

Classes

SubspaceSemanticsMatcher

Wrapper for semantics matcher lambdas that allows to build string explaining to the developer what conditions were being tested.
SubspaceSemanticsNodeInteraction

Represents a semantics node and the path to fetch it from the semantics tree.
SubspaceSemanticsNodeInteractionCollection

Represents a collection of semantics nodes and the path to fetch them from the semantics tree.
SubspaceTestContext
SubspaceTestingActivity

Custom test class that should be used for testing SubspaceComposable content.

Top-level functions summary

Unit
@Composable
TestSetup(
    isXrEnabled: Boolean,
    isFullSpace: Boolean,
    runtime: JxrPlatformAdapter,
    content: @Composable Session.() -> Unit
)

A Test environment composable wrapper to support testing elevated components locally
JxrPlatformAdapter

Create a fake JxrPlatformAdapter for testing.
Session
createFakeSession(
    activity: SubspaceTestingActivity,
    runtime: JxrPlatformAdapter
)

Create a fake Session for testing.
SubspaceSemanticsMatcher

Verifies the node's ancestors.
SubspaceSemanticsMatcher

Verifies the node's children.
SubspaceSemanticsMatcher

Verifies the node's descendants.
SubspaceSemanticsMatcher

Verifies the node's siblings.
SubspaceSemanticsMatcher
hasContentDescription(
    value: String,
    substring: Boolean,
    ignoreCase: Boolean
)

Verifies the node's content description.
SubspaceSemanticsMatcher

Verifies the node's parent.
SubspaceSemanticsMatcher
hasTestTag(testTag: String)

Verifies the node's test tag.
SubspaceSemanticsMatcher

Verifies that the node is focusable.
SubspaceSemanticsMatcher

Verifies that the node is focused.
SubspaceSemanticsMatcher

Verifies that the node is not focusable.
SubspaceSemanticsMatcher

Verifies that the node is not focused.
SubspaceSemanticsMatcher

Verifies that the node is the root semantics node.

Extension functions summary

SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has depth that is greater than or equal to expectedMinDepth.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has depth equal to expectedDepth.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has height that is greater than or equal to expectedMinHeight.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has height equal to expectedHeight.
Unit
Dp.assertIsEqualTo(expected: Dp, subject: String, tolerance: Dp)

Asserts that this value is equal to the given expected value.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the left position in the root composable that is equal to the given position.
SubspaceSemanticsNodeInteraction
@CanIgnoreReturnValue
SubspaceSemanticsNodeInteraction.assertPositionInRootIsEqualTo(
    expectedX: Dp,
    expectedY: Dp,
    expectedZ: Dp
)

Asserts that the layout of this node has position in the root composable that is equal to the given position.
SubspaceSemanticsNodeInteraction
@CanIgnoreReturnValue
SubspaceSemanticsNodeInteraction.assertPositionIsEqualTo(
    expectedX: Dp,
    expectedY: Dp,
    expectedZ: Dp
)

Asserts that the layout of this node has position that is equal to the given position.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has rotation in the root composable that is equal to the given rotation.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has rotation that is equal to the given rotation.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the top position in the root composable that is equal to the given position.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has width that is greater than or equal to expectedMinWidth.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has width equal to expectedWidth.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the x position in the root composable that is equal to the given position.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the x position that is equal to the given position.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the y position in the root composable that is equal to the given position.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the y position that is equal to the given position.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the z position in the root composable that is equal to the given position.
SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the z position that is equal to the given position.
Vector3

Returns the position of the node relative to its parent layout node.
Vector3

Returns the position of the node relative to the root node.
Quaternion

Returns the rotation of the node relative to its parent layout node.
Quaternion

Returns the rotation of the node relative to the root node.
DpVolumeSize

Returns the size of the node.
SubspaceSemanticsNodeInteractionCollection

Subspace version of onAllNodes in Compose.
SubspaceSemanticsNodeInteractionCollection

Subspace version of onAllNodesWithTag in Compose.
SubspaceSemanticsNodeInteraction

Subspace version of onNode in Compose.
SubspaceSemanticsNodeInteraction

Subspace version of onNodeWithTag in Compose.
Unit

Analog to AndroidComposeTestRule.setContent for testing SubspaceComposable content.
Unit

Analog to AndroidComposeTestRule.setContent for testing SubspaceComposable content.
Dp

Converts a float to a Dp value.
Dp

Converts an integer to a Dp value.

Top-level functions

TestSetup

@Composable
fun TestSetup(
    isXrEnabled: Boolean = true,
    isFullSpace: Boolean = true,
    runtime: JxrPlatformAdapter = createFakeRuntime(LocalContext.current.getActivity() as SubspaceTestingActivity),
    content: @Composable Session.() -> Unit
): Unit

A Test environment composable wrapper to support testing elevated components locally

TODO(b/370856223) Update documentation

createFakeRuntime

fun createFakeRuntime(activity: SubspaceTestingActivity): JxrPlatformAdapter

Create a fake JxrPlatformAdapter for testing.

TODO(b/370856223) Update documentation to include params

createFakeSession

fun createFakeSession(
    activity: SubspaceTestingActivity,
    runtime: JxrPlatformAdapter = createFakeRuntime(activity)
): Session

Create a fake Session for testing.

TODO(b/370856223) Update documentation to include params

hasAnyAncestor

fun hasAnyAncestor(matcher: SubspaceSemanticsMatcher): SubspaceSemanticsMatcher

Verifies the node's ancestors.

Parameters
matcher: SubspaceSemanticsMatcher

The matcher to use to check the ancestors. Example: For the following tree

|-X
|-A
  |-B
    |-C1
    |-C2

In case of C1, we would check the matcher against A and B.
Returns
SubspaceSemanticsMatcher

true if the node has at least one ancestor that satisfies the given matcher.

hasAnyChild

fun hasAnyChild(matcher: SubspaceSemanticsMatcher): SubspaceSemanticsMatcher

Verifies the node's children.

Parameters
matcher: SubspaceSemanticsMatcher

The matcher to use to check the children.
Returns
SubspaceSemanticsMatcher

true if the node has at least one child that satisfies the given matcher.

hasAnyDescendant

fun hasAnyDescendant(matcher: SubspaceSemanticsMatcher): SubspaceSemanticsMatcher

Verifies the node's descendants.

Parameters
matcher: SubspaceSemanticsMatcher

The matcher to use to check the descendants. Example: For the following tree

|-X
|-A
  |-B
    |-C1
    |-C2

In case of A, we would check the matcher against B, C1 and C2.
Returns
SubspaceSemanticsMatcher

true if the node has at least one descendant that satisfies the given matcher.

hasAnySibling

fun hasAnySibling(matcher: SubspaceSemanticsMatcher): SubspaceSemanticsMatcher

Verifies the node's siblings.

Parameters
matcher: SubspaceSemanticsMatcher

The matcher to use to check the siblings. Sibling is defined as a any other node that shares the same parent.
Returns
SubspaceSemanticsMatcher

true if the node has at least one sibling that satisfies the given matcher.

hasContentDescription

fun hasContentDescription(
    value: String,
    substring: Boolean = false,
    ignoreCase: Boolean = false
): SubspaceSemanticsMatcher

Verifies the node's content description.

Parameters
value: String

Value to match as one of the items in the list of content descriptions.
substring: Boolean = false

Whether to use substring matching.
ignoreCase: Boolean = false

Whether case should be ignored.
Returns
SubspaceSemanticsMatcher

true if the node's content description contains the given value.
See also
ContentDescription

hasParent

fun hasParent(matcher: SubspaceSemanticsMatcher): SubspaceSemanticsMatcher

Verifies the node's parent.

Parameters
matcher: SubspaceSemanticsMatcher

The matcher to use to check the parent.
Returns
SubspaceSemanticsMatcher

true if the node's parent satisfies the given matcher.

hasTestTag

fun hasTestTag(testTag: String): SubspaceSemanticsMatcher

Verifies the node's test tag.

Parameters
testTag: String

Value to match.
Returns
SubspaceSemanticsMatcher

true if the node is annotated by the given test tag.
See also
TestTag

isFocusable

fun isFocusable(): SubspaceSemanticsMatcher

Verifies that the node is focusable.

Returns
SubspaceSemanticsMatcher

matcher that matches the node if it is focusable.
See also
Focused

isFocused

fun isFocused(): SubspaceSemanticsMatcher

Verifies that the node is focused.

Returns
SubspaceSemanticsMatcher

matcher that matches the node if it is focused.
See also
Focused

isNotFocusable

fun isNotFocusable(): SubspaceSemanticsMatcher

Verifies that the node is not focusable.

Returns
SubspaceSemanticsMatcher

matcher that matches the node if it is not focusable.
See also
Focused

isNotFocused

fun isNotFocused(): SubspaceSemanticsMatcher

Verifies that the node is not focused.

Returns
SubspaceSemanticsMatcher

matcher that matches the node if it is not focused.
See also
Focused

isRoot

fun isRoot(): SubspaceSemanticsMatcher

Verifies that the node is the root semantics node.

There is always one root in every node tree, added implicitly by Compose.

Returns
SubspaceSemanticsMatcher

true if the node is the root semantics node.

Extension functions

assertDepthIsAtLeast

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertDepthIsAtLeast(
    expectedMinDepth: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has depth that is greater than or equal to expectedMinDepth.

Parameters
expectedMinDepth: Dp

The minimum depth to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertDepthIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertDepthIsEqualTo(
    expectedDepth: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has depth equal to expectedDepth.

Parameters
expectedDepth: Dp

The depth to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertHeightIsAtLeast

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertHeightIsAtLeast(
    expectedMinHeight: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has height that is greater than or equal to expectedMinHeight.

Parameters
expectedMinHeight: Dp

The minimum height to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertHeightIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertHeightIsEqualTo(
    expectedHeight: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has height equal to expectedHeight.

Parameters
expectedHeight: Dp

The height to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertIsEqualTo

fun Dp.assertIsEqualTo(expected: Dp, subject: String, tolerance: Dp = Dp(.5f)): Unit

Asserts that this value is equal to the given expected value.

Performs the comparison with the given tolerance or the default one if none is provided. It is recommended to use tolerance when comparing positions and size coming from the framework as there can be rounding operation performed by individual layouts so the values can be slightly off from the expected ones.

Parameters
expected: Dp

The expected value to which this one should be equal to.
subject: String

Used in the error message to identify which item this assertion failed on.
tolerance: Dp = Dp(.5f)

The tolerance within which the values should be treated as equal.
Throws
kotlin.AssertionError

if comparison fails.

assertLeftPositionInRootIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertLeftPositionInRootIsEqualTo(
    expectedLeft: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the left position in the root composable that is equal to the given position.

Parameters
expectedLeft: Dp

The left position to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertPositionInRootIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertPositionInRootIsEqualTo(
    expectedX: Dp,
    expectedY: Dp,
    expectedZ: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has position in the root composable that is equal to the given position.

Parameters
expectedX: Dp

The x position to assert.
expectedY: Dp

The y position to assert.
expectedZ: Dp

The z position to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertPositionIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertPositionIsEqualTo(
    expectedX: Dp,
    expectedY: Dp,
    expectedZ: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has position that is equal to the given position.

Parameters
expectedX: Dp

The x position to assert.
expectedY: Dp

The y position to assert.
expectedZ: Dp

The z position to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertRotationInRootIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertRotationInRootIsEqualTo(
    expected: Quaternion
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has rotation in the root composable that is equal to the given rotation.

Parameters
expected: Quaternion

The rotation to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertRotationIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertRotationIsEqualTo(
    expected: Quaternion
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has rotation that is equal to the given rotation.

Parameters
expected: Quaternion

The rotation to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertTopPositionInRootIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertTopPositionInRootIsEqualTo(
    expectedTop: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the top position in the root composable that is equal to the given position.

Parameters
expectedTop: Dp

The top position to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertWidthIsAtLeast

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertWidthIsAtLeast(
    expectedMinWidth: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has width that is greater than or equal to expectedMinWidth.

Parameters
expectedMinWidth: Dp

The minimum width to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertWidthIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertWidthIsEqualTo(
    expectedWidth: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has width equal to expectedWidth.

Parameters
expectedWidth: Dp

The width to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertXPositionInRootIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertXPositionInRootIsEqualTo(
    expectedX: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the x position in the root composable that is equal to the given position.

Parameters
expectedX: Dp

The x position to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertXPositionIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertXPositionIsEqualTo(
    expectedX: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the x position that is equal to the given position.

Parameters
expectedX: Dp

The x position to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertYPositionInRootIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertYPositionInRootIsEqualTo(
    expectedY: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the y position in the root composable that is equal to the given position.

Parameters
expectedY: Dp

The y position to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertYPositionIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertYPositionIsEqualTo(
    expectedY: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the y position that is equal to the given position.

Parameters
expectedY: Dp

The y position to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertZPositionInRootIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertZPositionInRootIsEqualTo(
    expectedZ: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the z position in the root composable that is equal to the given position.

Parameters
expectedZ: Dp

The z position to assert.
Throws
kotlin.AssertionError

if comparison fails.

assertZPositionIsEqualTo

@CanIgnoreReturnValue
fun SubspaceSemanticsNodeInteraction.assertZPositionIsEqualTo(
    expectedZ: Dp
): SubspaceSemanticsNodeInteraction

Asserts that the layout of this node has the z position that is equal to the given position.

Parameters
expectedZ: Dp

The z position to assert.
Throws
kotlin.AssertionError

if comparison fails.

getPosition

fun SubspaceSemanticsNodeInteraction.getPosition(): Vector3

Returns the position of the node relative to its parent layout node.

Additional assertions with custom tolerances may be performed on the individual values.

getPositionInRoot

fun SubspaceSemanticsNodeInteraction.getPositionInRoot(): Vector3

Returns the position of the node relative to the root node.

Additional assertions with custom tolerances may be performed on the individual values.

getRotation

fun SubspaceSemanticsNodeInteraction.getRotation(): Quaternion

Returns the rotation of the node relative to its parent layout node.

Additional assertions with custom tolerances may be performed on the individual values.

getRotationInRoot

fun SubspaceSemanticsNodeInteraction.getRotationInRoot(): Quaternion

Returns the rotation of the node relative to the root node.

Additional assertions with custom tolerances may be performed on the individual values.

getSize

fun SubspaceSemanticsNodeInteraction.getSize(): DpVolumeSize

Returns the size of the node.

Additional assertions with custom tolerances may be performed on the individual values.

onAllSubspaceNodes

fun <Error class: unknown class><<Error class: unknown class>, SubspaceTestingActivity>.onAllSubspaceNodes(
    matcher: SubspaceSemanticsMatcher
): SubspaceSemanticsNodeInteractionCollection

Subspace version of onAllNodes in Compose.

onAllSubspaceNodesWithTag

fun <Error class: unknown class><<Error class: unknown class>, SubspaceTestingActivity>.onAllSubspaceNodesWithTag(
    testTag: String
): SubspaceSemanticsNodeInteractionCollection

Subspace version of onAllNodesWithTag in Compose.

onSubspaceNode

fun <Error class: unknown class><<Error class: unknown class>, SubspaceTestingActivity>.onSubspaceNode(
    matcher: SubspaceSemanticsMatcher
): SubspaceSemanticsNodeInteraction

Subspace version of onNode in Compose.

onSubspaceNodeWithTag

fun <Error class: unknown class><<Error class: unknown class>, SubspaceTestingActivity>.onSubspaceNodeWithTag(
    testTag: String
): SubspaceSemanticsNodeInteraction

Subspace version of onNodeWithTag in Compose.

setSubspaceContent

fun <Error class: unknown class><<Error class: unknown class>, SubspaceTestingActivity>.setSubspaceContent(
    content: @Composable @SubspaceComposable () -> Unit
): Unit

Analog to AndroidComposeTestRule.setContent for testing SubspaceComposable content.

setSubspaceContent

fun <Error class: unknown class><<Error class: unknown class>, SubspaceTestingActivity>.setSubspaceContent(
    uiContent: @Composable () -> Unit,
    content: @Composable @SubspaceComposable () -> Unit
): Unit

Analog to AndroidComposeTestRule.setContent for testing SubspaceComposable content.

toDp

fun Float.toDp(): Dp

Converts a float to a Dp value.

toDp

fun Int.toDp(): Dp

Converts an integer to a Dp value.