monkeyrunner

L'ancien outil monkeyrunner fournit une API permettant d'écrire des programmes qui contrôlent un appareil ou un émulateur Android en dehors du code Android.

L'outil monkeyrunner est principalement conçu pour tester des applications et des appareils au niveau de leur fonctionnalité ou de leur framework et pour exécuter des suites de tests unitaires, mais vous pouvez également l'utiliser à d'autres fins. Avec monkeyrunner, vous pouvez écrire un programme Python qui installe une application Android ou un package de test, l'exécute, lui envoie des combinaisons de touches, crée des captures d'écran de son interface utilisateur et les stocke sur le poste de travail.

Attention : L'API monkeyrunner n'est pas gérée. Nous vous recommandons plutôt d'utiliser le robot d'exploration d'applications ou le framework de test d'UI Automator.

L'outil monkeyrunner n'est pas lié à l'IU/Application Exerciser Monkey, également appelé monkey. L'outil monkey s'exécute dans un shell adb directement sur l'appareil ou l'émulateur et génère des flux pseudo-aléatoires d'événements utilisateur et système. En revanche, monkeyrunner contrôle les appareils et les émulateurs depuis un poste de travail, en envoyant des commandes et des événements spécifiques à partir d'une API.

L'outil monkeyrunner fournit les fonctionnalités suivantes pour les tests Android :

• Contrôle de plusieurs appareils : l'API monkeyrunner peut appliquer une ou plusieurs suites de tests sur plusieurs appareils ou émulateurs. Vous pouvez associer physiquement tous les appareils ou démarrer tous les émulateurs (ou les deux), vous connecter à chacun d'eux de façon automatisée, puis exécuter un ou plusieurs tests. Vous pouvez également démarrer une configuration d'émulateur de façon automatisée, exécuter un ou plusieurs tests, puis éteindre l'émulateur.
• Tests fonctionnels : monkeyrunner peut exécuter un test automatisé de bout en bout d'une application Android. Vous fournissez des valeurs d'entrée avec des combinaisons de touches ou des événements tactiles, et les résultats s'affichent sous forme de captures d'écran.
• Tests de régression : monkeyrunner peut tester la stabilité d'une application en l'exécutant et en comparant ses captures d'écran de sortie à un ensemble de captures fiables.
• Automatisation extensible : comme monkeyrunner est une boîte à outils d'API, vous pouvez développer un système de modules et de programmes basés sur Python pour contrôler les appareils Android. En plus d'avoir recours à l'API monkeyrunner elle-même, vous pouvez utiliser les modules standards Python os et subprocess pour appeler des outils Android tels qu'Android Debug Bridge.

  Vous pouvez également ajouter vos propres classes à l'API monkeyrunner. Pour en savoir plus, consultez la section Étendre monkeyrunner avec des plug-ins.

L'outil monkeyrunner utilise Jython, une implémentation de Python qui utilise le langage de programmation Java. Jython permet à l'API monkeyrunner d'interagir facilement avec le framework Android. Avec Jython, vous pouvez utiliser la syntaxe Python pour accéder aux constantes, classes et méthodes de l'API.

Un programme monkeyrunner simple

Voici un programme monkeyrunner simple qui se connecte à un appareil et crée un objet MonkeyDevice. À l'aide de l'objet MonkeyDevice, le programme installe un package d'application Android, exécute l'une de ses activités et envoie des événements clés à l'activité. Le programme effectue ensuite une capture d'écran du résultat, créant ainsi un objet MonkeyImage. À partir de cet objet, le programme écrit un fichier PNG contenant la capture d'écran.

# Imports the monkeyrunner modules used by this program.
from com.android.monkeyrunner import MonkeyRunner, MonkeyDevice

# Connects to the current device, returning a MonkeyDevice object.
device = MonkeyRunner.waitForConnection()

# Installs the Android package. Notice that this method returns a boolean, so you can test
# whether the installation worked.
device.installPackage('myproject/bin/MyApplication.apk')

# Sets a variable with the package's internal name.
package = 'com.example.android.myapplication'

# Sets a variable with the name of an Activity in the package.
activity = 'com.example.android.myapplication.MainActivity'

# Sets the name of the component to start.
runComponent = package + '/' + activity

# Runs the component.
device.startActivity(component=runComponent)

# Presses the Menu button.
device.press('KEYCODE_MENU', MonkeyDevice.DOWN_AND_UP)

# Takes a screenshot.
result = device.takeSnapshot()

# Writes the screenshot to a file.
result.writeToFile('myproject/shot1.png','png')

L'API monkeyrunner

L'API monkeyrunner se trouve dans trois modules du package com.android.monkeyrunner :

