En esta página

Qt Quick Prueba

Introducción

Qt Quick Test es un marco de pruebas unitarias para aplicaciones QML. Los casos de prueba se escriben como funciones de JavaScript dentro de un tipo « TestCase »:

import QtQuick 2.3
import QtTest 1.0

TestCase {
    name: "MathTests"

    function test_math() {
        compare(2 + 2, 4, "2 + 2 = 4")
    }

    function test_fail() {
        compare(2 + 2, 5, "2 + 2 = 5")
    }
}

Las funciones cuyos nombres comienzan por « test_ » se tratan como casos de prueba que deben ejecutarse. Consulta la documentación de los tipos « TestCase » y « SignalSpy » para obtener más información sobre cómo escribir casos de prueba.

Nota: Nohay garantía de compatibilidad binaria para el módulo « Qt Quick Test». Esto significa que solo se garantiza que una aplicación que utilice « Qt Quick Test» funcione con la versión de Qt con la que se desarrolló. Sin embargo, sí se garantiza la compatibilidad de código fuente.

Uso del módulo

API de QML

Los tipos QML de « Qt Quick Test» están disponibles mediante la importación « QtTest ». Para utilizar estos tipos, añade la siguiente instrucción de importación a tu archivo .qml:

import QtTest

API de C++

Para utilizar la biblioteca « C++ API » es necesario vincularla con la biblioteca del módulo, ya sea directamente o a través de otras dependencias. Varias herramientas de compilación ofrecen soporte específico para ello, entre ellas CMake y qmake.

Compilación con CMake

Utiliza el comando find_package() para localizar los componentes del módulo necesarios en el paquete Qt6:

find_package(Qt6 REQUIRED COMPONENTS QuickTest)
target_link_libraries(mytarget PRIVATE Qt6::QuickTest)

Consulta también la descripción general de «Compilación con CMake ».

Compilación con qmake

Hay dos formas de vincular la biblioteca C++ correspondiente. Si tu proyecto de prueba utiliza un archivo QML TestCase, ya deberías tener la siguiente línea en tu archivo de proyecto:

CONFIG += qmltestcase

Esto hará que la prueba se vincule a la biblioteca C++ QtQuickTest.

Si tienes un proyecto de pruebas solo en C++, puedes añadir la siguiente línea a tu archivo de proyecto:

QT += qmltest

Ejecución de pruebas

Los casos de prueba se ejecutan mediante un harness de C++ que consta del siguiente código:

#include <QtQuickTest>
QUICK_TEST_MAIN(example)

Donde «example» es el identificador que se utiliza para identificar de forma única este conjunto de pruebas.

Configura tu archivo CMakeLists.txt y compila tu proyecto utilizando tu generador favorito.

cmake_minimum_required(VERSION 3.2)

project(tst_example LANGUAGES CXX)

enable_testing()

find_package(Qt6 REQUIRED COMPONENTS QuickTest Qml)

#[[The test harness scans the specified source directory recursively
for "tst_*.qml" files. By default, it looks in the current directory,
which is usually where the executable is. This command makes it look
in the project's source directory instead.]]
add_definitions(-DQUICK_TEST_SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}")

qt_standard_project_setup(REQUIRES 6.6)

add_executable(tst_example tst_example.cpp)

add_test(NAME tst_example COMMAND tst_example)

target_link_libraries(tst_example
    PRIVATE
    Qt6::QuickTest
    Qt6::Qml
)

Añade CONFIG += qmltestcase a tu archivo de proyecto:

TEMPLATE = app
TARGET = tst_example
CONFIG += warn_on qmltestcase
SOURCES += tst_example.cpp

Si se especifica « IMPORTPATH » en tu archivo .pro, cada ruta de importación añadida a « IMPORTPATH » se pasará como argumento de línea de comandos cuando se ejecute la prueba con «make check»:

IMPORTPATH += $$PWD/../imports/my_module1 $$PWD/../imports/my_module2

El sistema de pruebas escanea de forma recursiva el directorio de código fuente especificado en busca de archivos «tst_*.qml». Si no se define ` QUICK_TEST_SOURCE_DIR `, se escaneará el directorio actual al ejecutar el sistema de pruebas. Pueden aparecer otros archivos *.qml correspondientes a componentes QML auxiliares utilizados por la prueba.

