monkeyrunner

Lo strumento monkeyrunner legacy fornisce un'API per la scrittura di programmi che controllano un emulatore o un dispositivo Android al di fuori del codice Android.

Lo strumento monkeyrunner è progettato principalmente per testare app e dispositivi a livello di funzionalità/framework e per eseguire suite di test delle unità, ma puoi utilizzarlo per altri scopi. Con monkeyrunner puoi scrivere un programma Python che installa un'app o un pacchetto di test per Android, lo esegue, invia le sequenze di tasti, acquisisce screenshot dell'interfaccia utente e archivia screenshot sulla workstation.

Attenzione: l'API monkeyrunner non viene gestita. Consigliamo di utilizzare invece lo strumento Crawler app o il framework di test UI Automator.

Lo strumento monkeyrunner non è correlato a UI/Application Exerciser Root, noto anche come strumento monkey. Lo strumento monkey viene eseguito in una shell adb direttamente sul dispositivo o nell'emulatore e genera flussi pseudo-casuali di eventi utente e di sistema. In confronto, lo strumento monkeyrunner controlla dispositivi ed emulatori da una workstation inviando comandi ed eventi specifici da un'API.

Lo strumento monkeyrunner offre le seguenti funzionalità per i test di Android:

  • Controllo di più dispositivi: l'API monkeyrunner può applicare una o più suite di test su più dispositivi o emulatori. Puoi collegare fisicamente tutti i dispositivi o avviare tutti gli emulatori (o entrambi) contemporaneamente, connetterti a ciascuno di essi in modo programmatico ed eseguire uno o più test. Puoi anche avviare la configurazione di un emulatore in modo programmatico, eseguire uno o più test e quindi disattivare l'emulatore.
  • Test funzionale: monkeyrunner può eseguire un test automatico dall'inizio alla fine di un'app per Android. Devi fornire valori di input con pressioni di tasti o eventi di tocco e visualizzare i risultati come screenshot.
  • Test di regressione. monkeyrunner può testare la stabilità dell'app eseguendo un'app e confrontando i suoi screenshot di output con una serie di screenshot noti per essere corretti.
  • Automazione estendibile: poiché monkeyrunner è un toolkit API, puoi sviluppare un sistema di moduli e programmi basati su Python per controllare i dispositivi Android. Oltre all'API monkeyrunner, puoi usare i moduli Python os e subprocess standard per chiamare strumenti Android, ad esempio Android Debug Bridge.

    Puoi anche aggiungere i tuoi corsi all'API monkeyrunner. Questa procedura è descritta in maggiore dettaglio nella sezione Estendi monkeyrunner con i plug-in.

Lo strumento monkeyrunner utilizza Jython, un'implementazione di Python che impiega il linguaggio di programmazione Java. Jython consente all'API monkeyrunner di interagire facilmente con il framework Android. Con Jython, puoi utilizzare la sintassi Python per accedere a costanti, classi e metodi dell'API.

Un semplice programma monkeyrunner

Ecco un semplice programma monkeyrunner che si connette a un dispositivo, creando un oggetto MonkeyDevice. Utilizzando l'oggetto MonkeyDevice, il programma installa un pacchetto di applicazioni Android, esegue una delle sue attività e invia eventi chiave all'attività. Il programma acquisisce quindi uno screenshot del risultato, creando un oggetto MonkeyImage. Da questo oggetto, il programma scrive un file PNG contenente lo screenshot.

# 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 è contenuta in tre moduli nel pacchetto com.android.monkeyrunner:

  • MonkeyRunner: una classe di metodi di utilità per i programmi monkeyrunner. Questa classe fornisce un metodo per connettere monkeyrunner a un dispositivo o un emulatore. Fornisce inoltre metodi per creare UI per un programma monkeyrunner e per visualizzare la guida integrata.
  • MonkeyDevice: rappresenta un dispositivo o un emulatore. Questa classe fornisce metodi per installare e disinstallare pacchetti, avviare un'attività e inviare eventi della tastiera o del tocco a un'app. Puoi utilizzare questa classe anche per eseguire pacchetti di test.
  • MonkeyImage: rappresenta un'immagine cattura schermo. Questa classe fornisce metodi per acquisire le schermate, convertire le immagini bitmap in vari formati, confrontare due oggetti MonkeyImage e scrivere un'immagine in un file.

