diff --git a/doc/global/externalsites/external-resources.qdoc b/doc/global/externalsites/external-resources.qdoc index 0dcea08a53a..66fe76be813 100644 --- a/doc/global/externalsites/external-resources.qdoc +++ b/doc/global/externalsites/external-resources.qdoc @@ -36,6 +36,10 @@ \externalpage https://developer.android.com/build/configure-app-module \title Android: Configure the app module */ +/*! + \externalpage https://developer.android.com/ndk/guides/ndk-stack + \title Android: ndk-stack +*/ /*! \externalpage https://developer.apple.com/documentation/uikit/uiapplication/1622952-canopenurl \title iOS: canOpenURL: diff --git a/src/tools/androidtestrunner/doc/androidtestrunner.qdoc b/src/tools/androidtestrunner/doc/androidtestrunner.qdoc new file mode 100644 index 00000000000..21f231868a4 --- /dev/null +++ b/src/tools/androidtestrunner/doc/androidtestrunner.qdoc @@ -0,0 +1,127 @@ +// 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 }: The path where the Android Gradle package + is built, commonly under \c {android-build-testname}. + \li \c {--make }: The command used to build the test APK, + for example, \c {cmake --build --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 }: 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 }: Specifies a custom ADB command path. + Defaults to the \c adb path found in the system's \c $PATH. + \li \c {--activity }: Specifies a custom activity to run. + Defaults to the first activity defined in the \c AndroidManifest.xml. + \li \c {--timeout }: 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 }: 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 {-- }: 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 +*/