Ultron UI Testing Framework

RuleSequence is a replacement for JUnit 4's RuleChain that provides flexible control over the order in which rules are executed. It is designed to work well with class inheritance, allowing you to define a base sequence in a BaseTest class and extend it in subclasses.

Rules are categorized into three priority lists:

• first: Executed before all other rules.
• normal: The default list for rules.
• last: Executed after all other rules.

When using RuleSequence, you only need to annotate the RuleSequence instance itself with @get:Rule. Other rules added to the sequence do not require the @get:Rule annotation.

abstract class BaseTest {
    val setupRule = SetUpRule(name = "some name").add {
        // precondition for all tests
    }

    @get:Rule
    open val ruleSequence = RuleSequence(setupRule)
}

class DemoTest : BaseTest() {
    private val activityRule = ActivityScenarioRule(MainActivity::class.java)

    init {
        // Add rules to the sequence in the init block of subclasses
        ruleSequence.addLast(activityRule)
    }
}

Extend the UltronTest base class to define common preconditions and postconditions for your test suite. This allows you to automate setup and teardown logic across multiple tests.

Lifecycle Hooks

• beforeFirstTest: Executed once before any tests in the class run.
• beforeTest: Executed before every individual test method.
• afterTest: Executed after every individual test method.

The test method

Use the test method to wrap your test logic. It provides:

• Isolation: Automatically recreates the UltronTestContext for each test.
• Assertion Safety: Clears previous softAssertion exceptions at the start of each test.
• Suppression: You can bypass the common lifecycle hooks using suppressCommonBefore = true and suppressCommonAfter = true within the test function arguments.

class SampleUltronFlowTest : UltronTest() {

    @OptIn(ExperimentalUltronApi::class)
    override val beforeFirstTest = {
        UltronLog.info("Before Class")
    }

    override val beforeTest = {
        UltronLog.info("Before test common")
    }

    override val afterTest = {
        UltronLog.info("After test common")
    }

    @Test
    fun someTest1() = test {
        // Test logic here
    }

    @Test
    fun someTest2() = test(
        suppressCommonBefore = true,
        suppressCommonAfter = true
    ) {
        // This test will NOT run beforeTest or afterTest
    }
}

When testing Compose Multiplatform UI components, you can choose between the standard Compose Testing framework and Ultron.

• runComposeUiTest: The standard method provided by the Compose Testing framework. It requires using onNode(...) to target elements and provides a SemanticsNodeInteractionProvider context that must be manually passed around if you want to use Page Objects.
• runUltronUiTest: An Ultron-provided alternative that simplifies interaction syntax by removing the need for onNode(...) wrappers (e.g., using hasTestTag(...).click() directly). It also improves interaction reliability and stability. Crucially, it allows you to call interactions from anywhere, including Page Objects, without manually passing a provider.

// Standard Compose approach
runComposeUiTest {
    setContent { /* UI */ }
    onNode(hasTestTag("text")).assertTextEquals("Hello")
}

// Ultron approach
runUltronUiTest {
    setContent { /* UI */ }
    hasTestTag("text").assertTextEquals("Hello")
}

When using withAssertion, be aware that the total time to failure may increase because Ultron may execute the operation and the assertion block multiple times to verify the failure.

To prevent tests from hanging, you can control timeouts at two levels:

1. Assertion Timeout: Use withTimeout(long) inside the assertion block to restrict how long a specific check (like isDisplayed()) should wait.
2. Operation Timeout: Use withTimeout(long) on the main object to extend the timeout of the primary operation being performed.

You can combine both to have a long-running operation with a strict, short-lived assertion check.

// Restrict the assertion check to 3 seconds
button.withAssertion {
    title.withTimeout(3_000L).isDisplayed()
}.click()

// Extend the main operation to 10 seconds, but keep the assertion check at 2 seconds
button.withTimeout(10_000L).withAssertion {
    title.withTimeout(2_000L).isDisplayed()
}.click()