Android: document androidtestrunner tool

Add documentation and usage of androidtestrunner tool.

Pick-to: 6.9 6.8
Fixes: QTBUG-84330
Change-Id: I03aa67ebf0ba807f20595547f2598d905080a878
Reviewed-by: Nicholas Bennett <[email protected]>

2 files changed, 131 insertions, 0 deletions

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
@@ -37,6 +37,10 @@
     \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 <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 {-- <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
+*/