L'outil androidtestrunner

Introduction

L'outil « androidtestrunner » exécute des Qt Tests sur des appareils Android et des émulateurs. Il automatise les étapes nécessaires à l'exécution des tests, notamment la gestion de l'installation des fichiers APK, l'exécution des tests et la récupération des résultats.

Avant d'utiliser l'androidtestrunner, assurez-vous d'avoir configuré votre projet de test Qt avec CMake ou qmake.

Fonctionnement

1. Tout d’abord, le processus commence par l’exécution de la commande de compilation APK afin de générer le fichier APK nécessaire au test.
2. Ensuite, l'application de test est installée sur l'appareil cible, puis lancée, ce qui déclenche le processus de test.
3. Les résultats des tests sont enregistrés dans le répertoire de données de l’application sur l’appareil, ce qui garantit la capture de tous les résultats des tests.
4. Une fois les tests terminés, le programme d'exécution crée un fichier de code de sortie à côté des fichiers de résultats.
5. À ce stade, l’ androidtestrunner e récupère ces fichiers de résultats depuis l’appareil et examine le code de sortie pour détecter d’éventuels échecs.
6. Si des problèmes sont détectés, il affiche immédiatement les journaux Logcat de l’application, y compris les traces de pile de plantage potentielles, qui sont formatées pour faire apparaître les noms de fichiers et les numéros de ligne pour chaque trame. De plus, il capture et signale les journaux « Application Not Responding » (ANR) si de tels événements se produisent pendant l’exécution du test.

Afin d’améliorer l’expérience d’intégration, le programme d’exécution des tests propage les variables d’environnement QT ou Qt Test depuis l’environnement hôte du processus du programme d’exécution vers l’application, garantissant ainsi la cohérence et un flux de travail de test fluide.

Exécution des tests avec le wrapper de test

Qt génère, pour chaque test Android, un script de wrapper spécifique à la cible (nommé d’après la cible de test) qui appelle ` androidtestrunner ` avec les chemins d’accès appropriés et transmet tout argument supplémentaire au binaire de test. L’exemple ci-dessous exécute ` tst_android ` sur un émulateur spécifique, transmet une variable d’environnement Qt et n’exécute que le cas de test ` testAssets ` :

ANDROID_SERIAL=emulator-5554 QT_DEBUG_PLUGINS=1 ./tst_android testAssets

Récupération des résultats

Par défaut, et si la sortie stdout du test n’est pas explicitement désactivée, les résultats du test sont affichés sur l’hôte au fur et à mesure de l’exécution du test. Une fois les tests terminés, tous les fichiers de test explicitement demandés sont copiés dans le chemin de sortie spécifié, dans leurs formats respectifs.

Pour plus de détails sur le framework d’ Qt Test, consultez la présentation d’Qt Test .

Mode d’emploi

La syntaxe de base pour exécuter l'androidtestrunner est la suivante :

androidtestrunner [ARGUMENTS] -- [TESTARGS]

Pour exécuter le test sur un appareil ou un émulateur spécifique, passez l'--serial <serial> ou définissez la variable d'environnement adb: ANDROID_SERIAL ou ANDROID_DEVICE_SERIAL. L'option explicite a la priorité.

Arguments obligatoires

Le programme d'exécution des tests attend toujours que les arguments suivants lui soient transmis :

• --path <build-path>: Le chemin d'accès à l'emplacement où le package Gradle Android est généré, généralement <build-dir>/android-build-<target>.
• --make <build-command>: La commande utilisée pour générer l'APK de test, par exemple cmake --build <build-dir> --target <target>_make_apk.

  Remarque : transmettez cet argument entre guillemets afin qu’il ne soit pas traité comme plusieurs arguments du programme d’exécution des tests, mais comme la valeur de l’argument --make.

• L'un des éléments suivants :
  • --apk <apk-path>: Chemin d’accès à l’APK de test généré par la commande de compilation et installé sur l’appareil.
  • --aab <aab-path>: Chemin d’accès à l’AAB de test ; nécessite --bundletool. Ces deux options ne peuvent pas être définies simultanément, et aucune ne peut être spécifiée plus d’une fois.

Arguments facultatifs

Vous pouvez également passer les arguments facultatifs suivants :

• --bundletool <path>: Chemin d'accès au fichier JAR d'bundletool d'Android. Obligatoire lorsque « --aab » est utilisé.
• --manifest <path>: Chemin d'accès personnalisé à l'AndroidManifest.xml. Par défaut, il s'agit d'un fichier situé dans le répertoire de compilation ou dans son sous-répertoire « app/ ».
• --adb <adb-path>: Spécifie un chemin d’accès personnalisé à la commande ADB. Par défaut, il s’agit du chemin d’accès à la commande « adb » situé dans le répertoire « $PATH » du système.
• --serial <serial>: Numéro de série de l’appareil Android cible. Remplace les paramètres « ANDROID_SERIAL » et « ANDROID_DEVICE_SERIAL ».
• --activity <activity-name>: Spécifie une activité personnalisée à exécuter. La valeur par défaut est la première activité définie dans le fichier ` AndroidManifest.xml`.
• --timeout <seconds>: Définit le délai d’expiration pour l’exécution du test. La valeur par défaut est de 600 secondes (10 minutes).
• --pre-test-adb-command <command>: Appelle l’ <command> adb après l’installation et avant l’exécution du test. Peut être passé plusieurs fois.
• --skip-install-root: Supprime le suffixe « INSTALL_ROOT=<path> install » ajouté automatiquement à « --make » lorsque la commande de compilation est un outil de type « make-family » (make, gmake, nmake, mingw32-make, jom; la correspondance ne tient pas compte de la casse). Ce suffixe n’est jamais ajouté pour « cmake », « ninja » ou d’autres pilotes de compilation ; cette option n’a donc d’effet qu’avec les outils répertoriés.
• --ndk-stack <command-path>: Spécifie le chemin d’accès à l’outil ndk-stack permettant de symboliser les traces de pile de plantage. Par défaut, il s’agit du chemin d’accès à l’outil situé sous $ANDROID_NDK_ROOT.
• --show-logcat: Affiche la sortie de logcat sur stdout, que le test échoue ou non. Lit les tampons « main », « system » et « crash », et inclut les lignes system_server lorsqu’un ANR est détecté.
• --verbose: Affiche une sortie détaillée.
• -- <arguments>: Transmet tout ce qui suit les tirets en tant qu’arguments de test.
• --help: Affiche les informations d’aide.

Exemple d'utilisation

Voici un exemple qui lance le test « tst_android » en n'exécutant que le cas de test « testAssets » :

androidtestrunner \
    --path ~/tst_android/build/android-build-tst_openssl \
    --make "cmake --build ~/tst_android/build --target apk" \
    --apk ~/tst_android/build/android-build-tst_openssl/tst_openssl.apk \
    testAssets