Conceitos básicos do Espresso

Este documento explica como concluir tarefas comuns de teste automatizado usando a API Espresso.

A API Espresso incentiva os autores de testes a pensar no que um usuário pode fazer ao interagir com o aplicativo, como localizar elementos da interface e interagir com eles. Ao mesmo tempo, o framework impede o acesso direto a atividades e visualizações do aplicativo, porque manter esses objetos e operar com eles fora da linha de execução de interface é uma das principais causas de instabilidade em testes. Portanto, você não vai encontrar métodos como getView() e getCurrentActivity() na API Espresso. Ainda é possível operar com segurança em visualizações implementando suas próprias subclasses de ViewAction e ViewAssertion.

Componentes da API

Os principais componentes do Espresso incluem:

  • Espresso: ponto de entrada para interações com visualizações (usando onView() e onData()). Também expõe APIs que não estão necessariamente vinculadas a nenhuma visualização, como pressBack().
  • ViewMatchers: uma coleção de objetos que implementam a interface Matcher<? super View>. É possível transmitir um ou mais deles para o método onView() para localizar uma visualização na hierarquia de visualização atual.
  • ViewActions: uma coleção de objetos ViewAction que podem ser transmitidos ao método ViewInteraction.perform(), como click().
  • ViewAssertions: uma coleção de objetos ViewAssertion que podem ser transmitidos ao método ViewInteraction.check(). Na maioria das vezes, você vai usar a declaração matches, que usa um matcher de visualização para declarar o estado da visualização selecionada no momento.

Exemplo:

// withId(R.id.my_view) is a ViewMatcher.
// click() is a ViewAction.
// matches(isDisplayed()) is a ViewAssertion.
onView(withId(R.id.my_view))
    .perform(click())
    .check(matches(isDisplayed()))

Encontrar uma visualização

Na grande maioria dos casos, o método onView() usa um matcher hamcrest que deve corresponder a uma, e apenas uma, visualização na hierarquia de visualização atual. Os correspondentes são eficientes e serão familiares para quem já os usou com o Mockito ou o JUnit. Se você não conhece os matchers do Hamcrest, sugerimos que comece com uma rápida olhada nesta apresentação (link em inglês).

Muitas vezes, a visualização desejada tem um R.id exclusivo, e um matcher withId simples vai restringir a pesquisa de visualização. No entanto, há muitos casos legítimos em que não é possível determinar R.id no momento do desenvolvimento do teste. Por exemplo, a visualização específica pode não ter um R.id ou o R.id não é exclusivo. Isso pode tornar os testes de instrumentação normais frágeis e complicados de escrever, porque a maneira normal de acessar a visualização, com findViewById(), não funciona. Assim, talvez seja necessário acessar membros particulares da atividade ou do fragmento que contém a visualização ou encontrar um contêiner com um R.id conhecido e navegar até o conteúdo dele para a visualização específica.

O Espresso lida com esse problema de forma limpa, permitindo que você restrinja a visualização usando objetos ViewMatcher existentes ou personalizados.

Encontrar uma visualização pelo R.id é tão simples quanto chamar onView():

onView(withId(R.id.my_view))

Às vezes, os valores R.id são compartilhados entre várias visualizações. Quando isso acontece, uma tentativa de usar um R.id específico gera uma exceção, como AmbiguousViewMatcherException. A mensagem de exceção fornece uma representação de texto da hierarquia de visualização atual, que pode ser pesquisada para encontrar as visualizações que correspondem ao R.id não exclusivo:

java.lang.RuntimeException:
androidx.test.espresso.AmbiguousViewMatcherException
This matcher matches multiple views in the hierarchy: (withId: is <123456789>)

...

+----->SomeView{id=123456789, res-name=plus_one_standard_ann_button,
visibility=VISIBLE, width=523, height=48, has-focus=false, has-focusable=true,
window-focus=true, is-focused=false, is-focusable=false, enabled=true,
selected=false, is-layout-requested=false, text=,
root-is-layout-requested=false, x=0.0, y=625.0, child-count=1}
****MATCHES****
|
+------>OtherView{id=123456789, res-name=plus_one_standard_ann_button,
visibility=VISIBLE, width=523, height=48, has-focus=false, has-focusable=true,
window-focus=true, is-focused=false, is-focusable=true, enabled=true,
selected=false, is-layout-requested=false, text=Hello!,
root-is-layout-requested=false, x=0.0, y=0.0, child-count=1}
****MATCHES****

