1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
// 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
*/
|