In un programma Python, accedi a ogni classe come modulo Python. Lo strumento monkeyrunner non importa questi moduli automaticamente. Per importare un modulo, utilizza l'istruzione from Python:

from com.android.monkeyrunner import <module>

Dove <module> è il nome del corso che vuoi importare. Puoi importare più di un modulo nella stessa istruzione from separando i nomi dei moduli con delle virgole.

Esegui monkeyrunner

Puoi eseguire programmi monkeyrunner da un file o inserendo istruzioni monkeyrunner in una sessione interattiva. Per eseguire entrambe le operazioni, richiama il comando monkeyrunner, disponibile nella sottodirectory tools/ della directory dell'SDK. Se fornisci un nome file come argomento, il comando monkeyrunner esegue i contenuti del file come programma Python, altrimenti avvia una sessione interattiva.

Di seguito è riportata la sintassi del comando monkeyrunner:

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

La tabella 1 illustra i flag e gli argomenti monkeyrunner.

Tabella 1. monkeyrunner flag e argomenti

Argomento Descrizione
-plugin <plugin_jar> (Facoltativo) Specifica un file JAR contenente un plug-in per monkeyrunner. Per scoprire di più sui plug-in monkeyrunner, consulta la sezione Estendi monkeyrunner con plug-in. Per specificare più di un file, includi l'argomento più volte.
<program_filename> Se fornisci questo argomento, il comando monkeyrunner esegue i contenuti del file come programma Python. In caso contrario, il comando avvia una sessione interattiva.
<program_options> (Facoltativo) Flag e argomenti per il programma in <program_file>.

guida integrata per monkeyrunner

Puoi generare un riferimento API per monkeyrunner eseguendo:

monkeyrunner help.py <format> <outfile>

Gli argomenti sono:

  • <format> è text per l'output in testo normale o html per l'output HTML.
  • <outfile> è un nome qualificato per il percorso del file di output.

Estendi monkeyrunner con i plug-in

Puoi estendere l'API monkeyrunner con classi che scrivi in Java e crei in uno o più file JAR. Puoi utilizzare questa funzionalità per estendere l'API monkeyrunner con le tue classi o per estendere le classi esistenti. Puoi utilizzare questa funzionalità anche per inizializzare l'ambiente monkeyrunner.

Per fornire un plug-in a monkeyrunner, richiama il comando monkeyrunner con l'argomento -plugin <plugin_jar> descritto nella tabella 1.

Nel codice plug-in puoi importare ed estendere le classi monkeyrunner principali MonkeyDevice, MonkeyImage e MonkeyRunner in com.android.monkeyrunner (consulta la sezione sull'API monkeyrunner).

Tieni presente che i plug-in non ti consentono di accedere all'SDK Android. Non puoi importare pacchetti come com.android.app. Questo perché monkeyrunner interagisce con il dispositivo o l'emulatore al di sotto del livello delle API del framework.

La classe di avvio del plug-in

Il file JAR di un plug-in può specificare una classe per la quale viene creata un'istanza prima dell'avvio dell'elaborazione dello script. Per specificare questa classe, aggiungi la chiave MonkeyRunnerStartupRunner al file manifest del file JAR. Come valore, utilizza il nome della classe da eseguire all'avvio. Lo snippet seguente mostra come eseguire questa operazione all'interno di uno script di build ant:

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


Per ottenere l'accesso all'ambiente di runtime dello strumento monkeyrunner, la classe di avvio può implementare com.google.common.base.Predicate<PythonInterpreter>. Ad esempio, questa classe imposta alcune variabili nello spazio dei nomi predefinito:

Kotlin

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

Java

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;
    }
}