Ao analisar os vários atributos das visualizações, você pode encontrar propriedades identificáveis de forma exclusiva. No exemplo acima, uma das visualizações tem o texto "Hello!". Você pode usar isso para restringir sua pesquisa usando correspondências de combinação:

onView(allOf(withId(R.id.my_view), withText("Hello!")))

Você também pode optar por não reverter nenhum dos matchers:

onView(allOf(withId(R.id.my_view), not(withText("Unwanted"))))

Para ver os matchers de visualização comuns fornecidos pelo Espresso, inspecione androidx.test.espresso.matcher.ViewMatchers no seu ambiente de desenvolvimento integrado ou consulte a folha de referência do Espresso.

Considerações

  • Em um aplicativo bem-comportado, todas as visualizações com que um usuário pode interagir precisam conter um texto descritivo ou uma descrição de conteúdo. Consulte Como tornar os apps mais acessíveis para mais detalhes. Se não for possível restringir uma pesquisa usando withText() ou withContentDescription(), trate-a como um bug de acessibilidade.
  • Use o matcher menos descritivo que encontre a visualização que você está procurando. Não especifique demais, porque isso vai forçar o framework a fazer mais trabalho do que o necessário. Por exemplo, se uma visualização for claramente identificada pelo texto, não será necessário especificar que ela também pode ser atribuída de TextView. Para muitas visualizações, o R.id da visualização é suficiente.
  • Se a visualização de destino estiver dentro de um AdapterView, como ListView, GridView ou Spinner, o método onView() pode não funcionar. Nesses casos, use onData().

Realizar uma ação em uma visualização

Quando você encontrar um matcher adequado para a visualização de destino, será possível executar instâncias de ViewAction nela usando o método perform.

Por exemplo, para clicar na visualização:

onView(...).perform(click())

Você pode executar uma ou mais ações com uma chamada de execução:

onView(...).perform(typeText("Hello"), click())

Se a visualização em que você está trabalhando estiver localizada dentro de um ScrollView (vertical ou horizontal), considere as ações anteriores que exigem que a visualização seja mostrada, como click() e typeText(), com scrollTo(). Isso garante que a visualização seja mostrada antes de prosseguir para a outra ação:

onView(...).perform(scrollTo(), click())

Para ações de visualização comuns fornecidas pelo Espresso, inspecione androidx.test.espresso.action.ViewActions no seu ambiente de desenvolvimento integrado ou consulte a folha de referência do Espresso.

Verificar as declarações de visualização

As declarações podem ser aplicadas à visualização selecionada no momento com o método check(). A declaração mais usada é a matches(). Ele usa um objeto ViewMatcher para declarar o estado da visualização selecionada no momento.

Por exemplo, para verificar se uma visualização tem o texto "Hello!":

onView(...).check(matches(withText("Hello!")))

Se quiser declarar que "Hello!" é o conteúdo da visualização, a seguinte prática é recomendada:

// Don't use assertions like withText inside onView.
onView(allOf(withId(...), withText("Hello!"))).check(matches(isDisplayed()))

Por outro lado, se você quiser declarar que uma visualização com o texto "Hello!" está visível, por exemplo, após uma mudança da flag de visibilidade das visualizações, o código está correto.

Teste simples para declaração de visualizações

Neste exemplo, SimpleActivity contém um Button e um TextView. Quando o botão é clicado, o conteúdo do TextView muda para "Hello Espresso!".

Veja como testar isso com o Espresso:

Clicar no botão

O primeiro passo é procurar uma propriedade que ajude a encontrar o botão. O botão no SimpleActivity tem um R.id exclusivo, como esperado.

onView(withId(R.id.button_simple))

Agora, para executar o clique:

onView(withId(R.id.button_simple)).perform(click())

Verificar o texto de TextView

O TextView com o texto a ser verificado também tem um R.id exclusivo:

onView(withId(R.id.text_simple))

Agora, para verificar o texto do conteúdo:

onView(withId(R.id.text_simple)).check(matches(withText("Hello Espresso!")))

Verificar o carregamento de dados nas visualizações do adaptador

AdapterView é um tipo especial de widget que carrega os dados dinamicamente de um adaptador. O exemplo mais comum de um AdapterView é ListView. Ao contrário dos widgets estáticos, como LinearLayout, apenas um subconjunto dos filhos de AdapterView pode ser carregado na hierarquia de visualização atual. Uma pesquisa simples de onView() não encontraria visualizações que não estão carregadas no momento.

