Receitas do Espresso

Este documento descreve como configurar diversos testes comuns do Espresso.

Associar uma visualização ao lado de outra

Um layout pode conter certas visualizações que não são exclusivas por si só. Por exemplo, um botão de chamada repetido em uma tabela de contatos pode ter o mesmo R.id, conter o mesmo texto e ter as mesmas propriedades que outros botões de chamada na hierarquia de visualização.

Por exemplo, nesta atividade, a visualização com o texto "7" se repete em várias linhas:

Uma atividade de lista mostrando três cópias do mesmo elemento de visualização
     em uma lista de três itens

Muitas vezes, a visualização não exclusiva é pareada com um rótulo exclusivo localizado ao lado dela, como o nome do contato ao lado do botão de chamada. Nesse caso, você pode usar o matcher hasSibling() para restringir sua seleção:

onView(allOf(withText("7"), hasSibling(withText("item: 0"))))
    .perform(click())

Associar uma visualização que está dentro de uma barra de ações

O ActionBarTestActivity tem duas barras de ações diferentes: uma barra de ações normal e uma barra de ação contextual, que é criada em um menu "opções". As duas barras de ações têm um item que está sempre visível e dois itens que só ficam visíveis no menu flutuante. Quando um item é clicado, ele muda um TextView para o conteúdo do item clicado.

A correspondência de ícones visíveis nas duas barras de ações é simples, conforme mostrado no snippet de código abaixo:

fun testClickActionBarItem() {
    // We make sure the contextual action bar is hidden.
    onView(withId(R.id.hide_contextual_action_bar))
        .perform(click())

    // Click on the icon - we can find it by the r.Id.
    onView(withId(R.id.action_save))
        .perform(click())

    // Verify that we have really clicked on the icon
    // by checking the TextView content.
    onView(withId(R.id.text_action_bar_result))
        .check(matches(withText("Save")))
}

O botão "Salvar" fica na barra de ações, na parte superior da atividade

O código é o mesmo para a barra de ações contextual:

fun testClickActionModeItem() {
    // Make sure we show the contextual action bar.
    onView(withId(R.id.show_contextual_action_bar))
        .perform(click())

    // Click on the icon.
    onView((withId(R.id.action_lock)))
        .perform(click())

    // Verify that we have really clicked on the icon
    // by checking the TextView content.
    onView(withId(R.id.text_action_bar_result))
        .check(matches(withText("Lock")))
}

O botão "Bloquear" fica na barra de ações, na parte superior da atividade

Clicar em itens no menu flutuante é um pouco mais complicado para a barra de ações normal, porque alguns dispositivos têm um botão de menu flutuante de hardware, que abre os itens flutuantes em um menu "opções", e outros têm um botão de menu flutuante de software, que abre um menu flutuante normal. Felizmente, o Espresso faz isso por nós.

Para a barra de ações normal:

fun testActionBarOverflow() {
    // Make sure we hide the contextual action bar.
    onView(withId(R.id.hide_contextual_action_bar))
        .perform(click())

    // Open the options menu OR open the overflow menu, depending on whether
    // the device has a hardware or software overflow menu button.
    openActionBarOverflowOrOptionsMenu(
        ApplicationProvider.getApplicationContext<Context>()
    )

    // Click the item.
    onView(withText("World"))
        .perform(click())

    // Verify that we have really clicked on the icon by checking
    // the TextView content.
    onView(withId(R.id.text_action_bar_result))
        .check(matches(withText("World")))
}

O botão do menu flutuante está visível, e uma lista aparece abaixo da
          barra de ações, perto da parte de cima da tela.

Esta é a aparência da barra em dispositivos com um botão físico de menu flutuante:

Não há botão de menu flutuante, e uma lista aparece perto da parte de baixo
          da tela

Para a barra de ações contextual, o código também é fácil:

fun testActionModeOverflow() {
    // Show the contextual action bar.
    onView(withId(R.id.show_contextual_action_bar))
        .perform(click())

    // Open the overflow menu from contextual action mode.
    openContextualActionModeOverflowMenu()

    // Click on the item.
    onView(withText("Key"))
        .perform(click())

    // Verify that we have really clicked on the icon by
    // checking the TextView content.
    onView(withId(R.id.text_action_bar_result))
        .check(matches(withText("Key")))
}

O botão do menu flutuante aparece na barra de ações, e a lista de
          opções aparece abaixo da barra de ações, perto da parte de cima da tela

Para ver o código completo desses exemplos, consulte o exemplo de ActionBarTest.java no GitHub.

Declarar que uma visualização não é exibida

Depois de realizar uma série de ações, você vai querer declarar o estado da interface em teste. Às vezes, pode ser um caso negativo, como quando algo não está acontecendo. É possível transformar qualquer matcher de visualização do Hamcrest em um ViewAssertion usando ViewAssertions.matches().

No exemplo abaixo, pegamos o matcher isDisplayed() e o invertemos usando o matcher padrão not():

// import androidx.test.espresso.Espresso.onView
// import androidx.test.espresso.assertion.ViewAssertions.matches
// import androidx.test.espresso.matcher.ViewMatchers.isDisplayed
// import androidx.test.espresso.matcher.ViewMatchers.withId
// import org.hamcrest.Matchers.not