• MonkeyRunner : classe de méthodes utilitaires pour les programmes monkeyrunner. Cette classe fournit une méthode pour connecter monkeyrunner à un appareil ou à un émulateur. Elle fournit également des méthodes permettant de créer des interfaces utilisateur pour un programme monkeyrunner et d'afficher l'aide intégrée.
• MonkeyDevice : représente un appareil ou un émulateur. Cette classe fournit des méthodes pour installer et désinstaller des packages, démarrer une activité et envoyer des événements de clavier ou des événements tactiles à une application. Elle permet également d'exécuter des packages de test.
• MonkeyImage : représente une image de capture d'écran. Cette classe fournit des méthodes de capture d'écran, de conversion d'images bitmap dans divers formats, de comparaison de deux objets MonkeyImage et d'écriture d'une image dans un fichier.

Dans un programme Python, vous accédez à chaque classe en tant que module Python. L'outil monkeyrunner n'importe pas ces modules automatiquement. Pour importer un module, utilisez l'instruction Python from :

from com.android.monkeyrunner import <module>

Où <module> est le nom de classe que vous souhaitez importer. Vous pouvez importer plusieurs modules dans la même instruction from en séparant les noms des modules par des virgules.

Exécuter monkeyrunner

Vous pouvez exécuter des programmes monkeyrunner à partir d'un fichier ou en saisissant des instructions monkeyrunner dans une session interactive. Pour effectuer ces deux opérations, appelez la commande monkeyrunner, qui se trouve dans le sous-répertoire tools/ du répertoire de votre SDK. Si vous fournissez un nom de fichier en tant qu'argument, la commande monkeyrunner exécute le contenu du fichier en tant que programme Python. Sinon, elle démarre une session interactive.

Voici la syntaxe de la commande monkeyrunner :

monkeyrunner -plugin <plugin_jar> <program_filename> <program_options>

Le tableau 1 décrit les indicateurs et les arguments monkeyrunner.

Tableau 1. Options et arguments monkeyrunner

Aide intégrée de monkeyrunner

Vous pouvez générer une référence d'API pour monkeyrunner en exécutant la commande suivante :

monkeyrunner help.py <format> <outfile>

Les arguments sont les suivants :

• <format> est text pour la sortie en texte brut ou html pour la sortie HTML.
• <outfile> est un nom de chemin d'accès complet pour le fichier de sortie.

Étendre monkeyrunner avec des plug-ins

Vous pouvez étendre l'API monkeyrunner avec des classes que vous écrivez en Java, puis compilez dans un ou plusieurs fichiers JAR. Vous pouvez utiliser cette fonctionnalité pour étendre l'API monkeyrunner avec vos propres classes ou pour étendre les classes existantes. Vous pouvez également utiliser cette fonctionnalité pour initialiser l'environnement monkeyrunner.

Pour fournir un plug-in à monkeyrunner, appelez la commande monkeyrunner avec l'argument -plugin <plugin_jar> décrit dans le tableau 1.

Dans le code de votre plug-in, vous pouvez importer et étendre les principales classes monkeyrunner, à savoir MonkeyDevice, MonkeyImage et MonkeyRunner, dans com.android.monkeyrunner (consultez la section sur l'API monkeyrunner).

Notez que les plug-ins ne vous permettent pas d'accéder au SDK Android. Vous ne pouvez pas importer de packages tels que com.android.app. En effet, monkeyrunner interagit avec l'appareil ou l'émulateur en dessous du niveau des API du framework.

La classe de démarrage du plug-in

Le fichier JAR d'un plug-in peut spécifier une classe instanciée avant le début du traitement du script. Pour spécifier cette classe, ajoutez la clé MonkeyRunnerStartupRunner au fichier manifeste du fichier JAR. Pour la valeur, utilisez le nom de la classe à exécuter au démarrage. L'extrait de code suivant montre comment procéder dans un script de compilation ant :

<jar jarfile="myplugin" basedir="${build.dir}">
<manifest>
<attribute name="MonkeyRunnerStartupRunner" value="com.myapp.myplugin"/>
</manifest>
</jar>

Pour accéder à l'environnement d'exécution de l'outil monkeyrunner, la classe de démarrage peut implémenter com.google.common.base.Predicate<PythonInterpreter>. Par exemple, cette classe définit certaines variables dans l'espace de noms par défaut :

package com.android.example

import com.google.common.base.Predicate
import org.python.util.PythonInterpreter

class Main: Predicate<PythonInterpreter> {

    override fun apply(anInterpreter: PythonInterpreter): Boolean {
        /*
         * Examples of creating and initializing variables in the monkeyrunner environment's
         * namespace. During execution, the monkeyrunner program can refer to the variables
         * "newtest" and "use_emulator"
         *
         */
        anInterpreter.set("newtest", "enabled")
        anInterpreter.set("use_emulator", 1)
        return true
    }
}

package com.android.example;

import com.google.common.base.Predicate;
import org.python.util.PythonInterpreter;

public class Main implements Predicate<PythonInterpreter> {
    @Override
    public boolean apply(PythonInterpreter anInterpreter) {

        /*
        * Examples of creating and initializing variables in the monkeyrunner environment's
        * namespace. During execution, the monkeyrunner program can refer to the variables "newtest"
        * and "use_emulator"
        *
        */
        anInterpreter.set("newtest", "enabled");
        anInterpreter.set("use_emulator", 1);

        return true;
    }
}