O Espresso lida com isso fornecendo um ponto de entrada onData() separado, que pode carregar primeiro o item do adaptador em questão, colocando-o em foco antes de operar nele ou em qualquer um dos filhos.

Aviso: implementações personalizadas de AdapterView podem ter problemas com o método onData() se violarem contratos de herança, principalmente a API getItem(). Nesses casos, o melhor curso de ação é refatorar o código do aplicativo. Se não for possível, implemente um AdapterViewProtocol personalizado correspondente. Para mais informações, consulte DataInteraction.usingAdapterViewProtocol() e inspecione androidx.test.espresso.action.AdapterViewProtocols em androidx.test.espresso:espresso-core.

Teste simples para visualização do adaptador

Este teste simples demonstra como usar onData(). SimpleActivity contém uma Spinner com alguns itens que representam tipos de bebidas de café. Quando um item é selecionado, há um TextView que muda para "One %s a day!", em que %s representa o item selecionado.

O objetivo desse teste é abrir o Spinner, selecionar um item específico e verificar se o TextView contém o item. Como a classe Spinner é baseada em AdapterView, é recomendável usar onData() em vez de onView() para corresponder ao item.

Abrir a seleção do item

onView(withId(R.id.spinner_simple)).perform(click())

Selecionar um item

Para a seleção do item, o Spinner cria um ListView com o próprio conteúdo. Essa visualização pode ser muito longa, e o elemento pode não ser adicionado à hierarquia de visualização. Ao usar onData(), forçamos o elemento desejado na hierarquia de visualização. Os itens em Spinner são strings, então queremos corresponder a um item que seja igual à string "Americano":

onData(
    allOf(
        `is`(instanceOf(String::class.java)),
        `is`("Americano")
    )
).perform(click())

Verificar se o texto está correto

onView(withId(R.id.spinnertext_simple))
    .check(matches(withText(containsString("Americano"))))

Depuração

O Espresso oferece informações úteis sobre depuração quando um teste falha:

Gerar registros

O Expresso registra todas as ações de visualização no Logcat. Por exemplo:

ViewInteraction: Performing 'single click' action on view with text: Espresso

Ver hierarquia

O Espresso mostra a hierarquia de visualização na mensagem de exceção quando onView() falha.

  • Se onView() não encontrar a visualização de destino, uma NoMatchingViewException será gerada. É possível examinar a hierarquia de visualização na string de exceção para analisar por que o matcher não correspondeu a nenhuma visualização.
  • Se o onView() encontrar várias visualizações que correspondem ao matcher fornecido, uma AmbiguousViewMatcherException será gerada. A hierarquia de visualização é impressa, e todas as visualizações correspondentes são marcadas com o rótulo MATCHES:
java.lang.RuntimeException:
androidx.test.espresso.AmbiguousViewMatcherException
This matcher matches multiple views in the hierarchy: (withId: is <123456789>)

...

+----->SomeView{id=123456789, res-name=plus_one_standard_ann_button,
visibility=VISIBLE, width=523, height=48, has-focus=false, has-focusable=true,
window-focus=true, is-focused=false, is-focusable=false, enabled=true,
selected=false, is-layout-requested=false, text=,
root-is-layout-requested=false, x=0.0, y=625.0, child-count=1}
****MATCHES****
|
+------>OtherView{id=123456789, res-name=plus_one_standard_ann_button,
visibility=VISIBLE, width=523, height=48, has-focus=false, has-focusable=true,
window-focus=true, is-focused=false, is-focusable=true, enabled=true,
selected=false, is-layout-requested=false, text=Hello!,
root-is-layout-requested=false, x=0.0, y=0.0, child-count=1}
****MATCHES****

Ao lidar com uma hierarquia de visualização complicada ou um comportamento inesperado de widgets, é sempre útil usar o Hierarchy Viewer no Android Studio para uma explicação.

Avisos de visualização do adaptador

O Espresso avisa os usuários sobre a presença de widgets AdapterView. Quando uma operação onView() gera um NoMatchingViewException e os widgets AdapterView estão presentes na hierarquia de visualização, a solução mais comum é usar onData(). A mensagem da exceção incluirá um aviso com uma lista das visualizações do adaptador. Você pode usar essas informações para invocar onData() para carregar a visualização de destino.

Outros recursos

Para mais informações sobre o uso do Espresso em testes do Android, consulte os recursos abaixo.

Amostras