onView(withId(R.id.bottom_left))
    .check(matches(not(isDisplayed())))

A abordagem acima funcionará se a visualização ainda fizer parte da hierarquia. Caso contrário, você vai receber um NoMatchingViewException e precisará usar ViewAssertions.doesNotExist().

Declarar que uma visualização não está presente

Se a visualização não estiver mais na hierarquia de visualização, o que pode acontecer quando uma ação causa uma transição para outra atividade, use ViewAssertions.doesNotExist():

// import androidx.test.espresso.Espresso.onView
// import androidx.test.espresso.assertion.ViewAssertions.doesNotExist
// import androidx.test.espresso.matcher.ViewMatchers.withId

onView(withId(R.id.bottom_left))
    .check(doesNotExist())

Declarar que um item de dados não está em um adaptador

Para provar que um item de dados específico não está em um AdapterView, é preciso fazer as coisas de maneira um pouco diferente. Precisamos encontrar o AdapterView em que estamos interessados e interrogar os dados que ele contém. Não é necessário usar onData(). Em vez disso, usamos onView() para encontrar o AdapterView e, em seguida, usamos outro matcher para trabalhar nos dados dentro da visualização.

Comece pelo matcher:

private fun withAdaptedData(dataMatcher: Matcher<Any>): Matcher<View> {
    return object : TypeSafeMatcher<View>() {

        override fun describeTo(description: Description) {
            description.appendText("with class name: ")
            dataMatcher.describeTo(description)
        }

        public override fun matchesSafely(view: View): Boolean {
            if (view !is AdapterView<*>) {
                return false
            }

            val adapter = view.adapter
            for (i in 0 until adapter.count) {
                if (dataMatcher.matches(adapter.getItem(i))) {
                    return true
                }
            }

            return false
        }
    }
}

Em seguida, basta usar onView() para encontrar a AdapterView:

fun testDataItemNotInAdapter() {
    onView(withId(R.id.list))
        .check(matches(not(withAdaptedData(withItemContent("item: 168")))))
}

E temos uma declaração que vai falhar se um item igual a "item: 168" existir em uma visualização de adaptador com o ID list.

Para ver o exemplo completo, consulte o método testDataItemNotInAdapter() na classe AdapterViewTest.java no GitHub.

Usar um gerenciador de falhas personalizado

Substituir o FailureHandler padrão no Espresso por um personalizado permite um tratamento de erros adicional ou diferente, como fazer uma captura de tela ou transmitir informações de depuração extras.

O exemplo CustomFailureHandlerTest demonstra como implementar um gerenciador de falhas personalizado:

private class CustomFailureHandler(targetContext: Context) : FailureHandler {
    private val delegate: FailureHandler

    init {
        delegate = DefaultFailureHandler(targetContext)
    }

    override fun handle(error: Throwable, viewMatcher: Matcher<View>) {
        try {
            delegate.handle(error, viewMatcher)
        } catch (e: NoMatchingViewException) {
            throw MySpecialException(e)
        }
    }
}

Esse gerenciador de falhas gera um MySpecialException em vez de um NoMatchingViewException e delega todas as outras falhas ao DefaultFailureHandler. O CustomFailureHandler pode ser registrado com o Espresso no método setUp() do teste:

@Throws(Exception::class)
override fun setUp() {
    super.setUp()
    getActivity()
    setFailureHandler(
        CustomFailureHandler(
            ApplicationProvider.getApplicationContext<Context>()
        )
    )
}

Para mais informações, consulte a interface FailureHandler e Espresso.setFailureHandler().

Segmentar janelas não padrão

O Android é compatível com várias janelas. Normalmente, isso é transparente para os usuários e o desenvolvedor de apps, mas, em alguns casos, várias janelas ficam visíveis, como quando uma janela de preenchimento automático é desenhada sobre a janela principal do aplicativo no widget da Pesquisa. Para simplificar, o Espresso usa uma heurística por padrão para adivinhar com qual Window você quer interagir. Essa heurística quase sempre é suficiente. No entanto, em casos raros, é necessário especificar qual janela uma interação deve segmentar. Para isso, forneça seu próprio matcher de janela raiz ou o matcher Root:

onView(withText("South China Sea"))
    .inRoot(withDecorView(not(`is`(getActivity().getWindow().getDecorView()))))
    .perform(click())

Semelhante a androidx.test.espresso.matcher.ViewMatchers, o Espresso oferece matchers de raiz integrados em androidx.test.espresso.matcher.RootMatchers, como withDecorView(), isDialog() e isPlatformPopup(). Para um resumo visual rápido dos comparadores integrados, consulte a página de referência do Espresso ou implemente seu próprio objeto Matcher<Root>.

Confira o exemplo MultipleWindowTest no GitHub.

Os cabeçalhos e rodapés são adicionados a ListViews usando os métodos addHeaderView() e addFooterView(). Para garantir que o Espresso.onData() saiba qual objeto de dados corresponde, transmita um valor de objeto de dados predefinido como o segundo parâmetro para addHeaderView() e addFooterView(). Exemplo:

Em seguida, programe um matcher para o rodapé:

O carregamento da visualização em um teste é simples:

Confira o exemplo de código completo, encontrado no método testClickFooter() de AdapterViewTest.java no GitHub.