Principes de base d'Espresso

Ce document explique comment effectuer des tâches de test automatisées courantes à l'aide de l'API Espresso.

L'API Espresso encourage les auteurs de tests à réfléchir à ce qu'un utilisateur pourrait faire lorsqu'il interagit avec l'application : localiser des éléments d'interface utilisateur et interagir avec eux. En même temps, le framework empêche l'accès direct aux activités et aux vues de l'application, car le fait de conserver ces objets et de les utiliser en dehors du thread UI est une source majeure d'instabilité des tests. Par conséquent, vous ne verrez pas de méthodes telles que getView() et getCurrentActivity() dans l'API Espresso. Vous pouvez toujours opérer en toute sécurité sur les vues en implémentant vos propres sous-classes de ViewAction et ViewAssertion.

Composants de l'API

Les principaux composants d'Espresso sont les suivants :

  • Espresso : point d'entrée pour les interactions avec les vues (via onView() et onData()). Expose également des API qui ne sont pas nécessairement liées à une vue, telles que pressBack().
  • ViewMatchers : collection d'objets qui implémentent l'interface Matcher<? super View>. Vous pouvez transmettre un ou plusieurs de ces éléments à la méthode onView() pour localiser une vue dans la hiérarchie des vues actuelle.
  • ViewActions : collection d'objets ViewAction pouvant être transmis à la méthode ViewInteraction.perform(), par exemple click().
  • ViewAssertions : collection d'objets ViewAssertion pouvant être transmis à la méthode ViewInteraction.check(). La plupart du temps, vous utiliserez l'assertion "matches", qui utilise un outil de mise en correspondance de vues pour vérifier l'état de la vue actuellement sélectionnée.

Exemple :

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

Rechercher une vue

Dans la grande majorité des cas, la méthode onView() utilise un outil de mise en correspondance Hamcrest qui doit correspondre à une seule vue dans la hiérarchie des vues actuelle. Les outils de mise en correspondance sont puissants et seront familiers à ceux qui les ont utilisés avec Mockito ou JUnit. Si vous ne connaissez pas les outils de mise en correspondance Hamcrest, nous vous suggérons de commencer par consulter rapidement cette présentation.

Souvent, la vue souhaitée possède un R.id unique, et un simple outil de mise en correspondance withId permet d'affiner la recherche de la vue. Cependant, il existe de nombreux cas légitimes dans lesquels vous ne pouvez pas déterminer R.id au moment du développement du test. Par exemple, la vue spécifique peut ne pas avoir d'R.id ou l'R.id n'est pas unique. Cela peut rendre les tests d'instrumentation normaux fragiles et compliqués à écrire, car la méthode normale d'accès à la vue (avec findViewById()) ne fonctionne pas. Vous devrez peut-être accéder aux membres privés de l'activité ou du fragment contenant la vue, ou rechercher un conteneur avec un R.id connu et accéder à son contenu pour la vue en question.

Espresso gère ce problème de manière propre en vous permettant d'affiner la vue à l'aide d'objets ViewMatcher existants ou de vos propres objets personnalisés.

Pour trouver une vue à l'aide de son R.id, il suffit d'appeler onView() :

onView(withId(R.id.my_view))

Parfois, les valeurs R.id sont partagées entre plusieurs vues. Dans ce cas, une tentative d'utilisation d'un R.id particulier génère une exception, telle que AmbiguousViewMatcherException. Le message d'exception fournit une représentation textuelle de la hiérarchie des vues actuelle. Vous pouvez rechercher et trouver les vues qui correspondent au R.id non unique :

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****

En examinant les différents attributs des vues, vous pouvez trouver des propriétés identifiables de manière unique. Dans l'exemple ci-dessus, l'une des vues contient le texte "Hello!". Vous pouvez l'utiliser pour affiner votre recherche à l'aide d'outils de mise en correspondance combinés :

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

Vous pouvez également choisir de n'inverser aucun des outils de mise en correspondance :

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

Pour les outils de mise en correspondance des affichages courants fournis par Espresso, inspectez androidx.test.espresso.matcher.ViewMatchers dans votre IDE ou consultez l'aide-mémoire Espresso.

Remarques

  • Dans une application bien conçue, toutes les vues avec lesquelles un utilisateur peut interagir doivent contenir un texte descriptif ou une description de contenu. Pour en savoir plus, consultez Rendre les applications plus accessibles. Si vous ne parvenez pas à affiner une recherche à l'aide de withText() ou de withContentDescription(), considérez qu'il s'agit d'un bug d'accessibilité.
  • Utilisez l'outil de mise en correspondance le moins descriptif qui trouve la vue que vous recherchez. Ne spécifiez pas trop de détails, car cela obligerait le framework à effectuer plus de travail que nécessaire. Par exemple, si une vue est identifiable de manière unique par son texte, vous n'avez pas besoin de spécifier qu'elle peut également être attribuée à partir de TextView. Pour de nombreuses vues, l'R.id de la vue devrait suffire.
  • Si la vue cible se trouve dans un AdapterView (par exemple, ListView, GridView ou Spinner), la méthode onView() risque de ne pas fonctionner. Dans ce cas, vous devez utiliser onData() à la place.

Effectuer une action sur une vue

Une fois que vous avez trouvé un outil de mise en correspondance adapté à la vue cible, vous pouvez effectuer des instances de ViewAction sur celle-ci à l'aide de la méthode perform.

Par exemple, pour cliquer sur la vue :

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

Vous pouvez exécuter plusieurs actions avec un seul appel "perform" :

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

Si la vue que vous utilisez se trouve dans un ScrollView (vertical ou horizontal), envisagez de faire précéder les actions qui nécessitent l'affichage de la vue (comme click() et typeText()) par scrollTo(). Cela garantit que la vue s'affiche avant de passer à l'autre action :

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