La opción de línea de comandos -input se puede configurar en tiempo de ejecución para ejecutar casos de prueba desde un directorio diferente. Esto puede ser necesario para ejecutar pruebas en un dispositivo de destino en el que el nombre del directorio compilado haga referencia a un host. Por ejemplo:

tst_example -input /mnt/SDCard/qmltests

También es posible ejecutar un único archivo utilizando la opción ` -input `. Por ejemplo:

tst_example -input data/test.qml
tst_example -input <full_path>/test.qml

Nota: Especificar la ruta completa al archivo de prueba qml es necesario, por ejemplo, para las compilaciones en segundo plano.

Si tu caso de prueba necesita importaciones de QML, puedes añadirlas como opciones « -import » en la línea de comandos del programa de prueba.

La opción de línea de comandos -functions devolverá una lista de las funciones de prueba actuales. Es posible ejecutar una única función de prueba utilizando el nombre de dicha función como argumento. Por ejemplo:

tst_example Test_Name::function1

La opción de línea de comandos ` -help ` mostrará todas las opciones disponibles.

tst_example -help

Nota: Al ejecutar un caso de prueba « Qt Quick », siempre aparecerá una ventana en la pantalla, incluso si el código de prueba no incluye ninguna interfaz de usuario Quick UI. Para evitarlo, ejecuta el ejecutable de prueba con ` -platform offscreen`.

Ejecución de código C++ antes de las pruebas QML

Para ejecutar código C++ antes de que se ejecuten las pruebas de QML, se puede utilizar la macro ` QUICK_TEST_MAIN_WITH_SETUP `. Esto puede resultar útil, entre otras cosas, para establecer propiedades de contexto en el motor de QML.

La macro es idéntica a QUICK_TEST_MAIN, salvo que admite un argumento de tipo adicional. El marco de pruebas llamará a las ranuras y a las funciones invocables con los siguientes nombres:

NombreFinalidadDesde
void applicationAvailable()Se invoca justo después de que se haya instanciado el objeto `QApplication`. Utiliza esta función para realizar configuraciones que no requieran una instancia de ` QQmlEngine `.Qt 5.12
void qmlEngineAvailable(QQmlEngine *)Se invoca cuando el motor QML está disponible. En este momento, ya se habrán establecido en el motor cualquier import paths, plugin paths y extra file selectors.

Esta función se invoca una vez por cada archivo de prueba QML, por lo que cualquier argumento es exclusivo de esa prueba. Por ejemplo, esto significa que cada archivo de prueba QML tendrá su propio motor QML.

Esta función se puede utilizar para registrar tipos QML y add import paths, entre otras cosas.

Qt 5.11
void cleanupTestCase()Se invoca justo después de que haya finalizado la ejecución de la prueba. Utiliza esta función para realizar una limpieza antes de que comience la destrucción de todos los objetos.Qt 5.12

El siguiente ejemplo muestra cómo se puede utilizar la macro para establecer propiedades de contexto en el motor QML:

// src_qmltest_qquicktest.cpp
#include <QtQuickTest>
#include <QQmlEngine>
#include <QQmlContext>
#include <QGuiApplication>

class Setup : public QObject
{
    Q_OBJECT

public:
    Setup() {}

public slots:
    void applicationAvailable()
    {
        // Initialization that only requires the QGuiApplication object to be available
    }

    void qmlEngineAvailable(QQmlEngine *engine)
    {
        // Initialization requiring the QQmlEngine to be constructed
        engine->rootContext()->setContextProperty("myContextProperty", QVariant(true));
    }

    void cleanupTestCase()
    {
        // Implement custom resource cleanup
    }
};

QUICK_TEST_MAIN_WITH_SETUP(mytest, Setup)

#include "src_qmltest_qquicktest.moc"

La inclusión « .moc » se basa en el nombre del archivo « .cpp ». Por ejemplo, en el ejemplo anterior, el archivo « .cpp » se llama « src_qmltest_qquicktest.cpp ». Si el archivo se llamara « MyTest.cpp », la inclusión sería:

#include "MyTest.moc"

Referencia

Licencias

Qt Quick Qt Test está disponible bajo licencias comerciales de The Qt Company. Además, está disponible bajo licencias de software libre. Desde Qt 5.4, estas licencias de software libre son la Licencia Pública General Reducida de GNU, versión 3, o la Licencia Pública General de GNU, versión 2. Consulte Licencias de Qt para obtener más detalles.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.