harmonyostestrunner.qdoc

Go to the documentation of this file.

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
    \page harmonyos-test-runner.html
    \brief Overview of the harmonyostestrunner tool for running Qt tests on HarmonyOS.
    \title The harmonyostestrunner Tool
 
    \target harmonyostestrunner
 
    \note Qt for HarmonyOS is in technology preview and may change in future
    releases.
 
    \section1 Introduction
 
    The \c harmonyostestrunner tool runs a single Qt auto test on a HarmonyOS
    device or emulator and reports the result on the host. When you run a test
    with \c ctest, the CMake test wrapper normally invokes it for you. Invoke it
    directly when the test HAP is built on one machine but the device is
    attached to another, or when you have a test HAP but no CMake build tree at
    hand.
 
    This tool does not build or install the test package. Instead, \l{The
    harmonydeployqt Tool}{harmonydeployqt} bundles the test binaries into a
    single test HAP (through its \c {--test-bundle} option). You must build,
    sign, and install that HAP on the device beforehand:
 
    \badcode
    hdc install <path/to/autotests-signed.hap>
    \endcode
 
    \section1 How it works
 
    \list 1
        \li It verifies that the target device has the test bundle HAP
            installed.
        \li It force-stops any running instance of the bundle, then launches the
            ability with \c {aa start}, telling the platform which test shared
            library to load and where to redirect the test's standard output and
            exit code inside the application sandbox.
        \li It streams the test's standard output to the host as the test runs.
        \li It waits for the test to finish, which it detects when the exit-code
            file becomes readable. A liveness check catches a crashed process, and an
            optional no-progress watchdog force-stops a test that stops producing
            \c PASS or \c FAIL results.
        \li If the test declares blocking system dialogs and the test's output
            goes quiet, it dumps the screen layout with \c uitest and clicks the
            expected button.
        \li It returns the test's exit code as its own exit code.
    \endlist
 
    \section1 How to use it
 
    The basic syntax is:
 
    \badcode
    harmonyostestrunner [OPTIONS] <test-binary> [TESTARGS]
    \endcode
 
    The \c {<test-binary>} argument is the path to the test shared library, for
    example \c {libtst_qobject.so}. Its file name selects which test inside the
    bundle to run. Anything after it, such as test function names or \c {-v2}, the
    tool forwards to the test.
 
    \section2 Options
 
    The following table lists the command-line options of \c
    harmonyostestrunner. You can set each option through the environment
    variable in parentheses. The command-line value takes precedence.
 
    \table
    \header
        \li Option
        \li Description
    \row
        \li \c {--bundle-name <name>}
        \li HarmonyOS bundle name of the installed test HAP
            (\c QT_HARMONYOS_BUNDLE_NAME). Defaults to
            \c org.qtproject.autotests.
    \row
        \li \c {--ability-name <name>}
        \li HarmonyOS ability name inside the test HAP
            (\c QT_HARMONYOS_ABILITY_NAME). Defaults to \c QAbility.
    \row
        \li \c {--hdc <path>}
        \li Path to the \c hdc tool (\c QT_HARMONYOS_HDC). Defaults to the
            \c hdc found in \c PATH.
    \row
        \li \c {--timeout <seconds>}
        \li Seconds to wait for a test to complete before aborting
            (\c QT_HARMONYOS_TEST_TIMEOUT). Defaults to 300.
    \row
        \li \c {--no-progress-timeout <seconds>}
        \li Seconds without a \c PASS or \c FAIL result before the tool declares
            the test hung (\c QT_HARMONYOS_NO_PROGRESS_TIMEOUT). Defaults to 60;
            0 disables the watchdog.
    \row
        \li \c {--device <key>}
        \li The \c hdc connect key (\c {-t}) for the target device
            (\c QT_HARMONYOS_DEVICE). Required when you attach multiple
            devices.
    \row
        \li \c {--test-config <path>}
        \li Path to the generated test bundle deployment settings
            (\c QT_HARMONYOS_TEST_CONFIG). The build generates this file, and the
            CMake test wrapper passes it. The tool reads it for the blocking
            system dialogs it has to answer.
    \row
        \li \c {--help}
        \li Displays the help information.
    \row
        \li \c {--version}
        \li Displays the tool version.
    \endtable
 
    \section2 Example usage
 
    Run the \c tst_qobject test on a specific device, executing only the
    \c signalsBlocked test case:
 
    \badcode
    harmonyostestrunner --device 127.0.0.1:5555 libtst_qobject.so signalsBlocked
    \endcode
 
    For more information about the Qt Test framework, see \l{Qt Test Overview}.
*/