Pour connaître les actions d'affichage courantes fournies par Espresso, inspectez androidx.test.espresso.action.ViewActions dans votre IDE ou consultez l'aide-mémoire Espresso.

Vérifier les assertions de vue

Les assertions peuvent être appliquées à la vue actuellement sélectionnée avec la méthode check(). L'assertion la plus utilisée est l'assertion matches(). Il utilise un objet ViewMatcher pour vérifier l'état de la vue actuellement sélectionnée.

Par exemple, pour vérifier qu'une vue contient le texte "Hello!" :

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

Si vous souhaitez déclarer que "Hello!" est le contenu de la vue, la méthode suivante est considérée comme une mauvaise pratique :

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

En revanche, si vous souhaitez vérifier qu'une vue contenant le texte "Hello!" est visible (par exemple, après une modification de l'indicateur de visibilité des vues), le code est correct.

Afficher le test simple d'assertion

Dans cet exemple, SimpleActivity contient un Button et un TextView. Lorsque l'utilisateur clique sur le bouton, le contenu de TextView devient "Hello Espresso!".

Voici comment tester cela avec Espresso :

Cliquez sur le bouton

La première étape consiste à rechercher une propriété qui permet de trouver le bouton. Le bouton de SimpleActivity possède un R.id unique, comme prévu.

onView(withId(R.id.button_simple))

Maintenant, pour effectuer le clic :

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

Vérifier le texte de TextView

L'élément TextView contenant le texte à vérifier possède également un R.id unique :

onView(withId(R.id.text_simple))

Pour vérifier le texte du contenu :

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

Vérifier le chargement des données dans les vues de l'adaptateur

AdapterView est un type spécial de widget qui charge ses données de manière dynamique à partir d'un adaptateur. L'exemple le plus courant d'un AdapterView est ListView. Contrairement aux widgets statiques tels que LinearLayout, seul un sous-ensemble des enfants AdapterView peut être chargé dans la hiérarchie des vues actuelle. Une simple recherche onView() ne trouverait pas les vues qui ne sont pas actuellement chargées.

Espresso gère ce problème en fournissant un point d'entrée onData() distinct, capable de charger d'abord l'élément d'adaptateur en question, en le mettant en avant avant d'agir sur lui ou sur l'un de ses enfants.

Avertissement : Les implémentations personnalisées de AdapterView peuvent rencontrer des problèmes avec la méthode onData() si elles ne respectent pas les contrats d'héritage, en particulier l'API getItem(). Dans ce cas, la meilleure solution consiste à refactoriser le code de votre application. Si ce n'est pas possible, vous pouvez implémenter un AdapterViewProtocol personnalisé correspondant. Pour en savoir plus, consultez DataInteraction.usingAdapterViewProtocol() et inspectez androidx.test.espresso.action.AdapterViewProtocols dans androidx.test.espresso:espresso-core.

Test simple de la vue de l'adaptateur

Ce test simple montre comment utiliser onData(). SimpleActivity contient un Spinner avec quelques éléments représentant des types de boissons au café. Lorsqu'un élément est sélectionné, un TextView devient "One %s a day!", où %s représente l'élément sélectionné.

L'objectif de ce test est d'ouvrir Spinner, de sélectionner un élément spécifique et de vérifier que TextView contient l'élément. Comme la classe Spinner est basée sur AdapterView, il est recommandé d'utiliser onData() au lieu de onView() pour faire correspondre l'élément.

Ouvrir la sélection d'éléments

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

Sélectionner un élément

Pour la sélection d'éléments, Spinner crée un ListView avec son contenu. Cette vue peut être très longue, et l'élément peut ne pas être ajouté à la hiérarchie des vues. En utilisant onData(), nous forçons l'élément souhaité dans la hiérarchie des vues. Les éléments de Spinner sont des chaînes. Nous voulons donc faire correspondre un élément égal à la chaîne "Americano" :

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

Vérifier que le texte est correct

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

Débogage

Espresso fournit des informations de débogage utiles en cas d'échec d'un test :

Journalisation

Espresso consigne toutes les actions d'affichage dans logcat. Exemple :

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

Hiérarchie de vues

Espresso affiche la hiérarchie des vues dans le message d'exception en cas d'échec de onView().

  • Si onView() ne trouve pas la vue cible, une exception NoMatchingViewException est générée. Vous pouvez examiner la hiérarchie des vues dans la chaîne d'exception pour analyser pourquoi l'outil de mise en correspondance n'a trouvé aucune vue correspondante.
  • Si onView() trouve plusieurs vues correspondant au comparateur donné, une exception AmbiguousViewMatcherException est générée. La hiérarchie des vues est imprimée, et toutes les vues correspondantes sont marquées avec l'étiquette 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****

Lorsque vous êtes confronté à une hiérarchie des vues complexe ou à un comportement inattendu des widgets, il est toujours utile d'utiliser le Hierarchy Viewer dans Android Studio pour obtenir une explication.

Avertissements concernant la vue de l'adaptateur

Espresso avertit les utilisateurs de la présence de widgets AdapterView. Lorsqu'une opération onView() génère une exception NoMatchingViewException et que des widgets AdapterView sont présents dans la hiérarchie des vues, la solution la plus courante consiste à utiliser onData(). Le message d'exception inclut un avertissement avec la liste des vues de l'adaptateur. Vous pouvez utiliser ces informations pour appeler onData() afin de charger la vue cible.

Ressources supplémentaires

Pour en savoir plus sur l'utilisation d'Espresso dans les tests Android, consultez les ressources suivantes.

Exemples