androidtestrunner.qdoc

Go to the documentation of this file.

// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
    \page android-test-runner.html
    \brief Overview of the androidtestrunner tool for running Qt tests on Android.
    \title The androidtestrunner Tool
 
    \ingroup android-platform-extra-topics
 
    \section1 Introduction
 
    The \c androidtestrunner tool runs Qt tests on Android devices and emulators.
    It automates the steps required to execute tests, including managing APK
    installation, test execution, and retrieving results.
 
    Before using the \c androidtestrunner, ensure you have configured your Qt
    test project with CMake or qmake.
 
    \section1 How it works
 
    \list 1
        \li Firstly, it begins by executing the APK build command to generate
            the required APK for the test.
        \li Following this, it installs the test app on the target device and
            starts the test app, setting the testing process in motion.
        \li The test results are written to the app’s data directory on the
            device, ensuring that comprehensive test outputs are captured.
        \li Once the tests conclude, the runner writes an exit code file beside
            the result files.
        \li At this stage, the \c androidtestrunner retrieves these result files
            from the device, examining the exit code for failures.
        \li If issues are detected, it immediately prints the app’s logcat logs,
            including any potential crash stack traces, which are beautified to
            reveal file names and line numbers for each frame. Additionally, it
            captures and reports Application Not Responding (ANR) logs if such
            events occur during the test execution.
    \endlist
 
    To enhance the integration experience, the test runner
    propagates QT or QTEST environment variables from the host environment of
    the test runner process to the app, ensuring consistency and a seamless
    testing workflow.
 
    \section1 Running tests with the test wrapper
 
    Here is an example that runs the \c tst_android test while running it on
    a specific emulator instance, passing an environment variable and executing
    only \c testAssets test case:
 
    \badcode
    ANDROID_SERIAL=emulator-5554 QT_DEBUG_PLUGINS=1 ./tst_android testAssets
    \endcode
 
    \section1 Retrieving results
 
    By default, and if the stdout test output is not explicitly disabled, the test
    results are printed to the host as the test is executing. After running the
    tests, any explicitly requested test files are pulled into the specified output
    path with their respective formats.
 
    For comprehensive details about Qt Test Framework, see \l {Qt Test Overview}.
 
    \section1 How to use it
 
    The basic syntax to run the \c androidtestrunner is as follows:
 
    \badcode
    androidtestrunner [ARGUMENTS] -- [TESTARGS]
    \endcode
 
    To run the test on a specific device/emulator, use the \c adb environment
    varialbe \c ANDROID_SERIAL or \c ANDROID_DEVICE_SERIAL.
 
    \section2 Mandatory Arguments
 
    The test runner always expects the following arguments to be passed:
 
    \list
        \li \c {--path <build-path>}: The path where the Android Gradle package
            is built, commonly under \c {android-build-testname}.
        \li \c {--make <build-command>}: The command used to build the test APK,
            for example, \c {cmake --build <build-dir> --target <target>_make_apk}.
            \note Pass this argument quoted so it's not treated as multiple arguments
                of the test runner but as the value of \c {--make} argument.
        \li \c {--apk <apk-path>}: The Path to the test APK that is generated by
            the build command and that is installed on the device.
    \endlist
 
    \section2 Optional arguments
 
    You can also pass the following optional arguments:
 
    \list
        \li \c {--adb <adb-path>}: Specifies a custom ADB command path.
            Defaults to the \c adb path found in the system's \c $PATH.
        \li \c {--activity <activity-name>}: Specifies a custom activity to run.
            Defaults to the first activity defined in the \c AndroidManifest.xml.
        \li \c {--timeout <seconds>}: Sets the timeout for running the test.
            Defaults to 600 seconds (10 minutes).
        \li \c --skip-install-root: Avoids appending INSTALL_ROOT to the make
            command and is mainly useful when using \c qmake.
        \li \c --show-logcat: Prints the logcat output to stdout regardless of
            test failure. Logs are printed in case of failure and can include
            crash stacktraces or ANR events.
        \li \c {--ndk-stack <command-path>}: Specifies the path to the
            \l {Android: ndk-stack}{ndk-stack} tool for symbolizing crash stack
            traces. Defaults to the tool path found under \c $ANDROID_NDK_ROOT.
        \li \c {--pre-test-adb-command <command>}: call the adb <command> after
            installation and before the test run.
        \li \c {-- <arguments>}: Passes anything after the dashes as test arguments.
        \li \c --verbose: Prints verbose output.
        \li \c --help: Displays the help information.
    \endlist
 
    \section2 Example usage
 
    Here is an example that runs the \c tst_android test, executing only
    \c testAssets test case:
 
    \badcode
    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 \
        --skip-install-root \
        testAssets
    \endcode
*/