Ultron — самый простой фреймворк для разработки UI тестов Android

В большинстве случаев, когда разговор заходит об автоматизации тестирования на android, многие рекомендуют популярный фреймворк kaspresso. А есть ли альтернативы?

Сегодня мы поговорим о таком фреймворке как Ultron для android ui тестирования, что‑то отличное от kaspresso со своим подходом. На просторах интернета мало кто знает об этом фреймворке. Фреймворк базируется на Espresso, UI Automator и Compose UI testing framework, написан Алексеем Тюриным, который неоднократно выступал на Heisenbug. Поэтому было бы неплохо подсветить Ultron на хабре.

Каковы преимущества использования фреймворка?

• Простой синтаксис

• Полный контроль над любым action или assertion

• Архитектурный подход к разработке UI‑тестов

• Механизм подклюения preconditions и postconditions

Давайте рассмотрим данный фреймворк поближе.

Подход к Assertions and Actions

Взглянем на примеры actions и assertions над элементами:

Espresso

onView(withId(R.id.send_button)).check(isDisplayed()).perform(click()) 

Ultron

withId(R.id.send_button).isDisplayed().click() 

Как видно из примера, синтаксис ultron позволяет более лаконично описывать действия над элементами. Названия всех операций Ultron такие же, как у эспрессо. Ultron также предоставляет список дополнительных операций.

Давайте посмотрим как это будет выглядеть с использованием паттерна page object:

object SomePage : Page<SomePage>() {     private val button = withId(R.id.button1)     private val eventStatus = withId(R.id.last_event_status)      fun checkEventStatusText(expectedEventText: String) {          button.click()          eventStatus.hasText(expectedEventText)     } } 

Все выглядит предельно просто и понятно. Вам всего лишь нужно указать матчеры для ваших элементов и вызвать над ними необходимые действия.

Подход к действиям над recycler view

Espresso

onView(withId(R.id.recycler_friends))     .perform(         RecyclerViewActions             .scrollTo<RecyclerView.ViewHolder>(hasDescendant(withText("Janice")))     )     .perform(         RecyclerViewActions             .actionOnItem<RecyclerView.ViewHolder>(                 hasDescendant(withText("Janice")),                 click()             )         ) 

Ultron

withRecyclerView(R.id.recycler_friends)     .item(hasDescendant(withText("Janice")))     .click() 

Ultron предоставляет очень комфортное апи и весь код лаконично умещается в пару строк.
Взглянем на best practice с использованием page object:

