Guide de référence des scripts Robo

Ce document fournit des informations de référence sur les scripts Robo, y compris la structure, les capacités, l'utilisation, l'enregistrement et les actions. Les scripts robotiques sont des tests qui automatisent les tâches manuelles d'assurance qualité (QA) pour les applications mobiles et permettent l'intégration continue (CI) et les stratégies de test de pré-lancement. Un script Robo est un fichier JSON qui décrit une séquence d'interface utilisateur (UI) et d'autres actions.

Vous pouvez créer un script Robo des manières suivantes :

• Utilisez la fonction d'enregistrement de script Robo.
• Créez le script Robo manuellement.
• Enregistrez le script Robo, puis modifiez-le manuellement.

Pour en savoir plus sur l'utilisation des scripts Robo, consultez Exécuter un script Robo .

Le script Robo est fourni au test Robo avec d'autres entrées telles que le package d'application Android (APK) de l'application en cours de test.

Voici un exemple de script Robo qui connecte un utilisateur à une application, qui est déclenchée lorsque l'application en cours de test est lancée :

[
  {
    "crawlStage": "crawl",
    "contextDescriptor": {
      "condition": "app_under_test_shown"
    },
    "actions": [
      {
        "eventType": "VIEW_TEXT_CHANGED",
        "replacementText": "user123",
        "elementDescriptors": [
          {
            "resourceId": "my.app.package:id/username"
          }
        ]
      },
      {
        "eventType": "VIEW_TEXT_CHANGED",
        "replacementText": "12345",
        "elementDescriptors": [
          {
            "resourceId": "my.app.package:id/password"
          }
        ]
      },
      {
        "eventType": "VIEW_CLICKED",
        "elementDescriptors": [
          {
            "resourceId": "my.app.package:id/login"
          }
        ]
      }
    ]
  }
]

S'il y a un seul script Robo dans un fichier et qu'il a la condition de déclenchement par défaut app_under_test_shown , comme dans l'exemple ci-dessus, alors vous pouvez spécifier le script Robo dans un fichier en utilisant un format plus simple - juste comme une séquence de ses actions :

[
  {
    "eventType": "VIEW_TEXT_CHANGED",
    "replacementText": "user123",
    "elementDescriptors": [
      {
        "resourceId": "my.app.package:id/username"
      }
    ]
  },
  {
    "eventType": "VIEW_TEXT_CHANGED",
    "replacementText": "12345",
    "elementDescriptors": [
      {
        "resourceId": "my.app.package:id/password"
      }
    ]
  },
  {
    "eventType": "VIEW_CLICKED",
    "elementDescriptors": [
      {
        "resourceId": "my.app.package:id/login"
      }
    ]
  }
]

Structure

Un script Robo a plusieurs attributs qui décrivent comment Robo l'exécute. La plupart de ces attributs sont facultatifs avec des valeurs par défaut prédéfinies :

Attribut	Description
id	Un nombre entier qui permet de suivre ce script Robo dans les sorties d'analyse.
description	Similaire à id mais plus descriptif.
crawlStage	L'étape d'un crawl Robo applique ce script Robo à. Par défaut, il s'agit de l'étape de crawl principale.
priority	La priorité de ce script Robo par rapport aux autres scripts Robo. Par défaut, tous les scripts Robo ont une priorité de 1 .
maxNumberOfRuns	Spécifie combien de fois pendant une analyse Robo peut exécuter ce script Robo. Par défaut, Robo peut exécuter un script Robo une seule fois.
contextDescriptor	Décrit le contexte/la condition qui déclenche ce script Robo. Si elle est omise, la condition de déclenchement de ce script Robo est considérée comme toujours remplie ; en d'autres termes, le script Robo est inconditionnel.
actions	Toutes les actions de ce script Robo.

Un seul fichier contient une collection d'un ou plusieurs scripts Robo.

Voici un exemple de fichier avec deux scripts Robo inconditionnels, chacun avec une seule action exécutée une fois au début d'un crawl :

[
  {
    "id": 1000,
    "description": "My first Robo script",
    "actions": [
      {
        "eventType": "DISABLE_KEYBOARD"
      }
    ]
  },
  {
    "id": 1001,
    "description": "My second Robo script",
    "actions": [
      {
        "eventType": "PRESSED_BACK"
      }
    ]
  }
]

Descripteur de contexte

Un descripteur de contexte définit le contexte/la condition qui déclenche un script Robo à l'aide d'un ou d'une combinaison de plusieurs attributs :

Attribut	Description
"condition": "element_present"	Vérifie qu'un widget d'interface utilisateur qui correspond à elementDescriptors ou au texte spécifié par visionText est présent à l'écran.
"condition": "element_disabled"	Vérifie qu'un widget d'interface utilisateur qui correspond à elementDescriptors est présent à l'écran et qu'il est impossible d'interagir avec lui.
"condition": "element_checked"	Vérifie qu'un widget d'interface utilisateur qui correspond à elementDescriptors est présent à l'écran et est coché.
"condition": "app_under_test_shown"	Vérifie que l'application en cours de test s'exécute au premier plan.
"condition": "default_launcher_shown"	Vérifie que l'écran d'accueil d'un appareil s'affiche, ce qui signifie qu'aucune application n'est en cours d'exécution au premier plan.
"condition": "non_roboscript_action_performed"	Vérifie que la dernière action effectuée par le test Robo n'est pas une action de script Robo.
negateCondition	Si défini sur true , annule la condition . Par exemple, vous pouvez utiliser cet attribut pour vérifier si un widget d'interface utilisateur n'est PAS présent à l'écran ou si l'application en cours de test ne s'exécute PAS au premier plan.
elementDescriptors	Un ou plusieurs descripteurs d'élément qui identifient un widget d'interface utilisateur à l'écran. Il est utilisé en combinaison avec les conditions element_present , element_disabled et element_checked . Mutuellement exclusif avec visionText . Pour plus d'informations, voir Descripteurs d'éléments .
visionText	Le texte à l'écran est détecté à l'aide de l'API de reconnaissance optique de caractères (OCR). visionText est utilisé en combinaison avec la condition element_present . Mutuellement exclusif avec elementDescriptors .

Voici un exemple de script Robo déclenché par un widget d'interface utilisateur avec un ID de ressource "my.app.package:id/page_header" présent à l'écran :

{
  "id": 1000,
  "contextDescriptor": {
    "condition": "element_present",
    "elementDescriptors": [
      {
        "resourceId": "my.app.package:id/page_header"
      }
    ]
  },
  "actions": [
    {
      "eventType": "VIEW_CLICKED",
      "elementDescriptors": [
        {
          "text": "Settings"
        }
      ]
    }
  ]
}

Voici un exemple de script Robo déclenché par "Privacy Policy" détectée par la reconnaissance optique de caractères (OCR) :

{
  "id": 1000,
  "description": "Vision text Robo script",
  "contextDescriptor": {
    "condition": "element_present",
    "visionText": "Privacy Policy"
  },
  "actions": [
    {
      "eventType": "VIEW_CLICKED",
      "visionText": "Privacy Policy"
    }
  ]
}

Voici un exemple de script Robo qui attend 5 secondes après chaque action Robo non script :

{
  "contextDescriptor": {
    "condition": "non_roboscript_action_performed"
  },
  "maxNumberOfRuns" : 1000,
  "actions" : [
    {
      "eventType" : "DELAYED_MESSAGE_POSTED",
      "delayTime" : 5000
    }]
}

Actions

Chaque action d'un script Robo est représentée sous la forme d'un ensemble d'une ou plusieurs paires attribut-valeur, qui sont décrites dans le tableau suivant :

Attribut	Description
eventType	Spécifie le type de l'action, par exemple, clic, modification de texte, etc. Obligatoire pour chaque action.
elementDescriptors	Descripteurs qui identifient un widget d'interface utilisateur. Requis pour toutes les actions qui ont un widget d'interface utilisateur cible, comme cliquer sur un bouton particulier.
optional	Si la valeur est true , cette action est ignorée lorsqu'elle ne peut pas être effectuée. Par exemple, cette action est ignorée lorsqu'elle ne trouve pas son widget d'interface utilisateur cible sur un écran, sans faire échouer le script Robo contenant. Par défaut, la valeur est false .
replacementText	Le texte à saisir dans le widget d'interface utilisateur cible. Obligatoire pour les actions d'édition de texte.
swipeDirection	Spécifie la direction du balayage. Obligatoire pour les actions de balayage.
delayTime	Spécifie le temps d'attente, en millisecondes. Obligatoire pour les actions d'attente.
pointTapXCoordinate et pointTapYCoordinate	Coordonnées pixel X et Y du point tapé. Mutuellement exclusif avec pointTapXPercent et pointTapYPercent . Requis pour les actions d'appui ponctuel.
pointTapXPercent et pointTapYPercent	Coordonnées X et Y en pourcentage du point tapé. Mutuellement exclusif avec pointTapXCoordinate et pointTapYCoordinate . Requis pour les actions d'appui ponctuel.

Voici un exemple de script Robo avec deux actions sans widgets d'interface utilisateur cibles, ce qui signifie que ces actions ne fonctionnent pas sur un widget d'interface utilisateur spécifique :

[
  {
    "eventType": "DELAYED_MESSAGE_POSTED",
    "delayTime": 3000
  },
  {
    "eventType": "PRESSED_BACK"
  }
]

Descripteurs d'éléments

Un descripteur d'élément identifie un widget d'interface utilisateur à l'aide d'un ou plusieurs des attributs d'identification suivants :

