Ultron Extension

Ultron leverages the power of Kotlin extension functions.

You can extend the framework by using its native approach along with your custom operations.

Compose

To enhance the Compose part of the framework, follow these steps:

• Create an extension method for UltronComposeSemanticsNodeInteraction. This method should encapsulate the logic of the operation.
• Create SemanticsMatcher extension method to invoke the method with the operation logic.

Two methods facilitate this process:

• perform: This evaluates the operation and returns updated UltronComposeSemanticsNodeInteraction object.

fun UltronComposeSemanticsNodeInteraction.hasAnyChildren() = perform {
    Assert.assertTrue("SemanticsNode has any children", it.fetchSemanticsNode().children.isNotEmpty())
}

fun SemanticsMatcher.hasAnyChildren() = UltronComposeSemanticsNodeInteraction(this).hasAnyChildren()

• execute: This evaluates the operation and returns the operation's result.

fun UltronComposeSemanticsNodeInteraction.getWidth(): Int = execute {
    it.fetchSemanticsNode().size.width
}

fun SemanticsMatcher.getWidth(): Int = UltronComposeSemanticsNodeInteraction(this).getWidth()

Customize operation info

You can provide additional information to the framework using UltronComposeOperationParams for both the perform and execute methods.

fun UltronComposeSemanticsNodeInteraction.getWidth(): Int = execute(
    UltronComposeOperationParams(
        operationName = "Get width of '${semanticsNodeInteraction.getDescription()}'",
        operationDescription = "Compose get width of '${semanticsNodeInteraction.getDescription()}' during $timeoutMs ms",
        operationType = CustomComposeOperationType.GET_WIDTH
    )
) {
    it.fetchSemanticsNode().size.width
}

Espresso

For Espresso operations, extend UltronEspressoInteraction class. There are 3 methods that help us:

• perform: This evaluates the action and returns an updated UltronEspressoInteraction object.

fun <T> UltronEspressoInteraction<T>.appendText(value: String) = perform { _, view ->
    val textView = (view as TextView)
    textView.text = "${textView.text}$value"
}

• execute: This evaluates the action and returns the result of the operation.

fun <T> UltronEspressoInteraction<T>.getText(): String = execute { _, view ->
    (view as TextView).text.toString()
}

• assertMatches: This evaluates the assertion and returns an updated UltronEspressoInteraction object.

fun <T> UltronEspressoInteraction<T>.assertChecked(expectedState: Boolean) = assertMatches { view ->
    // block returns Boolean defining whether assertion failed or succeded
    (view as CheckBox).isChecked == expectedState
}

To make your custom operation fully native, extend Matcher<View>, ViewInteraction, DataInteraction:

//support action for all Matcher<View>
fun Matcher<View>.appendText(text: String) = UltronEspressoInteraction(onView(this)).appendText(text)

//support action for all ViewInteractions
fun ViewInteraction.appendText(text: String) = UltronEspressoInteraction(this).appendText(text)

//support action for all DataInteractions
fun DataInteraction.appendText(text: String) =  UltronEspressoInteraction(this).appendText(text)

You are able to use this custom operation

withId(R.id.text_input).appendText("some text to append")

Customize action info

You can provide additional information to the framework using UltronEspressoActionParams for both the perform and execute methods.

fun <T> UltronEspressoInteraction<T>.getText(): String = execute(
    UltronEspressoActionParams(
        operationName = "GetText from TextView with '${getInteractionMatcher()}'",
        operationDescription = "${interaction.simpleClassName()} action '${CustomEspressoActionType.GET_TEXT}' of '${getInteractionMatcher()}' with root '${getInteractionRootMatcher()}' during ${getActionTimeout()} ms",
        operationType = CustomEspressoActionType.GET_TEXT,
        viewActionDescription = "getting text from TextView",
        viewActionConstraints = isAssignableFrom(TextView::class.java)
    )
) { _, view ->
    (view as TextView).text.toString()
}

Customize assertion info

You can provide additional information to the framework using UltronEspressoAssertionParams for the assertChecked method.

fun <T> UltronEspressoInteraction<T>.assertChecked(expectedState: Boolean) = assertMatches (
    UltronEspressoAssertionParams(
        operationName = "Assert CheckBox isChecked = '$expectedState'",
        operationDescription = "Assert CheckBox isChecked = '$expectedState' during $timeoutMs ms",
        operationType = EspressoAssertionType.IS_CHECKED,
    )
){ view ->
    (view as CheckBox).isChecked == expectedState
}

Espresso Web

For Espresso Web operations, extend the UltronWebElement class.

// add action on wenView
fun UltronWebElement.appendText(text: String) = apply {
        executeOperation(
            getUltronWebActionOperation (
                webInteractionBlock = {
                    webInteractionBlock().perform(DriverAtoms.webKeys(text))
                },
                name = "WebElement(${locator.type} = '$value') appendText '$text'",
                description = "WebElement(${locator.type} = '$value') appendText '$text' during $timeoutMs ms"
            )
        )
    }

Use it like

id("text_input").appendText("some text")

In case you need to add an assertion, use getUltronWebAssertionOperation() instead of getUltronWebActionOperation()

// add assertion on webView
fun UltronWebElement.appendText(text: String) = apply {
        executeOperation(
            getUltronWebAssertionOperation (...)
        )
    }

UI Automator

For UI Automator operations, extend either UltronUiObject2 or UltronUiObject class.

//actually, UltronUiObject2 already has the same method addText
// this is just an example of how to extend UltronUiObject2
fun UltronUiObject2.appendText(appendText: String) = apply {
        executeAction(
            actionBlock = { uiObject2ProviderBlock()!!.text += appendText },
            name = "AppendText '$appendText' to $selectorDesc",
            description = "UiObject2 action '${UiAutomatorActionType.ADD_TEXT}' $selectorDesc appendText '$appendText' during $timeoutMs ms"
        )
    }

Use this new ability like:

object SomePage : Page<SomePage>() {
    private val search = byResId(R.id.search)  
    fun someUserStep(prefixText: String){
         search.addPrefixText(prefix)
    }
}

The same approach applies to adding custom assertions:

// actually it is not required to create custom  UltronOperationType, but could be useful later
enum class CustomUltronOperations : UltronOperationType {
    ASSERT_HAS_ANY_CHILD
}
// add extension function to UltronUiObject2 that calls `executeAssertion`
fun UltronUiObject2.assertHasAnyChild() = apply {
    executeAssertion(
        assertionBlock = { uiObject2ProviderBlock()!!.childCount > 0 },
        name = "Assert $selectorDesc has any child",
        type = CustomUltronOperations.ASSERT_HAS_ANY_CHILD,
        description = "UiObject2 assertion '${CustomUltronOperations.ASSERT_HAS_ANY_CHILD}' of $selectorDesc during $timeoutMs ms"
    )
}

Use this new ability like:

object SomePage : Page<SomePage>() {
    private val searchResult = byResId(R.id.search_result)
    fun someUserStep(prefixText: String){
        search.addPrefixText(prefix)
        searchResult.assertHasAnyChild()
    }
}