object FriendsListPage : Page<FriendsListPage>() {     // param loadTimeout в мс указывает время ожидания загрузки элементов RecyclerView     val recycler = withRecyclerView(R.id.recycler_friends, loadTimeout = 10_000L)      fun someStep(){         recycler.assertEmpty()         recycler.hasContentDescription("Description")     } } 

Апи, которое предоставляет фреймворк для работы с ресайклером:

recycler.item(position = 10, autoScroll = true).click() // найти 10 айтем по позиции и проскроллить до него recycler.item(matcher = hasDescendant(withText("Janice"))).isDisplayed() recycler.firstItem().click() // взять первый айтем ресайклера recycler.lastItem().isCompletelyDisplayed()  // если невозможно указать уникальный матчер для целевого элемента val matcher = hasDescendant(withText("Friend")) recycler.itemMatched(matcher, index = 2).click() // вернуть 3 совпадающий по матчеру элемент начиная с 0 индекса recycler.firstItemMatched(matcher).isDisplayed() recycler.lastItemMatched(matcher).isDisplayed() recycler.getItemsAdapterPositionList(matcher) // вернуть все позиции элементов по матчеру 

Стоит отметить, что вам не нужно беспокоиться о скроллинге до элемента. По умолчанию автоскроллинг к элементам равен true в каждом методе по работе с элементами ресайклера.

Если у вас комплексные айтемы ресайклера (имеют вложенные вью) и вам нужно с ними поработать, то вы можете использовать следующий подход:

object FriendsListPage : Page<FriendsListPage>() {      // задаем матчер для ресайклера     val recycler = withRecyclerView(R.id.recycler_friends)      // создаем функцию для получения айтема ресайклера     fun getListItem(contactName: String): FriendRecyclerItem {         return recycler.getItem(hasDescendant(allOf(withId(R.id.tv_name), withText(contactName))))     }      // создаем класс, который мы подразумеваем как айтем ресайклера withRecyclerView(R.id.recycler_friends)     class FriendRecyclerItem : UltronRecyclerViewItem() {         val avatar by lazy { getChild(withId(R.id.avatar)) }         val name by lazy { getChild(withId(R.id.tv_name)) }         val status by lazy { getChild(withId(R.id.tv_status)) }     }      // используем getListItem(name) для доступа к status     fun assertStatus(name: String, status: String) = apply {         getListItem(name).status.hasText(status).isDisplayed()     } } 

При подходе создания класса как FriendRecyclerItem, мы можем использовать такое апи:

recycler.getItem<FriendRecyclerItem>(position = 10, autoScroll = true).status.hasText("UNAGI") recycler.getItem<FriendRecyclerItem>(matcher = hasDescendant(withText("Janice"))).status.textContains("Oh. My") recycler.getFirstItem<FriendRecyclerItem>().avatar.click() // взять первый ресайклер айтем recycler.getLastItem<FriendRecyclerItem>().isCompletelyDisplayed()  // если невозможно указать уникальный матчер для целевого элемента val matcher = hasDescendant(withText(containsString("Friend"))) recycler.getItemMatched<FriendRecyclerItem>(matcher, index = 2).name.click() // вернуть 3 совпадающий по матчеру элемент начиная с 0 индекса recycler.getFirstItemMatched<FriendRecyclerItem>(matcher).name.hasText("Friend1") recycler.getLastItemMatched<FriendRecyclerItem>(matcher).avatar.isDisplayed() 

Espresso WebView operations

Espresso

onWebView()     .withElement(findElement(Locator.ID, "text_input"))     .perform(webKeys(newTitle))     .withElement(findElement(Locator.ID, "button1"))     .perform(webClick())     .withElement(findElement(Locator.ID, "title"))     .check(webMatches(getText(), containsString(newTitle))) 

Ultron

id("text_input").webKeys(newTitle) id("button1").webClick() id("title").hasText(newTitle) 

Так как работа с вебвью не такой частый кейс, то все возможности фреймворка можно будет глянуть в доке.

UI Automator operations

Espresso

val device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation()) device     .findObject(By.res("com.atiurin.sampleapp:id", "button1"))     .click() 

Ultron

byResId(R.id.button1).click() 

Функционал фреймворка через UI Automator описан тут.

Простые compose operations

Compose framework

composeTestRule.onNode(hasTestTag("Continue")).performClick() composeTestRule.onNodeWithText("Welcome").assertIsDisplayed() 

Ultron

hasTestTag("Continue").click() hasText("Welcome").assertIsDisplayed() 

Взаимодесйтвие с компоузом описано в wiki.

Compose list operations

Compose framework

val itemMatcher = hasText(contact.name) composeRule     .onNodeWithTag(contactsListTestTag)     .performScrollToNode(itemMatcher)     .onChildren()     .filterToOne(itemMatcher)     .assertTextContains(contact.name) 

Ultron

composeList(hasTestTag(contactsListTestTag))     .item(hasText(contact.name))     .assertTextContains(contact.name) 

Работа с LazyColumn/LazyRow описана тут.

Стабильность фреймворка

Чем обусловлена стабильность тестов во фреймворке?
Фреймворк перехватывает список указанных исключений и пытается повторить операцию в течение определенного тайм-аута (по умолчанию 5 секунд).

UltronWrapperException::class.java, UltronException::class.java, PerformException::class.java, NoMatchingViewException::class.java, AssertionFailedError::class.java, RuntimeException::class.java 

Вы можете настроить список обрабатываемых исключений, добавить новые или убрать существующие через UltronConfig, а также поменять дефолтный тайм-аут. Также можно указать пользовательский тайм-аут для любой операции — withTimeout(..) (будет рассмотрен ниже).

Давайте рассмотрим какие есть возможности во фреймворке:

Пользовательский тайм-аут для любой операции

withId(R.id.last_event_status).withTimeout(10_000).isDisplayed() 

Данная фича позволяет установить таймаут, в пределах которого будет производиться action или assertion над элементом (по умолчанию 5 секунд)

Есть 2 подхода к использованию метода withTimeout(..):
Укажите withTimeout(..) в месте объявления элемента и он будет применяться для всех операций с этим элементом

object SomePage : Page<SomePage>() {     private val eventStatus = withId(R.id.last_event_status).withTimeout(10_000) } 

Укажите withTimeout(..) внутри шага, чтобы взаимодействие с элементом длилось на протяжении указанного времени. Это значение тайм-аута будет применено только один раз для одной операции.

object SomePage : Page<SomePage>() {     fun someLongUserStep(expectedEventText: String){          longRequestButton.click()          eventStatus.withTimeout(20_000).hasText(expectedEventText)     } } 

То есть проверка hasText(expectedEventText) над элементом eventStatus будет исполняться 20 секунд, пока она не достигнет успеха. Если в течении 20 секунд операция не увенчается успехом, тест упадет с соответствующей ошибкой.

Boolean operation result

Во фреймворке присутствует метод isSuccess, который позволяет получить результат любой операции в виде boolean значения. В случае false проверка isSuccess может выполняться слишком долго (по умолчанию 5 секунд). Поэтому разумно указать пользовательский тайм-аут для некоторых операций вкупе с функцией isSuccess.

Например:

val isButtonDisplayed = withId(R.id.button).isSuccess { withTimeout(2_000).isDisplayed() } if (isButtonDisplayed) {     // какие-то необходимые проверки и действия } 

Расширение фреймворка своими кастомными ViewActions и ViewAssertions

Под капотом все операции эспрессо Ultron описаны в классе UltronEspressoInteraction. для создания своих кастомных действий и проверок вам просто нужно расширить этот класс, используя функцию расширения kotlin, например.

fun <T> UltronEspressoInteraction<T>.appendText(text: String) = apply {     executeAction(         operationBlock = getInteractionActionBlock(AppendTextAction(text)),         name = "Append text '$text' to ${getInteractionMatcher()}",         description = "${interaction!!::class.simpleName} APPEND_TEXT to ${getInteractionMatcher()} during $timeoutMs ms",     ) 

AppendTextAction — это пользовательский ViewAction

class AppendTextAction(private val value: String) : ViewAction {     override fun getConstraints() = allOf(isDisplayed(), isAssignableFrom(TextView::class.java))     override fun perform(uiController: UiController, view: View) {         (view as TextView).apply {             this.text = "$text$value"         }         uiController.loopMainThreadUntilIdle()     }     ... } 

Чтобы сделать вашу пользовательскую операцию на 100% нативной для фреймворка Ultron, необходимо добавить еще 3 строки.

//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) 

Наконец, мы можем использовать нашу кастомную операцию appendText:

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

Custom operation assertions

Бывают случаи, когда операция click() не проходит по элементу и тест падает (точнее проходит визуально, но почему-то не срабатывает onClick listener или не отсылается экшен на клик) или вам нужно сделать какой-то необходимый ассершн на клик, чтобы убедиться, что клик возымел эффект. Можно использовать следующее решение:

button.withAssertion("Assert smth is displayed") {     title.isDisplayed() }.click() 

«Assert smth is displayed» — это текст, который вы увидите в случае исключения.
Но это необязательное условие и можно написать так:

button.withAssertion {     title.isDisplayed() }.click() 

По умолчанию все операции Ultron внутри assertion блока не регистрируются в logcat, но в любом случае вы увидите причину в случае исключения.

Если вы хотите, чтобы информация регистрировалась в logcat, используйте параметр isListened

button.withAssertion(isListened = true) { .. } 

Здесь также нужно сделать одно замечание, про тайм-ауты операций assertion и action.

• withAssertion {..} может удвоить время до возникновения исключения. Это происходит потому, что action выполняется как минимум дважды. И блок assertion также выполняется дважды. Это необходимо, чтобы определить истинное исключение по которому падает action.

• В случае, если action выполнен успешно, но assertion failed, то action повторяется. У вас может быть несколько взаимодействий action и assertion.

• Вы можете ограничить время assertion, например:

button.withAssertion {     title.withTimeout(3_000L).isDisplayed() }.click() 

Вы также все еще можете увеличить общий таймаут на всю операцию:

button.withTimeout(10_000L).withAssertion {     title.withTimeout(2_000L).isDisplayed() }.click() 

RuleSequence + SetUps & TearDowns для тестов

• контролировать выполнение пред- и постусловий каждого теста

• контролировать момент запуска активити

• нет необходимости использовать @Before и @After, можно заменить их на лямбда-выражения объектов SetUpRule или TearDownRule

• комбинируйте условия вашего теста, используя аннотации

RuleSequence

RuleSequence правило является усовершенствованной заменой JUnit 4 RuleChain. Это позволяет контролировать порядок выполнения правил.

RuleSequence не имеет проблем при наследовании классов и в этом его изначальная идея.

Порядок выполнения правил зависит от порядка их добавления. RuleSequence содержит три списка правил с собственным приоритетом.

first — правила из этого списка будут выполняться в первую очередь
normal — правила будут добавлены в этот список по умолчанию
last — правила из этого списка будут выполняться последними

Про порядок исполнения подробнее можно почитать тут.

Рекомендуется создавать RuleSequence в BaseTest. Вы сможете добавлять правила в RuleSequence в BaseTest и в подклассах BaseTest.

abstract class BaseTest {     val setupRule = SetUpRule().add {             // предусловия для тестов или автологин в приложение         }      @get:Rule     open val ruleSequence = RuleSequence(setupRule) } 

Добавление правил лучше делать в блоке init вашего тестового класса:

class DemoTest : BaseTest() {     private val activityRule = ActivityScenarioRule(MainActivity::class.java)      init {         ruleSequence.addLast(activityRule)     } } 

При использовании RuleSequence (как это было с RuleChain) вам не нужно указывать аннотацию @get:Rule для других правил.

Фулл примеры можно чекнуть тут:

• BaseTest

• DemoEspressoTest

SetUpRule

Это правило позволяет указать лямбда-выражения, которые обязательно будут вызываться перед запуском теста. Более того, в сочетании с настройкой RuleSequence лямбда-выражения могут быть вызваны до запуска активности.

Предусловия для тестов

Добавляем лямбду в SetUpRule без string key в скобках и она будет выполняться перед каждым тестом в классе.

open val setupRule = SetUpRule()     .add {         Log.info("Login valid user will be executed before any test is started")         AccountManager(InstrumentationRegistry.getInstrumentation().targetContext).login(             CURRENT_USER.login, CURRENT_USER.password         )     } 

Предусловие для конкретного теста

1. добавить лямбду со string key в (..) в SetUpRule

2. добавить аннотацию @SetUp(string key) к нужному тесту

setupRule.add(FIRST_CONDITION){      Log.info("$FIRST_CONDITION setup, executed for test with annotation @SetUp(FIRST_CONDITION)")   }  @SetUp(FIRST_CONDITION) @Test fun someTest() {     // степы теста }  companion object {     private const val FIRST_CONDITION = "Название предусловия" } 

Не забудьте добавить правило SetUpRule в Rule Sequence.

ruleSequence.add(setupRule) 

TearDownRule

Это правило позволяет указать лямбда-выражения, которые обязательно будут вызываться после завершения теста.

Постусловие для всех тестов

Добавьте лямбду в TearDownRule без string key в скобках, и она будет выполняться после каждого теста в классе.

open val tearDownRule = TearDownRule()     .add {         AccountManager(InstrumentationRegistry.getInstrumentation().targetContext).logout()     } 

Постусловие для конкретного теста

1. добавить лямбду со string key в (..) в TearDownRule

2. добавить аннотацию @TearDown(string key) к нужному тесту

tearDownRule.add (LAST_CONDITION){      Log.info("$LAST_CONDITION tearDown, executed for test with annotation @TearDown(LAST_CONDITION)")   }  @TearDown(LAST_CONDITION) @Test fun someTest() {     // степы теста }  companion object {     private const val LAST_CONDITION = "Название постусловия" } 

Не забудьте добавить правило TearDownRule в Rule Sequence.

ruleSequence.addLast(tearDownRule) 

Решение нетривиальных Espresso исключений

Одна из магических ошибок, которая возникает в процессе исполнения тестов может быть Waited for the root of the view hierarchy to have window focus and not request layout for 10 seconds. В данном фреймворке данная проблема решена и вот как это выглядит:

val toolbarTitle = withId(R.id.toolbar_title)  fun assertToolbarTitleWithSuitableRoot(text: String) {     toolbarTitle.withSuitableRoot().hasText(text) } 

Функция withSuitableRoot() ищет видимый root view, где находится ваша искомая view по матчеру и назначает его для вашего ViewInteraction. Если таковой не найдется в пределах внутреннего тайм-аута Espresso, то вывалится нативная ошибка NoMatchingRootException, что никакой root view не подходит для искомой view по вашему матчеру. В данном контексте это будет значить, что во всех видимых root view нет вашей искомой view.

Минусы фреймворка

• Нет adbServer, есть только шелл

• Фреймворк не имеет много авторов и развивается не так активно, как хотелось бы

Заключение

В данной статье я постарался подсветить ключевые фишки фреймворка и ту базу, которая всем интересна на этапе выбора фреймворка автоматизации ui на своем проекте. Спасибо, что дочитали / долистали до конца и надеюсь, что в данной статье вы смогли найти для себя что-то интересное.

Заходите в группу, если у вас есть вопросы Ultron telegram group.