Attribut	Description
className	–
ancestorClassName	Nom de classe de l'ancêtre de la hiérarchie de l'interface utilisateur de l'élément. Un ancêtre est l'un des nœuds parents dans la hiérarchie de l'interface utilisateur de l'élément, y compris l'élément lui-même.
resourceId	–
resourceIdRegex	Expression régulière Java pour correspondre à resourceId .
contentDescription	–
contentDescriptionRegex	Expression régulière Java pour correspondre à contentDescription .
text (qui apparaît à l'écran)	–
textRegex	Expression régulière Java pour faire correspondre text .
groupViewChildPosition , recyclerViewChildPosition ou adapterViewChildPosition	Représente la position enfant d'un widget d'interface utilisateur en fonction du type de son widget parent.

Souvent, ces attributs ne sont pas définis, par exemple, un bouton peut ne pas avoir de texte et de description de contenu. Même si certaines valeurs d'attribut sont présentes, elles peuvent ne pas être uniques sur un écran d'application donné (y compris resourceId ).

Par exemple, la différenciation entre les éléments d'une liste n'est généralement possible qu'en utilisant leurs différentes positions enfant dans leur widget parent. Cela signifie que l'utilisation d'un seul descripteur d'élément pour identifier un widget d'interface utilisateur est généralement insuffisante. Par conséquent, l'attribut elementDescriptors d'une action contient une séquence de descripteurs d'éléments qui sont ordonnés de sorte que le premier corresponde au widget d'interface utilisateur cible, le second corresponde au widget parent du widget d'interface utilisateur cible, et ainsi de suite. Le widget d'interface utilisateur cible d'une action est mis en correspondance lorsque tous ses descripteurs d'élément correspondent à la sous-hiérarchie de widget d'interface utilisateur correspondante.

Voici un exemple de script Robo avec un changement de texte et des actions de clic, qui nécessitent tous deux que vous identifiiez le widget d'interface utilisateur cible à l'aide des descripteurs d'élément fournis :

[
  {
    "eventType": "VIEW_TEXT_CHANGED",
    "replacementText": "John",
    "elementDescriptors": [
      {
        "className": "android.support.v7.widget.AppCompatEditText",
        "groupViewChildPosition": 0,
        "resourceId": "com.google.samples.apps.topeka:id/first_name"
      },
      {
        "className": "android.widget.FrameLayout",
        "groupViewChildPosition": 0
      },
      {
        "className": "android.support.design.widget.TextInputLayout",
        "groupViewChildPosition": 1
      }
    ]
  },
  {
    "eventType": "VIEW_CLICKED",
    "elementDescriptors": [
      {
        "className": "android.support.design.widget.FloatingActionButton",
        "groupViewChildPosition": 1,
        "resourceId": "com.google.samples.apps.topeka:id/done"
      },
      {
        "className": "android.widget.FrameLayout",
        "groupViewChildPosition": 1,
        "resourceId": "com.google.samples.apps.topeka:id/content"
      },
      {
        "className": "android.widget.FrameLayout",
        "groupViewChildPosition": 0,
        "resourceId": "com.google.samples.apps.topeka:id/sign_in_content"
      }
    ]
  }
]

Possibilités d'exécution

Vous pouvez éventuellement préfixer la liste des actions dans un script Robo avec un objet JSON qui spécifie les options d'exécution pour ce script Robo. Cet en-tête de configuration commence par le mot-clé roboscript suivi d'une représentation JSON des options d'exécution souhaitées.

Les scripts Robo prennent en charge les options d'exécution suivantes :

• executionMode - options d'exécution appliquées lorsqu'un script Robo est en cours d'exécution :
  • strict - si défini sur true , le script Robo n'utilise pas de correspondance partielle, ignore l'action en cours et suspend . Autrement dit, le script Robo est exécuté comme un test d'instrumentation normal et échoue dès que l'une de ses actions ne peut pas être effectuée.
• postscript - options d'exécution appliquées après la fin d'un script Robo :
  • terminate - si défini sur true , le test Robo arrête l'exploration une fois le script Robo terminé.

Voici un exemple de script Robo exécuté en mode strict qui dort pendant trois secondes, après quoi l'exploration s'arrête :

"roboscript": {
  "executionMode": {
    "strict": true
  },
  "postscript": {
    "terminate": true
  }
}
[
  {
    "eventType": "DELAYED_MESSAGE_POSTED",
    "delayTime": 3000
  }
]

Paramètres du modèle

Un paramètre de modèle est un espace réservé dans un script Robo qui est remplacé par la valeur réelle lorsque le test Robo charge ce script Robo pour exécution. Les paramètres de modèle sont précédés d'un double trait de soulignement suivi d'un signe de pourcentage et sont postfixés d'un signe de pourcentage suivi d'un double trait de soulignement.

Les scripts Robo prennent en charge le paramètre de modèle suivant :

• __%APP_PACKAGE_NAME%__ - le nom du package de l'application en cours de test.

Voici un exemple de script Robo qui arrête le processus d'application en cours de test :

[
  {
    "eventType": "ADB_SHELL_COMMAND",
    "command": "am force-stop __%APP_PACKAGE_NAME%__"
  }
]

commentaires

Un script Robo peut contenir des lignes de commentaires, qui sont des lignes commençant par # ou // .

Voici un exemple de script Robo avec quelques commentaires :

# Confirm a user account.
[
  {
    // Click the DONE button.
    "eventType": "VIEW_CLICKED",
    "elementDescriptors": [
      {
        "resourceId": "com.google.samples.apps.topeka:id/done"
      }
    ]
  }
]

Capacités

Par défaut, jusqu'à ce que toutes les actions d'un script Robo soient terminées (ou au moins tentées), le script Robo reste actif. Le test Robo continue d'essayer de faire correspondre une action de script Robo chaque fois qu'il sélectionne une action à effectuer. Le script Robo utilise les techniques suivantes pour augmenter la robustesse :

Technique	Description
Appariement partiel	Si l'action de script Robo actuelle ne peut pas être entièrement mise en correspondance, les critères de correspondance sont assouplis et la mise en correspondance est réessayée. La correspondance partielle ne prend pas en compte le descripteur d'élément le plus externe lors de la correspondance avec le widget d'interface utilisateur cible d'une action de script Robo. Si la correspondance partielle réussit, l'action de script Robo correspondante est exécutée comme d'habitude. Cette technique prend en charge les scénarios dans lesquels la structure de l'application change, par exemple, entre les versions de l'application, lorsque les éléments de l'écran sont réorganisés.
Ignorer l'action en cours	Si l'action de script Robo actuelle ne peut pas correspondre entièrement ou partiellement, Robo essaie de faire correspondre l'action de script Robo suivante. Si l'action suivante correspond entièrement ou partiellement, le test Robo ignore (et ne revient jamais) l'action de script Robo actuelle et exécute la suivante. Cette technique prend en charge les scénarios lorsque le comportement de l'application change entre les versions ou est instable, par exemple, lorsqu'une boîte de dialogue intermittente peut apparaître sur différents écrans lors de l'enregistrement par rapport à la relecture d'un script Robo.
Suspendre	Si aucune des actions de script Robo actuelles ou ultérieures ne peut correspondre entièrement ou partiellement, le script Robo est temporairement suspendu et le test Robo sélectionne une action à effectuer à l'aide de ses autres stratégies. Une fois cette action terminée, le test Robo reprend l'exécution du script Robo. Tant que les actions de script Robo actuelles ou ultérieures ne peuvent pas être mises en correspondance, le script Robo reste suspendu pour n'importe quel nombre d'actions. Ainsi, les scripts Robo n'ont pas nécessairement besoin d'être un prologue pour un test Robo, et vous pouvez intercaler des actions de script Robo avec des actions de test Robo standard. Cette technique prend en charge les scénarios lorsque le comportement de l'application est instable ou lorsque les changements entre les versions de l'application sont suffisamment importants pour que le test Robo doive « combler les lacunes » avec ses actions standard.

Priorités

Si un script Robo atteint son maxNumberOfRuns , il ne peut plus être déclenché dans un crawl donné. Si plusieurs scripts Robo peuvent être déclenchés par le contexte actuel, la priorité est donnée en choisissant, dans l'ordre suivant, le script Robo qui :

1. Possède un attribut contextDescriptor .
2. A la priority la plus élevée (par défaut, tous les scripts Robo ont la même priority d'exécution de 1 ).
3. Apparaît en premier dans la liste des scripts Robo, si les priorités des scripts Robo sont les mêmes.

Voici un exemple de fichier avec trois scripts Robo qui effectuent la même action et sont déclenchés par la même condition - l'application sous test étant au premier plan :

[
  {
    "id": 1000,
    "description": "Robo script 1",
    "contextDescriptor": {
      "condition": "app_under_test_shown"
    },
    "actions": [
      {
        "eventType": "DELAYED_MESSAGE_POSTED",
        "delayTime": 3000
      }
    ]
  },
  {
    "id": 1001,
    "description": "Robo script 2",
    "priority": "2",
    "contextDescriptor": {
      "condition": "app_under_test_shown"
    },
    "actions": [
      {
        "eventType": "DELAYED_MESSAGE_POSTED",
        "delayTime": 3000
      }
    ]
  },
  {
    "id": 1002,
    "description": "Robo script 3",
    "contextDescriptor": {
      "condition": "app_under_test_shown"
    },
    "actions": [
      {
        "eventType": "DELAYED_MESSAGE_POSTED",
        "delayTime": 3000
      }
    ]
  }
]

Lorsque l'application en cours de test est au premier plan, Robo déclenche les actions suivantes, dans l'ordre :

1. "Robo script 2" car il a la priorité la plus élevée.
2. "Robo script 1" car il apparaît plus tôt parmi les scripts Robo applicables restants avec la même priorité.
3. "Robo script 3" comme dernier script Robo applicable.

Courses répétées

Par défaut, Robo déclenche un script Robo au plus une fois lors d'un crawl. Cela peut être ajusté via l'attribut maxNumberOfRuns .

Voici un exemple de script Robo qui met l'application en cours de test en arrière-plan jusqu'à 10 fois :

{
  "id": 1000,
  "maxNumberOfRuns": 10,
  "contextDescriptor": {
    "condition": "app_under_test_shown"
  },
  "actions": [
    {
      "eventType": "GO_HOME"
    }
  ]
}

Étape d'exploration

Les scripts Robo sont applicables à différentes étapes d'un crawl Robo donné :

Étape d'exploration	Description
pre_crawl	Avant que Robo ne se lance et ne commence à explorer l'application en cours de test.
post_crawl	Une fois que Robo a fini d'explorer l'application en cours de test.
crawl	L'étape d'exploration principale, lorsque Robo explore l'application en cours de test.
close_screen	Lorsque Robo essaie de revenir en arrière (backtrack) à partir d'un écran donné, lorsque toutes les actions possibles sur cet écran sont explorées. Par défaut, Robo appuie en arrière, ce qui n'est pas souhaitable dans certains scénarios.

Si l'attribut crawlStage d'un script Robo n'est pas spécifié, il s'agit implicitement de crawl .

Voici un exemple de script Robo qui efface les données utilisateur de l'application en cours de test avant que Robo ne commence à l'explorer :

{
  "id": 1000,
  "crawlStage": "pre_crawl",
  "actions": [
    {
      "eventType": "ADB_SHELL_COMMAND",
      "command": "pm clear __%APP_PACKAGE_NAME%__"
    }
  ]
}

Voici un exemple de script Robo qui demande à Robo de cliquer sur "Cancel" chaque fois qu'il tente de revenir en arrière (retour en arrière) à partir d'une boîte de dialogue de confirmation :

{
  "id": 1000,
  "crawlStage": "close_screen",
  "maxNumberOfRuns": 999,
  "contextDescriptor": {
    "condition": "element_present",
    "elementDescriptors": [
      {
        "resourceId": "my.app.package:id/confirmation_dialog"
      }
    ]
  },
  "actions": [
    {
      "eventType": "VIEW_CLICKED",
      "elementDescriptors": [
        {
          "text": "Cancel"
        }
      ]
    }
  ]
}

Actions conditionnelles

Un script Robo peut contenir des actions conditionnelles. Les actions conditionnelles ont trois attributs supplémentaires qui décrivent comment Robo les exécute :

Attribut	Description
priority	La priorité de cette action conditionnelle par rapport aux autres actions conditionnelles dans son script Robo contenant. Par défaut, toutes les actions conditionnelles ont une priorité de 1 .
maxNumberOfRuns	Combien de fois cette action conditionnelle peut être effectuée lors d'une exécution de son script Robo contenant. Par défaut, toutes les actions conditionnelles peuvent être exécutées au plus une fois dans une seule exécution de leur script Robo contenant.
contextDescriptor	Le contexte/la condition qui déclenche cette action conditionnelle. Il a la même structure et offre des fonctionnalités similaires au [contextDescriptor du script Robo](#context-descriptor).

Lorsqu'il est déclenché, un script Robo exécute ses actions non conditionnelles une par une dans l'ordre d'apparition. Si un script Robo contient des actions conditionnelles, elles sont prises en compte à chaque fois avant de choisir une action non conditionnelle à effectuer. Si une action conditionnelle est déclenchée et sélectionnée en fonction de sa priorité et du nombre d'exécutions restantes, le script Robo exécute cette action conditionnelle. Sinon, le script Robo exécute l'action non conditionnelle suivante. Pour être valide, un script Robo doit contenir au moins une action non conditionnelle.

Voici un exemple de script Robo inconditionnel avec une action conditionnelle qui ferme les boîtes de dialogue contextuelles si elles s'affichent à tout moment pendant l'exécution du script Robo :

{
  "id": 1000,
  "actions": [
    {
      "description": "Dismiss popup",
      "maxNumberOfRuns": 100,
      "contextDescriptor": {
        "condition": "default_launcher_shown",
        "negateCondition": true
      },
      "eventType": "GO_HOME"
    },
    {
      "description": "Screen off",
      "eventType": "ADB_SHELL_COMMAND",
      "command": "input keyevent 26"
    },
    {
      "description": "Wait for 10 seconds",
      "eventType": "DELAYED_MESSAGE_POSTED",
      "delayTime": 10000
    },
    {
      "description": "Screen on",
      "eventType": "ADB_SHELL_COMMAND",
      "command": "input keyevent 82"
    },
    {
      "description": "Wait for 10 seconds",
      "eventType": "DELAYED_MESSAGE_POSTED",
      "delayTime": 10000
    }
}

Ignorer les actions

Un script Robo peut contenir des instructions permettant à Robo d'ignorer des widgets d'interface utilisateur spécifiques ou tous les widgets d'interface utilisateur sur un écran particulier. Ces instructions sont représentées comme ignorant les "actions" avec eventType ELEMENT_IGNORED et ALL_ELEMENTS_IGNORED en conséquence.

Chaque fois que l'attribut contextDescriptor d'un script Robo contenant des actions ignorées correspond à un écran donné, Robo n'interagit avec aucun widget d'interface utilisateur ciblé par ses actions d'ignorance (à moins qu'une autre action de script Robo oblige Robo à effectuer une action sur l'un des widgets d'interface utilisateur ignorés).

Un script Robo peut contenir un mélange d'actions ignorées, conditionnelles et non conditionnelles. Contrairement aux autres actions de script Robo, les actions ignorées sont appliquées tant que contextDescriptor du script Robo qui les contient correspond à un écran lors d'une analyse Robo, quelles que soient les valeurs des attributs priority et maxNumberOfRuns .

Voici un exemple de fichier avec deux scripts Robo. Le premier script Robo oblige Robo à ignorer tous les widgets d'interface utilisateur sur un écran contenant un widget d'interface utilisateur avec un ID de ressource "my.app.package:id/ignored_screen" . Le deuxième script Robo permet à Robo d'ignorer les widgets d'interface utilisateur dont les ID de ressource correspondent à l'expression régulière Java ".*:id/done" sur un écran contenant un widget d'interface utilisateur avec un ID de ressource "my.app.package:id/main_screen" :

[
  {
    "id": 1000,
    "contextDescriptor": {
      "condition": "element_present",
      "elementDescriptors": [
        {
          "resourceId": "my.app.package:id/ignored_screen"
        }
      ]
    },
    "actions": [
      {
        "eventType": "ALL_ELEMENTS_IGNORED"
      }
    ]
  },
  {
    "id": 1001,
    "contextDescriptor": {
      "condition": "element_present",
      "elementDescriptors": [
        {
          "resourceId": "my.app.package:id/main_screen"
        }
      ]
    },
    "actions": [
      {
        "eventType": "ELEMENT_IGNORED",
        "elementDescriptors": [
          {
            "resourceIdRegex": ".*:id/done"
          }
        ]
      }
    ]
  }
]

Prise en charge de RecyclerView et AdapterView

Les enfants des widgets RecyclerView et AdapterView sont chargés dynamiquement et peuvent être affichés à plusieurs balayages de l'écran actuel. Étant donné que la taille d'un écran et le nombre de balayages nécessaires pour atteindre cet enfant sont différents pour différents facteurs de forme d'appareil, il est beaucoup plus robuste de s'appuyer sur la position des données de l'enfant, qui est absolue. C'est une approche moins robuste de compter sur le nombre de balayages nécessaires pour amener cet enfant à l'écran, puis d'utiliser sa position à l'écran.

Par conséquent, le script Robo capture les positions de données absolues des enfants RecyclerView qui sont les cibles des actions de script Robo en tant que recyclerViewChildPosition . Le script Robo capture également les positions de données absolues des enfants AdapterView qui sont les cibles des actions de script Robo en tant que adapterViewChildPosition .

Les actions sur les enfants RecyclerView et AdapterView sont effectuées selon les étapes suivantes :

1. Le test Robo garantit que l'enfant correspondant est affiché à l'écran grâce à une action de positionnement sur son RecyclerView ou AdapterView contenant.

2. Robo test effectue l'action enregistrée directement sur l'élément enfant, puisqu'il est déjà affiché à l'écran.

Voici un exemple d'action de clic sur un enfant AdapterView ( android.widget.GridView ):

{
  "eventType": "VIEW_CLICKED",
  "elementDescriptors": [
    {
      "className": "com.google.samples.apps.topeka.widget.AvatarView",
      "adapterViewChildPosition": 5,
      "resourceId": "com.google.samples.apps.topeka:id/avatar",
      "contentDescription": "Avatar 6"
    },
    {
      "className": "android.widget.GridView",
      "groupViewChildPosition": 1,
      "resourceId": "com.google.samples.apps.topeka:id/avatars"
    },
    {
      "className": "android.widget.LinearLayout",
      "groupViewChildPosition": 1
    },
    {
      "className": "android.widget.LinearLayout",
      "groupViewChildPosition": 0
    }
  ]
}

Voici un exemple d'action de clic sur un enfant RecyclerView ( android.support.v7.widget.RecyclerView ):

{
  "eventType": "VIEW_CLICKED",
  "elementDescriptors": [
    {
      "className": "android.support.v7.widget.AppCompatTextView",
      "groupViewChildPosition": 1,
      "resourceId": "com.google.samples.apps.topeka:id/category_title"
    },
    {
      "className": "android.widget.FrameLayout",
      "recyclerViewChildPosition": 8,
      "resourceId": "com.google.samples.apps.topeka:id/category_item"
    },
    {
      "className": "android.support.v7.widget.RecyclerView",
      "groupViewChildPosition": 1,
      "resourceId": "com.google.samples.apps.topeka:id/categories"
    },
    {
      "className": "android.widget.FrameLayout",
      "groupViewChildPosition": 1,
      "resourceId": "com.google.samples.apps.topeka:id/category_container"
    },
    {
      "className": "android.widget.LinearLayout",
      "groupViewChildPosition": 0
    }
  ]
}

Enregistrez un script Robo dans Android Studio et exécutez-le dans Test Lab

Vous pouvez créer un script Robo dans Android Studio, qui enregistre le script sous forme de fichier JSON. Vous pouvez ensuite télécharger le fichier JSON dans Firebase Test Lab avec l'application et exécuter le test en conséquence.

Lorsque vous exécutez un test Robo avec un script joint, le test Robo parcourt d'abord vos actions pré-scriptées, puis explore l'application comme d'habitude.

Pour créer un fichier JSON de script Robo dans Android Studio, suivez les étapes décrites dans Enregistrer un script Robo à l'aide de Test Lab dans Android Studio .

Actions de script robotique

L'attribut facultatif commun suivant s'applique à toutes les actions :

• description - permet de suivre l'exécution de cette action de script Robo dans les sorties de test Robo.

Affirmation

Si la condition affirmée est vraie, le script Robo passe à l'action suivante, qui peut être une autre assertion. Sinon, l'exécution du script Robo est interrompue en raison d'un échec d'assertion.

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "ASSERTION"	--
contextDescriptor	Décrit le contexte ou la condition affirmée. Il a la même structure et offre des fonctionnalités similaires à celles du contextDescriptor du script Robo .

Voici un exemple d'assertion de script Robo qui vérifie que l'application sous test est au premier plan :

{
  "eventType": "ASSERTION",
  "contextDescriptor": {
    "condition": "app_under_test_shown"
  }
}

Voici un exemple d'assertion de script Robo qui vérifie qu'un widget d'interface utilisateur avec l'ID de ressource "com.google.samples.apps.topeka:id/done" est présent sur un écran :

{
  "eventType": "ASSERTION",
  "contextDescriptor": {
    "condition": "element_present",
    "elementDescriptors": [
      {
        "resourceId": "com.google.samples.apps.topeka:id/done"
      }
    ]
  }
}

Voici un exemple d'assertion de script Robo qui vérifie que "Settings" n'est PAS détecté sur un écran utilisant l'OCR :

{
  "eventType": "ASSERTION",
  "contextDescriptor": {
    "condition": "element_present",
    "negateCondition": true,
    "visionText": "Settings"
  }
}

Cliquez sur

Le tableau suivant répertorie les attributs requis :

Attribut	Description
eventType	Spécifie le type d'action de script Robo.
"eventType": "VIEW_CLICKED"	Clique sur l'élément cible de l'application en cours de test.
"eventType": "SOFT_KEYBOARD_CLICK"	Clique sur l'élément cible du clavier logiciel.
"eventType": "SOFT_KEYBOARD_RANDOM_CLICK"	Clique sur des éléments aléatoires du clavier logiciel jusqu'à maxNumberOfRuns fois.
"eventType": "LIST_ITEM_CLICKED"	Utilisé par l'enregistreur de script Robo dans Android Studio pour cliquer sur les éléments de la liste.
elementDescriptors	Identifie le widget d'interface utilisateur cliqué à l'aide de la hiérarchie de l'interface utilisateur Android. Mutuellement exclusif avec visionText .
visionText	Identifie l'élément cliqué à l'aide de l'OCR. Mutuellement exclusif avec elementDescriptors .
maxNumberOfRuns	Spécifie combien de fois cliquer sur un élément aléatoire du clavier logiciel, lorsque eventType est SOFT_KEYBOARD_RANDOM_CLICK . La valeur par défaut est 1 .

Voici un exemple d'action de script Robo qui clique sur un bouton avec l'ID de ressource "com.google.samples.apps.topeka:id/done" :

{
  "eventType": "VIEW_CLICKED",
  "elementDescriptors": [
    {
      "resourceId": "com.google.samples.apps.topeka:id/done"
    }
  ]
}

Voici un exemple d'action de script Robo qui clique sur "Privacy Policy" détectée sur un écran utilisant l'OCR :

{
  "eventType": "VIEW_CLICKED",
  "visionText": "Privacy Policy"
}

Voici un exemple d'action de script Robo qui clique sur un élément de clavier logiciel avec une description de contenu "Emoji button" :

{
  "eventType": "SOFT_KEYBOARD_CLICK",
  "elementDescriptors": [
    {
      "contentDescription": "Emoji button"
    }
  ]
}

Voici un exemple d'action de script Robo qui clique jusqu'à cinq fois sur des éléments aléatoires du clavier virtuel :

{
  "eventType": "SOFT_KEYBOARD_RANDOM_CLICK",
  "maxNumberOfRuns": 5
}

Désactiver le clavier logiciel

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "DISABLE_KEYBOARD"	--

Voici un exemple d'action de script Robo qui désactive le clavier logiciel :

{
  "eventType": "DISABLE_KEYBOARD"
}

Exécuter la commande shell adb

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "ADB_SHELL_COMMAND"	--
command	La commande shell Android Debug Bridge (adb) à exécuter.

Voici un exemple d'action de script Robo qui efface les données utilisateur de l'application en cours de test :

{
  "eventType": "ADB_SHELL_COMMAND",
  "command": "pm clear __%APP_PACKAGE_NAME%__"
}

Accorder des autorisations

Cette action est enregistrée par l'enregistreur de script Robo dans Android Studio pour une compatibilité descendante avec Espresso Test Recorder . Le test Robo accorde toutes les autorisations à l'application sous test au début de chaque analyse, et par conséquent, cette action est une non-opération. N'utilisez PAS cette action dans vos scripts Robo.

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "PERMISSIONS_REQUEST"	--

Ignorer tous les éléments d'un écran

Cette action fait que Robo ignore tous les éléments sur n'importe quel écran qui déclenche le script Robo contenant.

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "ALL_ELEMENTS_IGNORED"	--

Voici un exemple d'action de script Robo qui oblige Robo à ignorer tous les éléments d'un écran :

{
  "eventType": "ALL_ELEMENTS_IGNORED"
}

Ignorer un élément

Cette action oblige Robo à ignorer un élément (ou des éléments) qui correspondent aux elementDescriptors spécifiés.

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "ELEMENT_IGNORED"	--
elementDescriptors	Identifie le ou les widgets d'interface utilisateur ignorés à l'aide de la hiérarchie de l'interface utilisateur Android.

Voici un exemple d'action de script Robo qui oblige Robo à ignorer tous les éléments dont les descriptions de contenu commencent par "Avatar" :

{
  "eventType": "ELEMENT_IGNORED",
  "elementDescriptors": [
    {
      "contentDescriptionRegex": "Avatar.*"
    }
  ]
}

Texte de saisie

Le tableau suivant répertorie les attributs requis :

Attribut	Description
eventType	Spécifie le type d'action de script Robo.
"eventType": "VIEW_TEXT_CHANGED"	Entre le texte donné dans le widget d'interface utilisateur cible.
"eventType": "ENTER_TEXT"	entre le texte donné dans le widget d'interface utilisateur cible, puis envoie un événement KEYCODE_ENTER à ce widget d'interface utilisateur.
elementDescriptors	Identifie le widget d'interface utilisateur cible à l'aide de la hiérarchie de l'interface utilisateur Android.
replacementText	Le texte à saisir dans le widget d'interface utilisateur cible.

Voici un exemple d'action de script Robo qui saisit "John" dans un widget d'interface utilisateur avec l'ID de ressource "com.google.samples.apps.topeka:id/first_name" :

{
  "eventType": "VIEW_TEXT_CHANGED",
  "replacementText": "John",
  "elementDescriptors": [
    {
      "resourceId": "com.google.samples.apps.topeka:id/first_name"
    }
  ]
}

Clic long

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "VIEW_LONG_CLICKED"	--
elementDescriptors	Identifie le widget d'interface utilisateur cible à l'aide de la hiérarchie de l'interface utilisateur Android.

L'attribut suivant est facultatif :

• delayTime - spécifie la durée de la pression d'un long clic, en millisecondes.

Voici un exemple d'action de script Robo qui effectue un clic de cinq secondes sur un widget d'interface utilisateur avec la description de contenu "Avatar 8" :

{
  "eventType": "VIEW_LONG_CLICKED",
  "elementDescriptors": [
    {
      "contentDescription": "Avatar 8"
    }
  ],
  "delayTime": 5000
}

Effectuer un geste en un point

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "ONE_POINT_GESTURE"	--
coordinates	Deux coordonnées pour un geste à un point, au format "(x1,y1)->(x2,y2)" en pourcentages ou en pixels.

L'attribut suivant est facultatif :

• dragAndDrop - si défini sur true , le geste en un point effectue une action de glisser-déposer. Par défaut, c'est false .

Voici un exemple d'action gestuelle en un point de script Robo qui effectue un balayage vers le bas :

{
  "eventType": "ONE_POINT_GESTURE",
  "coordinates": "(50%,25%)->(50%,75%)"
}

Effectuer un geste en deux points

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "TWO_POINT_GESTURE"	--
coordinates	Quatre coordonnées pour un geste à deux points, au format "(x1,y1)->(x2,y2),(x3,y3)->(x4,y4)" en pourcentages ou en pixels.

Voici un exemple d'action de script Robo qui effectue un geste de pincement :

{
  "eventType": "TWO_POINT_GESTURE",
  "coordinates": "(50%,50%)->(25%,50%),(50%,50%)->(75%,50%)"
}

Effectuer une action IME

Cette action appuie sur le bouton d'action en cours, par exemple, suivant, terminé et rechercher, sur l'éditeur de méthode d'entrée (IME) pour le widget d'interface utilisateur cible spécifié.

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "PRESSED_EDITOR_ACTION"	--
elementDescriptors	Identifie le widget d'interface utilisateur cible à l'aide de la hiérarchie de l'interface utilisateur Android.

Voici un exemple d'action de script Robo qui exécute une action IME sur un widget d'interface utilisateur avec l'ID de ressource "com.google.samples.apps.topeka:id/first_name" :

{
  "eventType": "PRESSED_EDITOR_ACTION",
  "elementDescriptors": [
    {
      "resourceId": "com.google.samples.apps.topeka:id/first_name"
    }
  ]
}

Refouler

Le tableau suivant répertorie les attributs requis :

Attribut	Description
eventType	Spécifie le type d'action de script Robo.
"eventType": "PRESSED_BACK"	Envoie un événement KEYCODE_BACK à l'appareil.
"eventType": "PRESSED_BACK_EMULATOR_28"	Utilisé par l'enregistreur de script Robo dans Android Studio pour appuyer sur les émulateurs API 28.

Voici un exemple d'action de script Robo qui appuie en arrière :

{
  "eventType": "PRESSED_BACK"
}

Appuyez sur accueil

Cette action envoie un événement KEYCODE_HOME à l'appareil.

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "GO_HOME"	--

Voici un exemple d'action de script Robo qui appuie sur home :

{
  "eventType": "GO_HOME"
}

Faire défiler un élément dans la vue

Cette action permet à Robo de faire défiler vers l'avant le widget d'interface utilisateur qui correspond aux elementDescriptors spécifiés jusqu'à ce que le widget d'interface utilisateur correspondant aux childElementDescriptors spécifiés soit présent à l'écran, ou que le widget défilé ne puisse plus défiler, ou que le nombre maximum de 50 défilements soit atteint.

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "ELEMENT_SCROLL_INTO_VIEW"	--
elementDescriptors	Identifie le widget d'interface utilisateur défilant à l'aide de la hiérarchie de l'interface utilisateur Android.
childElementDescriptors	Identifie le widget de l'interface utilisateur à parcourir à l'aide de la hiérarchie de l'interface utilisateur Android.

Voici un exemple d'action de script Robo qui fait défiler le widget UI avec l'ID de ressource "my.app.package:id/scrollable_card_container" jusqu'à ce que le widget UI avec le texte "Orange" soit présent à l'écran (ou plus aucun défilement ne peut être exécuté, ou le nombre maximum de 50 défilements est atteint) :

{
  "eventType": "ELEMENT_SCROLL_INTO_VIEW",
  "elementDescriptors": [
    {
      "resourceId": "my.app.package:id/scrollable_card_container"
    }
  ],
  "childElementDescriptors": [
    {
      "text": "Orange"
    }
  ]
}

Glisser

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "VIEW_SWIPED"	--
swipeDirection	Spécifie la direction du balayage : Left Right Up Down Forward - vers Down ou Right en fonction de la capacité de défilement vertical ou horizontal du widget d'interface utilisateur cible. Backward - Up ou Left en fonction de la possibilité de défilement vertical ou horizontal du widget d'interface utilisateur cible.
elementDescriptors	Identifie le widget d'interface utilisateur cible à l'aide de la hiérarchie de l'interface utilisateur Android.

Voici un exemple d'action de script Robo qui balaye un widget d'interface utilisateur avec l'ID de ressource "my.app.package:id/custom_content" :

{
  "eventType": "VIEW_SWIPED",
  "swipeDirection": "Up",
  "elementDescriptors": [
    {
      "resourceId": "my.app.package:id/custom_content"
    }
  ]
}

Prendre une capture d'écran

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "TAKE_SCREENSHOT"	--
screenshotName	Spécifie le nom du fichier de capture d'écran.

Voici un exemple d'action de script Robo qui prend une capture d'écran :

{
  "eventType": "TAKE_SCREENSHOT",
  "screenshotName": "my_screenshot"
}

Appuyez sur un point de l'écran

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "POINT_TAP"	--
pointTapXCoordinate	La coordonnée pixel X du point tapé. Mutuellement exclusif avec pointTapXPercent et pointTapYPercent .
pointTapYCoordinate	Coordonnée pixel Y du point tapé. Mutuellement exclusif avec pointTapXPercent et pointTapYPercent .
pointTapXPercent	La coordonnée X en pourcentage du point taraudé. Mutuellement exclusif avec pointTapXCoordinate et pointTapYCoordinate .
pointTapYPercent	La coordonnée Y en pourcentage du point taraudé. Mutuellement exclusif avec pointTapXCoordinate et pointTapYCoordinate .

Voici un exemple d'action de script Robo qui touche au milieu d'un écran :

{
  "eventType": "POINT_TAP",
  "pointTapXPercent": 50,
  "pointTapYPercent": 50
}

Appuyez sur un point dans un élément

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "POINT_TAP_ELEMENT"	--
pointTapXPercent	La coordonnée X en pourcentage dans l'élément cible.
pointTapYPercent	La coordonnée Y en pourcentage dans l'élément cible.
elementDescriptors	Identifie le widget d'interface utilisateur cible à l'aide de la hiérarchie d'interface utilisateur Android.

Voici un exemple d'action de script Robo qui déplace le curseur d'une barre de recherche vers la droite :

{
  "eventType": "POINT_TAP_ELEMENT",
  "pointTapXPercent": 80,
  "pointTapYPercent": 50,
  "elementDescriptors": [
    {
      "resourceId": "my.app.package:id/my_seekbar"
    }
  ]
}

Terminer l'exploration

Cette action arrête le test Robo.

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "TERMINATE_CRAWL"	--

Voici un exemple d'action de script Robo qui arrête un test Robo :

{
  "eventType": "TERMINATE_CRAWL"
}

Attendez

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "DELAYED_MESSAGE_POSTED"	--
delayTime	Spécifie le temps d'attente, en millisecondes.

Voici un exemple d'action de script Robo qui attend trois secondes :

{
  "eventType": "DELAYED_MESSAGE_POSTED",
  "delayTime": 3000
}

Attendre un élément

Cette action oblige le test Robo à attendre qu'un élément apparaisse à l'écran jusqu'au délai spécifié.

Le tableau suivant répertorie les attributs requis :

Attribut	Description
"eventType": "WAIT_FOR_ELEMENT"	--
delayTime	Spécifie le délai d'attente, en millisecondes.
elementDescriptors	Identifie le widget d'interface utilisateur attendu à l'aide de la hiérarchie de l'interface utilisateur Android.

Voici un exemple d'action de script Robo qui attend jusqu'à 30 secondes qu'un widget d'interface utilisateur avec l'ID de ressource "my.app.package:id/confirmation_button" apparaisse à l'écran :

{
  "eventType": "WAIT_FOR_ELEMENT",
  "delayTime": 30000,
  "elementDescriptors": [
    {
      "resourceId": "my.app.package:id/confirmation_button"
    }
  ]
}

Prochaines étapes

• Apprenez à exécuter un script Robo .

,

Ce document fournit des informations de référence sur les scripts Robo, y compris la structure, les capacités, l'utilisation, l'enregistrement et les actions. Les scripts robotiques sont des tests qui automatisent les tâches manuelles d'assurance qualité (QA) pour les applications mobiles et permettent l'intégration continue (CI) et les stratégies de test de pré-lancement. Un script Robo est un fichier JSON qui décrit une séquence d'interface utilisateur (UI) et d'autres actions.

Vous pouvez créer un script Robo des manières suivantes :

• Utilisez la fonction d'enregistrement de script Robo.
• Créez le script Robo manuellement.
• Enregistrez le script Robo, puis modifiez-le manuellement.

Pour en savoir plus sur l'utilisation des scripts Robo, consultez Exécuter un script Robo .

Le script Robo est fourni au test Robo avec d'autres entrées telles que le package d'application Android (APK) de l'application en cours de test.

Voici un exemple de script Robo qui connecte un utilisateur à une application, qui est déclenchée lorsque l'application en cours de test est lancée :

[
  {
    "crawlStage": "crawl",
    "contextDescriptor": {
      "condition": "app_under_test_shown"
    },
    "actions": [
      {
        "eventType": "VIEW_TEXT_CHANGED",
        "replacementText": "user123",
        "elementDescriptors": [
          {
            "resourceId": "my.app.package:id/username"
          }
        ]
      },
      {
        "eventType": "VIEW_TEXT_CHANGED",
        "replacementText": "12345",
        "elementDescriptors": [
          {
            "resourceId": "my.app.package:id/password"
          }
        ]
      },
      {
        "eventType": "VIEW_CLICKED",
        "elementDescriptors": [
          {
            "resourceId": "my.app.package:id/login"
          }
        ]
      }
    ]
  }
]

S'il y a un seul script Robo dans un fichier et qu'il a la condition de déclenchement par défaut app_under_test_shown , comme dans l'exemple ci-dessus, alors vous pouvez spécifier le script Robo dans un fichier en utilisant un format plus simple - juste comme une séquence de ses actions :

[
  {
    "eventType": "VIEW_TEXT_CHANGED",
    "replacementText": "user123",
    "elementDescriptors": [
      {
        "resourceId": "my.app.package:id/username"
      }
    ]
  },
  {
    "eventType": "VIEW_TEXT_CHANGED",
    "replacementText": "12345",
    "elementDescriptors": [
      {
        "resourceId": "my.app.package:id/password"
      }
    ]
  },
  {
    "eventType": "VIEW_CLICKED",
    "elementDescriptors": [
      {
        "resourceId": "my.app.package:id/login"
      }
    ]
  }
]

Structure

Un script Robo a plusieurs attributs qui décrivent comment Robo l'exécute. La plupart de ces attributs sont facultatifs avec des valeurs par défaut prédéfinies :

Attribut	Description
id	Un nombre entier qui permet de suivre ce script Robo dans les sorties d'analyse.
description	Similaire à id mais plus descriptif.
crawlStage	L'étape d'un crawl Robo applique ce script Robo à. Par défaut, il s'agit de l'étape de crawl principale.
priority	La priorité de ce script Robo par rapport aux autres scripts Robo. Par défaut, tous les scripts Robo ont une priorité de 1 .
maxNumberOfRuns	Spécifie combien de fois pendant une analyse Robo peut exécuter ce script Robo. Par défaut, Robo peut exécuter un script Robo une seule fois.
contextDescriptor	Décrit le contexte/la condition qui déclenche ce script Robo. Si elle est omise, la condition de déclenchement de ce script Robo est considérée comme toujours remplie ; en d'autres termes, le script Robo est inconditionnel.
actions	Toutes les actions de ce script Robo.

Un seul fichier contient une collection d'un ou plusieurs scripts Robo.

Voici un exemple de fichier avec deux scripts Robo inconditionnels, chacun avec une seule action exécutée une fois au début d'un crawl :

[
  {
    "id": 1000,
    "description": "My first Robo script",
    "actions": [
      {
        "eventType": "DISABLE_KEYBOARD"
      }
    ]
  },
  {
    "id": 1001,
    "description": "My second Robo script",
    "actions": [
      {
        "eventType": "PRESSED_BACK"
      }
    ]
  }
]

Descripteur de contexte

Un descripteur de contexte définit le contexte/la condition qui déclenche un script Robo à l'aide d'un ou d'une combinaison de plusieurs attributs :

Attribut	Description
"condition": "element_present"	Vérifie qu'un widget d'interface utilisateur qui correspond à elementDescriptors ou au texte spécifié par visionText est présent à l'écran.
"condition": "element_disabled"	Vérifie qu'un widget d'interface utilisateur qui correspond à elementDescriptors est présent à l'écran et qu'il est impossible d'interagir avec lui.
"condition": "element_checked"	Vérifie qu'un widget d'interface utilisateur qui correspond à elementDescriptors est présent à l'écran et est coché.
"condition": "app_under_test_shown"	Vérifie que l'application en cours de test s'exécute au premier plan.
"condition": "default_launcher_shown"	Vérifie que l'écran d'accueil d'un appareil s'affiche, ce qui signifie qu'aucune application n'est en cours d'exécution au premier plan.
"condition": "non_roboscript_action_performed"	Vérifie que la dernière action effectuée par le test Robo n'est pas une action de script Robo.
negateCondition	Si défini sur true , annule la condition . Par exemple, vous pouvez utiliser cet attribut pour vérifier si un widget d'interface utilisateur n'est PAS présent à l'écran ou si l'application en cours de test ne s'exécute PAS au premier plan.
elementDescriptors	Un ou plusieurs descripteurs d'élément qui identifient un widget d'interface utilisateur à l'écran. Il est utilisé en combinaison avec les conditions element_present , element_disabled et element_checked . Mutuellement exclusif avec visionText . Pour plus d'informations, voir Descripteurs d'éléments .
visionText	Le texte à l'écran est détecté à l'aide de l'API de reconnaissance optique de caractères (OCR). visionText est utilisé en combinaison avec la condition element_present . Mutuellement exclusif avec elementDescriptors .

Voici un exemple de script Robo déclenché par un widget d'interface utilisateur avec un ID de ressource "my.app.package:id/page_header" présent à l'écran :

{
  "id": 1000,
  "contextDescriptor": {
    "condition": "element_present",
    "elementDescriptors": [
      {
        "resourceId": "my.app.package:id/page_header"
      }
    ]
  },
  "actions": [
    {
      "eventType": "VIEW_CLICKED",
      "elementDescriptors": [
        {
          "text": "Settings"
        }
      ]
    }
  ]
}

The following is an example of a Robo script that is triggered by "Privacy Policy" detected by Optical Character Recognition (OCR):

{
  "id": 1000,
  "description": "Vision text Robo script",
  "contextDescriptor": {
    "condition": "element_present",
    "visionText": "Privacy Policy"
  },
  "actions": [
    {
      "eventType": "VIEW_CLICKED",
      "visionText": "Privacy Policy"
    }
  ]
}

The following is an example of a Robo script that waits for 5 seconds after every non-script Robo action:

{
  "contextDescriptor": {
    "condition": "non_roboscript_action_performed"
  },
  "maxNumberOfRuns" : 1000,
  "actions" : [
    {
      "eventType" : "DELAYED_MESSAGE_POSTED",
      "delayTime" : 5000
    }]
}

Actions

Each action in a Robo script is represented as a bundle of one or more attribute-value pairs, which are described in the following table:

Attribute	Description
eventType	Specifies the type of the action, for example, click, text edit, etc. Required for every action.
elementDescriptors	Descriptors that identify a UI widget. Required for all actions that have a target UI widget, like clicking a particular button.
optional	If set to true , this action is skipped when it cannot be performed. For example, this action is skipped when it can't find its target UI widget on a screen– without failing the containing Robo script. By default, the value is false .
replacementText	The text to input into the target UI widget. Required for text editing actions.
swipeDirection	Specifies the direction of the swipe. Required for swipe actions.
delayTime	Specifies how long to wait, in milliseconds. Required for wait actions.
pointTapXCoordinate and pointTapYCoordinate	The pixel X and Y coordinates of the tapped point. Mutually exclusive with pointTapXPercent and pointTapYPercent . Required for point tap actions.
pointTapXPercent and pointTapYPercent	The percentage X and Y coordinates of the tapped point. Mutually exclusive with pointTapXCoordinate and pointTapYCoordinate . Required for point tap actions.

The following is an example of a Robo script with two actions without target UI widgets, which means that these actions don't operate on a specific UI widget:

[
  {
    "eventType": "DELAYED_MESSAGE_POSTED",
    "delayTime": 3000
  },
  {
    "eventType": "PRESSED_BACK"
  }
]

Element descriptors

An element descriptor identifies a UI widget using one or more of the following identifying attributes:

Attribute	Description
className	–
ancestorClassName	Class name of the element's UI hierarchy ancestor. An ancestor is any of the parent nodes in the element's UI hierarchy, including the element itself.
resourceId	–
resourceIdRegex	Java regular expression to match resourceId .
contentDescription	–
contentDescriptionRegex	Java regular expression to match contentDescription .
text (that appears on the screen)	–
textRegex	Java regular expression to match text .
groupViewChildPosition , recyclerViewChildPosition , or adapterViewChildPosition	Represents a UI widget's child position depending on the kind of its parent widget.

Frequently, these attributes are undefined, for example, a button might not have text and content description. Even if some attribute values are present, they might not be unique on a given app screen (including resourceId ).

For example, differentiating between items of a list is commonly possible only by using their different child positions within their parent widget. This means that using just one element descriptor to identify a UI widget is usually insufficient. Therefore, an action's elementDescriptors attribute contains a sequence of element descriptors that are ordered such that the first one corresponds to the target UI widget, the second one corresponds to the target UI widget's parent widget, and so on. An action's target UI widget is matched when all of its element descriptors match the corresponding UI widget sub-hierarchy.

The following is an example of a Robo script with a text change and click actions, both of which require you to identify the target UI widget using the provided element descriptors:

[
  {
    "eventType": "VIEW_TEXT_CHANGED",
    "replacementText": "John",
    "elementDescriptors": [
      {
        "className": "android.support.v7.widget.AppCompatEditText",
        "groupViewChildPosition": 0,
        "resourceId": "com.google.samples.apps.topeka:id/first_name"
      },
      {
        "className": "android.widget.FrameLayout",
        "groupViewChildPosition": 0
      },
      {
        "className": "android.support.design.widget.TextInputLayout",
        "groupViewChildPosition": 1
      }
    ]
  },
  {
    "eventType": "VIEW_CLICKED",
    "elementDescriptors": [
      {
        "className": "android.support.design.widget.FloatingActionButton",
        "groupViewChildPosition": 1,
        "resourceId": "com.google.samples.apps.topeka:id/done"
      },
      {
        "className": "android.widget.FrameLayout",
        "groupViewChildPosition": 1,
        "resourceId": "com.google.samples.apps.topeka:id/content"
      },
      {
        "className": "android.widget.FrameLayout",
        "groupViewChildPosition": 0,
        "resourceId": "com.google.samples.apps.topeka:id/sign_in_content"
      }
    ]
  }
]

Execution options

You can optionally prefix the list of actions in a Robo script with a JSON object that specifies the execution options for that Robo script. This configuration header starts with the roboscript keyword followed by a JSON representation of the desired execution options.

Robo scripts support the following execution options:

• executionMode - execution options applied when a Robo script is running:
  • strict - if set to true , Robo script does not employ partial matching, skipping current action, and suspension . That is, the Robo script is executed as a regular instrumentation test and fails as soon as any of its actions cannot be performed.
• postscript - execution options applied after a Robo script is completed:
  • terminate - if set to true , Robo test stops crawling after the Robo script is completed.

The following is an example of a Robo script executed in strict mode that sleeps for three seconds, after which the crawl stops:

"roboscript": {
  "executionMode": {
    "strict": true
  },
  "postscript": {
    "terminate": true
  }
}
[
  {
    "eventType": "DELAYED_MESSAGE_POSTED",
    "delayTime": 3000
  }
]

Template parameters

A template parameter is a placeholder in a Robo script that is replaced with the actual value when Robo test loads that Robo script for execution. Template parameters are prefixed with a double underscore followed by a percent sign, and are postfixed with a percent sign followed by a double underscore.

Robo scripts support the following template parameter:

• __%APP_PACKAGE_NAME%__ - the package name of the app-under-test.

The following is an example of a Robo script that stops the app-under-test process:

[
  {
    "eventType": "ADB_SHELL_COMMAND",
    "command": "am force-stop __%APP_PACKAGE_NAME%__"
  }
]

Comments

A Robo script can contain comment lines, which are lines that start with # or // .

The following is an example of a Robo script with a couple of comments:

# Confirm a user account.
[
  {
    // Click the DONE button.
    "eventType": "VIEW_CLICKED",
    "elementDescriptors": [
      {
        "resourceId": "com.google.samples.apps.topeka:id/done"
      }
    ]
  }
]

Capabilities

By default, until all actions of a Robo script are completed (or at least attempted), the Robo script remains active. Robo test keeps trying to match a Robo script action whenever it is picking an action to perform. Robo script employs the following techniques to increase robustness:

Technique	Description
Partial matching	If the current Robo script action cannot be fully matched, the matching criteria are relaxed and the matching is retried. The partial matching doesn't consider the outermost element descriptor while matching the target UI widget of a Robo script action. If the partial matching succeeds, the corresponding Robo script action is performed as usual. This technique supports scenarios in which the app structure changes, for example, between app versions, when screen elements are rearranged.
Skip current action	If the current Robo script action cannot be fully or partially matched, Robo tries to match the subsequent Robo script action. If the subsequent action fully or partially matches, Robo test skips (and never returns to) the current Robo script action and performs the subsequent one. This technique supports scenarios when app behavior changes between versions or is flaky, for example, when an intermittent dialog might appear at different screens during recording versus replaying of a Robo script.
Suspend	If neither current nor subsequent Robo script actions can be fully or partially matched, Robo script is temporarily suspended and Robo test picks an action to perform using its other strategies. After this action is completed, Robo test resumes executing the Robo script. As long as current or subsequent Robo script actions cannot be matched, Robo script remains suspended for any number of actions. Thus, Robo scripts do not necessarily need to be a prologue for a Robo test, and you can intersperse Robo script actions with standard Robo test actions. This technique supports scenarios when app behavior is flaky, or when changes between app versions are large enough that Robo test needs to "fill in the gaps" with its standard actions.

Priorities

If a Robo script reaches its maxNumberOfRuns , it can no longer be triggered in a given crawl. If more than one Robo script can be triggered by the current context, priority is given by choosing, in the following order, the Robo script that:

1. Has a contextDescriptor attribute.
2. Has the highest priority (by default, all Robo scripts have the same execution priority of 1 ).
3. Appears earliest in the list of the Robo scripts, if Robo scripts' priorities are the same.

The following is an example of a file with three Robo scripts that perform the same action and are triggered by the same condition - the app-under-test being in the foreground:

[
  {
    "id": 1000,
    "description": "Robo script 1",
    "contextDescriptor": {
      "condition": "app_under_test_shown"
    },
    "actions": [
      {
        "eventType": "DELAYED_MESSAGE_POSTED",
        "delayTime": 3000
      }
    ]
  },
  {
    "id": 1001,
    "description": "Robo script 2",
    "priority": "2",
    "contextDescriptor": {
      "condition": "app_under_test_shown"
    },
    "actions": [
      {
        "eventType": "DELAYED_MESSAGE_POSTED",
        "delayTime": 3000
      }
    ]
  },
  {
    "id": 1002,
    "description": "Robo script 3",
    "contextDescriptor": {
      "condition": "app_under_test_shown"
    },
    "actions": [
      {
        "eventType": "DELAYED_MESSAGE_POSTED",
        "delayTime": 3000
      }
    ]
  }
]

When the app-under-test is in the foreground, Robo triggers the following, in order:

1. "Robo script 2" because it has the highest priority.
2. "Robo script 1" because it appears earlier among the remaining applicable Robo scripts with the same priority.
3. "Robo script 3" as the last applicable Robo script.

Repeated runs

By default, Robo triggers a Robo script at most once during a crawl. This can be adjusted via the maxNumberOfRuns attribute.

The following is an example of a Robo script that brings the app-under-test into the background for up to 10 times:

{
  "id": 1000,
  "maxNumberOfRuns": 10,
  "contextDescriptor": {
    "condition": "app_under_test_shown"
  },
  "actions": [
    {
      "eventType": "GO_HOME"
    }
  ]
}

Crawl stage

Robo scripts are applicable at different stages of a given Robo crawl:

Crawl stage	Description
pre_crawl	Before Robo launches and starts crawling the app-under-test.
post_crawl	After Robo finishes crawling the app-under-test.
crawl	The main crawl stage, when Robo crawls the app-under-test.
close_screen	When Robo tries to return back (backtrack) from a given screen, when all possible actions on this screen are explored. By default, Robo presses back, which is undesirable in some scenarios.

If the crawlStage attribute of a Robo script is unspecified, it is implied to be crawl .

The following is an example of a Robo script that clears the app-under-test user data before Robo starts crawling it:

{
  "id": 1000,
  "crawlStage": "pre_crawl",
  "actions": [
    {
      "eventType": "ADB_SHELL_COMMAND",
      "command": "pm clear __%APP_PACKAGE_NAME%__"
    }
  ]
}

The following is an example of a Robo script that instructs Robo to click "Cancel" whenever it tries to return back (backtrack) from a confirmation dialog:

{
  "id": 1000,
  "crawlStage": "close_screen",
  "maxNumberOfRuns": 999,
  "contextDescriptor": {
    "condition": "element_present",
    "elementDescriptors": [
      {
        "resourceId": "my.app.package:id/confirmation_dialog"
      }
    ]
  },
  "actions": [
    {
      "eventType": "VIEW_CLICKED",
      "elementDescriptors": [
        {
          "text": "Cancel"
        }
      ]
    }
  ]
}

Conditional actions

A Robo script can contain conditional actions. Conditional actions have three additional attributes that describe how Robo performs them:

Attribute	Description
priority	The priority of this conditional action in comparison to other conditional actions within its containing Robo script. By default, all conditional actions have a priority of 1 .
maxNumberOfRuns	How many times this conditional action can be performed during one execution of its containing Robo script. By default, all conditional actions can be performed at most once in a single execution of their containing Robo script.
contextDescriptor	The context/condition that triggers this conditional action. It has the same structure and offers similar capabilities as [the Robo script's contextDescriptor](#context-descriptor).

When triggered, a Robo script performs its non-conditional actions one by one in order of appearance. If a Robo script contains conditional actions, then they are considered every time before picking a non-conditional action to perform. If any conditional action is triggered and picked based on its priority and the remaining number of runs, then the Robo script performs this conditional action. Otherwise, the Robo script performs the following non-conditional action. To be valid, a Robo script must contain at least one non-conditional action.

The following is an example of an unconditional Robo script with a conditional action that dismisses popup dialogs if they show up at any point during the Robo script execution:

{
  "id": 1000,
  "actions": [
    {
      "description": "Dismiss popup",
      "maxNumberOfRuns": 100,
      "contextDescriptor": {
        "condition": "default_launcher_shown",
        "negateCondition": true
      },
      "eventType": "GO_HOME"
    },
    {
      "description": "Screen off",
      "eventType": "ADB_SHELL_COMMAND",
      "command": "input keyevent 26"
    },
    {
      "description": "Wait for 10 seconds",
      "eventType": "DELAYED_MESSAGE_POSTED",
      "delayTime": 10000
    },
    {
      "description": "Screen on",
      "eventType": "ADB_SHELL_COMMAND",
      "command": "input keyevent 82"
    },
    {
      "description": "Wait for 10 seconds",
      "eventType": "DELAYED_MESSAGE_POSTED",
      "delayTime": 10000
    }
}

Ignoring actions

A Robo script can contain instructions for Robo to ignore specific UI widgets or all UI widgets on a particular screen. These instructions are represented as ignoring "actions" with eventType ELEMENT_IGNORED and ALL_ELEMENTS_IGNORED correspondingly.

Whenever the contextDescriptor attribute of a Robo script containing ignoring actions matches a given screen, Robo does not interact with any UI widgets targeted by its ignoring actions (unless some other Robo script action makes Robo perform an action on one of the ignored UI widgets).

A Robo script can contain a mix of ignoring, conditional, and non-conditional actions. Unlike other Robo script actions, ignoring actions are applied as long as their containing Robo script's contextDescriptor matches a screen during a Robo crawl, regardless of the values of the priority and maxNumberOfRuns attributes.

The following is an example of a file with two Robo scripts. The first Robo script makes Robo ignore all UI widgets on a screen containing a UI widget with a resource ID "my.app.package:id/ignored_screen" . The second Robo script makes Robo ignore UI widgets whose resource IDs match Java regex ".*:id/done" on a screen containing a UI widget with a resource ID "my.app.package:id/main_screen" :

[
  {
    "id": 1000,
    "contextDescriptor": {
      "condition": "element_present",
      "elementDescriptors": [
        {
          "resourceId": "my.app.package:id/ignored_screen"
        }
      ]
    },
    "actions": [
      {
        "eventType": "ALL_ELEMENTS_IGNORED"
      }
    ]
  },
  {
    "id": 1001,
    "contextDescriptor": {
      "condition": "element_present",
      "elementDescriptors": [
        {
          "resourceId": "my.app.package:id/main_screen"
        }
      ]
    },
    "actions": [
      {
        "eventType": "ELEMENT_IGNORED",
        "elementDescriptors": [
          {
            "resourceIdRegex": ".*:id/done"
          }
        ]
      }
    ]
  }
]

RecyclerView and AdapterView support

Children of RecyclerView and AdapterView widgets are loaded dynamically and might be displayed many swipes away from the current screen. Since the size of a screen, and the number of swipes required to get to this child, is different for different device form factors, it is much more robust to rely on the child's data position, which is absolute. It is a less robust approach to rely on the number of swipes that are required to bring this child to the screen and then use its screen position.

Therefore, Robo script captures the absolute data positions of RecyclerView children that are targets of Robo script actions as recyclerViewChildPosition . Robo script also captures the absolute data positions of AdapterView children that are targets of Robo script actions as adapterViewChildPosition .

Actions on RecyclerView and AdapterView children are performed in the following steps:

1. Robo test ensures that the corresponding child is displayed on the screen through a positioning action on its containing RecyclerView or AdapterView.

2. Robo test performs the recorded action directly on the child element, since it is already displayed on the screen.

The following is an example of a click action on an AdapterView ( android.widget.GridView ) child:

{
  "eventType": "VIEW_CLICKED",
  "elementDescriptors": [
    {
      "className": "com.google.samples.apps.topeka.widget.AvatarView",
      "adapterViewChildPosition": 5,
      "resourceId": "com.google.samples.apps.topeka:id/avatar",
      "contentDescription": "Avatar 6"
    },
    {
      "className": "android.widget.GridView",
      "groupViewChildPosition": 1,
      "resourceId": "com.google.samples.apps.topeka:id/avatars"
    },
    {
      "className": "android.widget.LinearLayout",
      "groupViewChildPosition": 1
    },
    {
      "className": "android.widget.LinearLayout",
      "groupViewChildPosition": 0
    }
  ]
}

The following is an example of a click action on a RecyclerView ( android.support.v7.widget.RecyclerView ) child:

{
  "eventType": "VIEW_CLICKED",
  "elementDescriptors": [
    {
      "className": "android.support.v7.widget.AppCompatTextView",
      "groupViewChildPosition": 1,
      "resourceId": "com.google.samples.apps.topeka:id/category_title"
    },
    {
      "className": "android.widget.FrameLayout",
      "recyclerViewChildPosition": 8,
      "resourceId": "com.google.samples.apps.topeka:id/category_item"
    },
    {
      "className": "android.support.v7.widget.RecyclerView",
      "groupViewChildPosition": 1,
      "resourceId": "com.google.samples.apps.topeka:id/categories"
    },
    {
      "className": "android.widget.FrameLayout",
      "groupViewChildPosition": 1,
      "resourceId": "com.google.samples.apps.topeka:id/category_container"
    },
    {
      "className": "android.widget.LinearLayout",
      "groupViewChildPosition": 0
    }
  ]
}

Record a Robo script in Android Studio and run it in Test Lab

You can create a Robo script in Android Studio, which saves the script as a JSON file. You can then upload the JSON file to Firebase Test Lab with the application and run the test accordingly.

When you run a Robo test with a script attached, Robo test first steps through your pre-scripted actions and then explores the app as usual.

To create a Robo script JSON file in Android Studio, follow the steps in Record a Robo script using Test Lab in Android Studio .

Robo script actions

The following common optional attribute applies to all actions:

• description - helps track execution of this Robo script action in Robo test outputs.

Assertion

If the asserted condition is true, the Robo script continues to the next action, which could be another assertion. Otherwise, the Robo script execution is halted due to a failed assertion.

The following table lists required attributes:

Attribute	Description
"eventType": "ASSERTION"	--
contextDescriptor	Describes the asserted context or condition. It has the same structure and offers similar capabilities as the Robo script's contextDescriptor .

The following is an example of a Robo script assertion that checks that the app-under-test is in the foreground:

{
  "eventType": "ASSERTION",
  "contextDescriptor": {
    "condition": "app_under_test_shown"
  }
}

The following is an example of a Robo script assertion that checks that a UI widget with the resource ID "com.google.samples.apps.topeka:id/done" is present on a screen:

{
  "eventType": "ASSERTION",
  "contextDescriptor": {
    "condition": "element_present",
    "elementDescriptors": [
      {
        "resourceId": "com.google.samples.apps.topeka:id/done"
      }
    ]
  }
}

The following is an example of a Robo script assertion that checks that "Settings" is NOT detected on a screen using OCR:

{
  "eventType": "ASSERTION",
  "contextDescriptor": {
    "condition": "element_present",
    "negateCondition": true,
    "visionText": "Settings"
  }
}

Click

The following table lists required attributes:

Attribute	Description
eventType	Specifies the type of the Robo script action.
"eventType": "VIEW_CLICKED"	Clicks the target element of the app-under-test.
"eventType": "SOFT_KEYBOARD_CLICK"	Clicks the target element of the soft keyboard.
"eventType": "SOFT_KEYBOARD_RANDOM_CLICK"	Clicks random elements of the soft keyboard up to maxNumberOfRuns times.
"eventType": "LIST_ITEM_CLICKED"	Used by the Robo script recorder in Android Studio for clicking list items.
elementDescriptors	Identifies the clicked UI widget using the Android UI hierarchy. Mutually exclusive with visionText .
visionText	Identifies the clicked element using OCR. Mutually exclusive with elementDescriptors .
maxNumberOfRuns	Specifies how many times to click a random element of the soft keyboard, when eventType is SOFT_KEYBOARD_RANDOM_CLICK . The default value is 1 .

The following is an example of a Robo script action that clicks a button with the resource ID "com.google.samples.apps.topeka:id/done" :

{
  "eventType": "VIEW_CLICKED",
  "elementDescriptors": [
    {
      "resourceId": "com.google.samples.apps.topeka:id/done"
    }
  ]
}

The following is an example of a Robo script action that clicks on "Privacy Policy" detected on a screen using OCR:

{
  "eventType": "VIEW_CLICKED",
  "visionText": "Privacy Policy"
}

The following is an example of a Robo script action that clicks a soft keyboard element with a content description "Emoji button" :

{
  "eventType": "SOFT_KEYBOARD_CLICK",
  "elementDescriptors": [
    {
      "contentDescription": "Emoji button"
    }
  ]
}

The following is an example of a Robo script action that clicks random soft keyboard elements up to five times:

{
  "eventType": "SOFT_KEYBOARD_RANDOM_CLICK",
  "maxNumberOfRuns": 5
}

Disable soft keyboard

The following table lists required attributes:

Attribute	Description
"eventType": "DISABLE_KEYBOARD"	--

The following is an example of a Robo script action that disables the soft keyboard:

{
  "eventType": "DISABLE_KEYBOARD"
}

Execute adb shell command

The following table lists required attributes:

Attribute	Description
"eventType": "ADB_SHELL_COMMAND"	--
command	The Android Debug Bridge (adb) shell command to execute.

The following is an example of a Robo script action that clears the app-under-test user data:

{
  "eventType": "ADB_SHELL_COMMAND",
  "command": "pm clear __%APP_PACKAGE_NAME%__"
}

Grant permissions

This action is recorded by the Robo script recorder in Android Studio for backward compatibility with Espresso Test Recorder . Robo test grants all permissions to the app-under-test at the beginning of every crawl, and thus, this action is a no-op. Do NOT use this action in your Robo scripts.

The following table lists required attributes:

Attribute	Description
"eventType": "PERMISSIONS_REQUEST"	--

Ignore all elements on a screen

This action makes Robo ignore all elements on any screen that triggers the containing Robo script.

The following table lists required attributes:

Attribute	Description
"eventType": "ALL_ELEMENTS_IGNORED"	--

The following is an example of a Robo script action that makes Robo ignore all elements on a screen:

{
  "eventType": "ALL_ELEMENTS_IGNORED"
}

Ignore an element

This action makes Robo ignore an element (or elements) that match the specified elementDescriptors .

The following table lists required attributes:

Attribute	Description
"eventType": "ELEMENT_IGNORED"	--
elementDescriptors	Identifies the ignored UI widget(s) using the Android UI hierarchy.

The following is an example of a Robo script action that makes Robo ignore all elements, whose content descriptions start with "Avatar" :

{
  "eventType": "ELEMENT_IGNORED",
  "elementDescriptors": [
    {
      "contentDescriptionRegex": "Avatar.*"
    }
  ]
}

Input text

The following table lists required attributes:

Attribute	Description
eventType	Specifies the type of the Robo script action.
"eventType": "VIEW_TEXT_CHANGED"	Inputs the given text into the target UI widget.
"eventType": "ENTER_TEXT"	inputs the given text into the target UI widget and then sends a KEYCODE_ENTER event to this UI widget.
elementDescriptors	Identifies the target UI widget using the Android UI hierarchy.
replacementText	The text to input into the target UI widget.

The following is an example of a Robo script action that inputs "John" into a UI widget with the resource ID "com.google.samples.apps.topeka:id/first_name" :

{
  "eventType": "VIEW_TEXT_CHANGED",
  "replacementText": "John",
  "elementDescriptors": [
    {
      "resourceId": "com.google.samples.apps.topeka:id/first_name"
    }
  ]
}

Long click

The following table lists required attributes:

Attribute	Description
"eventType": "VIEW_LONG_CLICKED"	--
elementDescriptors	Identifies the target UI widget using the Android UI hierarchy.

The following attribute is optional:

• delayTime - specifies how long the press down of a long click lasts, in milliseconds.

The following is an example of a Robo script action that performs a five seconds-long click on a UI widget with content description "Avatar 8" :

{
  "eventType": "VIEW_LONG_CLICKED",
  "elementDescriptors": [
    {
      "contentDescription": "Avatar 8"
    }
  ],
  "delayTime": 5000
}

Perform a one-point gesture

The following table lists required attributes:

Attribute	Description
"eventType": "ONE_POINT_GESTURE"	--
coordinates	Two coordinates for a one-point gesture, formatted as "(x1,y1)->(x2,y2)" as percentages or pixels.

The following attribute is optional:

• dragAndDrop - if set to true , the one-point gesture performs a drag-and-drop action. By default, it is false .

The following is an example of a Robo script one-point gesture action that performs a swipe down:

{
  "eventType": "ONE_POINT_GESTURE",
  "coordinates": "(50%,25%)->(50%,75%)"
}

Perform a two-point gesture

The following table lists required attributes:

Attribute	Description
"eventType": "TWO_POINT_GESTURE"	--
coordinates	Four coordinates for a two-point gesture, formatted as "(x1,y1)->(x2,y2),(x3,y3)->(x4,y4)" as percentages or pixels.

The following is an example of a Robo script action that performs a pinch out gesture:

{
  "eventType": "TWO_POINT_GESTURE",
  "coordinates": "(50%,50%)->(25%,50%),(50%,50%)->(75%,50%)"
}

Perform an IME action

This action presses the current action button, for example, next, done, and search, on the Input Method Editor (IME) for the specified target UI widget.

The following table lists required attributes:

Attribute	Description
"eventType": "PRESSED_EDITOR_ACTION"	--
elementDescriptors	Identifies the target UI widget using the Android UI hierarchy.

The following is an example of a Robo script action that performs an IME action on a UI widget with the resource ID "com.google.samples.apps.topeka:id/first_name" :

{
  "eventType": "PRESSED_EDITOR_ACTION",
  "elementDescriptors": [
    {
      "resourceId": "com.google.samples.apps.topeka:id/first_name"
    }
  ]
}

Press back

The following table lists required attributes:

Attribute	Description
eventType	Specifies the type of the Robo script action.
"eventType": "PRESSED_BACK"	Sends a KEYCODE_BACK event to the device.
"eventType": "PRESSED_BACK_EMULATOR_28"	Used by the Robo script recorder in Android Studio for pressing back on emulators API 28.

The following is an example of a Robo script action that presses back:

{
  "eventType": "PRESSED_BACK"
}

Press home

This action sends a KEYCODE_HOME event to the device.

The following table lists required attributes:

Attribute	Description
"eventType": "GO_HOME"	--

The following is an example of a Robo script action that presses home:

{
  "eventType": "GO_HOME"
}

Scroll an element into view

This action makes Robo test scroll forward the UI widget that matches the specified elementDescriptors until the UI widget that matches the specified childElementDescriptors is present on the screen, or the scrolled widget can no longer be scrolled, or the max number of 50 scrolls is reached.

The following table lists required attributes:

Attribute	Description
"eventType": "ELEMENT_SCROLL_INTO_VIEW"	--
elementDescriptors	Identifies the scrolled UI widget using the Android UI hierarchy.
childElementDescriptors	Identifies the UI widget to scroll to using the Android UI hierarchy.

The following is an example of a Robo script action that scrolls the UI widget with the resource ID "my.app.package:id/scrollable_card_container" until the UI widget with text "Orange" is present on the screen (or no more scrolls can be performed, or the max number of 50 scrolls is reached):

{
  "eventType": "ELEMENT_SCROLL_INTO_VIEW",
  "elementDescriptors": [
    {
      "resourceId": "my.app.package:id/scrollable_card_container"
    }
  ],
  "childElementDescriptors": [
    {
      "text": "Orange"
    }
  ]
}

Swipe

The following table lists required attributes:

Attribute	Description
"eventType": "VIEW_SWIPED"	--
swipeDirection	Specifies the direction of the swipe: Left Right Up Down Forward - either Down or Right depending on vertical or horizontal scrollability of the target UI widget. Backward - either Up or Left depending on vertical or horizontal scrollability of the target UI widget.
elementDescriptors	Identifies the target UI widget using the Android UI hierarchy.

The following is an example of a Robo script action that swipes up a UI widget with the resource ID "my.app.package:id/custom_content" :

{
  "eventType": "VIEW_SWIPED",
  "swipeDirection": "Up",
  "elementDescriptors": [
    {
      "resourceId": "my.app.package:id/custom_content"
    }
  ]
}

Take screenshot

The following table lists required attributes:

Attribute	Description
"eventType": "TAKE_SCREENSHOT"	--
screenshotName	Specifies the screenshot file name.

The following is an example of a Robo script action that takes a screenshot:

{
  "eventType": "TAKE_SCREENSHOT",
  "screenshotName": "my_screenshot"
}

Tap a point on the screen

The following table lists required attributes:

Attribute	Description
"eventType": "POINT_TAP"	--
pointTapXCoordinate	The pixel X coordinate of the tapped point. Mutually exclusive with pointTapXPercent and pointTapYPercent .
pointTapYCoordinate	The pixel Y coordinate of the tapped point. Mutually exclusive with pointTapXPercent and pointTapYPercent .
pointTapXPercent	The percentage X coordinate of the tapped point. Mutually exclusive with pointTapXCoordinate and pointTapYCoordinate .
pointTapYPercent	The percentage Y coordinate of the tapped point. Mutually exclusive with pointTapXCoordinate and pointTapYCoordinate .

The following is an example of a Robo script action that taps in the middle of a screen:

{
  "eventType": "POINT_TAP",
  "pointTapXPercent": 50,
  "pointTapYPercent": 50
}

Tap a point within an element

The following table lists required attributes:

Attribute	Description
"eventType": "POINT_TAP_ELEMENT"	--
pointTapXPercent	The percentage X coordinate within the target element.
pointTapYPercent	The percentage Y coordinate within the target element.
elementDescriptors	Identifies the target UI widget using Android UI hierarchy.

The following is an example of a Robo script action that moves a seekbar's slider to the right:

{
  "eventType": "POINT_TAP_ELEMENT",
  "pointTapXPercent": 80,
  "pointTapYPercent": 50,
  "elementDescriptors": [
    {
      "resourceId": "my.app.package:id/my_seekbar"
    }
  ]
}

Terminate crawl

This action stops the Robo test.

The following table lists required attributes:

Attribute	Description
"eventType": "TERMINATE_CRAWL"	--

The following is an example of a Robo script action that stops a Robo test:

{
  "eventType": "TERMINATE_CRAWL"
}

Wait

The following table lists required attributes:

Attribute	Description
"eventType": "DELAYED_MESSAGE_POSTED"	--
delayTime	Specifies how long to wait, in milliseconds.

The following is an example of a Robo script action that waits for three seconds:

{
  "eventType": "DELAYED_MESSAGE_POSTED",
  "delayTime": 3000
}

Wait for an element

This action makes Robo test wait for an element to appear on the screen up to the specified timeout.

The following table lists required attributes:

Attribute	Description
"eventType": "WAIT_FOR_ELEMENT"	--
delayTime	Specifies the waiting timeout, in milliseconds.
elementDescriptors	Identifies the waited-for UI widget using the Android UI hierarchy.

The following is an example of a Robo script action that waits for up to 30 seconds for a UI widget with the resource ID "my.app.package:id/confirmation_button" to appear on the screen:

{
  "eventType": "WAIT_FOR_ELEMENT",
  "delayTime": 30000,
  "elementDescriptors": [
    {
      "resourceId": "my.app.package:id/confirmation_button"
    }
  ]
}

Prochaines étapes

• Learn how to run a Robo script .