En esta página

Qt Test Resumen

Qt Test es un marco de trabajo para realizar pruebas unitarias de aplicaciones y bibliotecas basadas en Qt. Qt Test ofrece todas las funcionalidades que suelen encontrarse en los marcos de trabajo de pruebas unitarias, así como extensiones para probar interfaces gráficas de usuario.

Qt Test Está diseñado para facilitar la redacción de pruebas unitarias para aplicaciones y bibliotecas basadas en Qt:

CaracterísticasDetalles
LigeroQt Test Consta de unas 6.000 líneas de código y 60 símbolos exportados.
AutónomoQt Test solo requiere unos pocos símbolos del módulo « Qt Core » para las pruebas sin interfaz gráfica de usuario.
Pruebas rápidasQt Test No necesita ejecutores de pruebas especiales ni ningún registro específico para las pruebas.
Pruebas basadas en datosUna prueba se puede ejecutar varias veces con diferentes datos de prueba.
Pruebas básicas de interfaz gráfica de usuarioQt Test ofrecen funcionalidades para la simulación del ratón y el teclado.
Pruebas de rendimientoQt Test Admite pruebas comparativas y proporciona varios back-ends de medición.
Compatible con IDEQt Test muestra mensajes que pueden ser interpretados por Qt Creator, Visual Studio y KDevelop.
Seguridad de subprocesosLa notificación de errores es segura para subprocesos y atómica.
Seguridad de tiposEl uso extensivo de plantillas evita los errores provocados por la conversión implícita de tipos.
Fácilmente ampliableSe pueden añadir fácilmente tipos personalizados a los datos de prueba y a los resultados de las pruebas.

Puedes utilizar el asistente de Qt Creator para crear un proyecto que contenga pruebas de Qt y compilarlas y ejecutarlas directamente desde Qt Creator. Para obtener más información, consulta Qt Creator: Compilar y ejecutar pruebas.

Creación de una prueba

Para crear una prueba, crea una subclase de ` QObject ` y añádele uno o más slots privados. Cada slot privado es una función de prueba dentro de tu prueba. Se puede utilizar ` QTest::qExec()` para ejecutar todas las funciones de prueba del objeto de prueba.

Además, puedes definir las siguientes ranuras privadas que no se tratan como funciones de prueba. Cuando estén presentes, serán ejecutadas por el marco de pruebas y pueden utilizarse para inicializar y limpiar bien toda la prueba, bien la función de prueba actual.

  • initTestCase() Se llamará antes de que se ejecute la primera función de prueba.
  • initTestCase_data() Se llamará a esta función para crear una tabla global de datos de prueba.
  • cleanupTestCase() Se llamará después de que se haya ejecutado la última función de prueba.
  • init() Se llamará antes de que se ejecute cada función de prueba.
  • cleanup() Se llamará después de cada función de prueba.

Utiliza ` initTestCase() ` para preparar la prueba. Cada prueba debe dejar el sistema en un estado utilizable, de modo que pueda ejecutarse repetidamente. Las operaciones de limpieza deben gestionarse en ` cleanupTestCase()`, para que se ejecuten incluso si la prueba falla.

Utiliza init() para preparar una función de prueba. Cada función de prueba debe dejar el sistema en un estado utilizable, de modo que pueda ejecutarse repetidamente. Las operaciones de limpieza deben gestionarse en cleanup(), para que se ejecuten incluso si la función de prueba falla y se sale prematuramente.

Como alternativa, puedes utilizar RAII (la adquisición de recursos es inicialización), con operaciones de limpieza llamadas en los destructores, para garantizar que se ejecuten cuando la función de prueba devuelva un valor y el objeto salga del ámbito.

Si initTestCase() falla, no se ejecutará ninguna función de prueba. Si init() falla, no se ejecutará la siguiente función de prueba, sino que la prueba pasará a la siguiente función de prueba.

Ejemplo:

class MyFirstTest: public QObject
{
    Q_OBJECT

private:
    bool myCondition()
    {
        return true;
    }

private slots:
    void initTestCase()
    {
        qDebug("Called before everything else.");
    }

    void myFirstTest()
    {
        QVERIFY(true); // comprueba que se cumpla una condición
        QCOMPARE(1, 1); // compara dos valores
    }

   void miSegundaPrueba()
    {
        QVERIFY(miCondición());
        QVERIFY(1 != 2);
    }

    void limpiarCasoDePrueba()
    {
        qDebug("Called after myFirstTest and mySecondTest.");
    }
};

Por último, si la clase de prueba tiene un método estático público ` void initMain() `, las macros ` QTEST_MAIN ` lo invocan antes de que se instancie el objeto ` QApplication `. Esta característica se añadió en la versión 5.14.

Para ver más ejemplos, consulta el tutorial de Qt Test .

Aumentar el tiempo de espera de las funciones de prueba

QtTest limita el tiempo de ejecución de cada prueba para detectar bucles infinitos y errores similares. Por defecto, cualquier llamada a una función de prueba se interrumpirá tras cinco minutos. En el caso de las pruebas basadas en datos, esto se aplica a cada llamada con una etiqueta de datos distinta. Este tiempo de espera se puede configurar estableciendo la variable de entorno ` QTEST_FUNCTION_TIMEOUT ` en el número máximo de milisegundos que se considera aceptable para una sola llamada. Si una prueba tarda más de lo establecido, se interrumpe y se llama a ` qFatal() `. Como resultado, la prueba se aborta de forma predeterminada, como si se hubiera bloqueado.

Para establecer QTEST_FUNCTION_TIMEOUT desde la línea de comandos en Linux o macOS, escribe:

QTEST_FUNCTION_TIMEOUT=900000
export QTEST_FUNCTION_TIMEOUT

En Windows:

SET QTEST_FUNCTION_TIMEOUT=900000

A continuación, ejecuta la prueba en este entorno.

Como alternativa, puedes configurar la variable de entorno mediante código en el propio código de prueba, por ejemplo, llamando, desde el método especial initMain() de tu clase de prueba:

qputenv("QTEST_FUNCTION_TIMEOUT", "900000");

Para calcular un valor adecuado para el tiempo de espera, comprueba cuánto tarda normalmente la prueba y decide cuánto tiempo más puede tardar sin que ello sea síntoma de algún problema. Convierte ese tiempo adicional a milisegundos para obtener el valor del tiempo de espera. Por ejemplo, si decides que una prueba que tarda varios minutos podría tardar razonablemente hasta veinte minutos, por ejemplo en un equipo lento, multiplica 20 * 60 * 1000 = 1200000 y establece la variable de entorno en 1200000 en lugar del 900000 anterior.

Creación de una prueba

Puedes compilar un ejecutable que contenga una clase de prueba que, por lo general, pruebe una clase del código de producción. Sin embargo, lo habitual es que quieras probar varias clases de un proyecto ejecutando un solo comando.

Consulta «Cómo escribir una prueba unitaria » para obtener una explicación paso a paso.

Compilación con CMake y CTest

Puedes utilizar CMake y CTest para crear una prueba. CTest te permite incluir o excluir pruebas basándose en una expresión regular que se compara con el nombre de la prueba. Además, puedes aplicar la propiedad « LABELS » a una prueba y, de este modo, CTest podrá incluir o excluir pruebas en función de esas etiquetas. Todos los objetivos etiquetados se ejecutarán cuando se llame a un objetivo « test » en la línea de comandos.

Nota: En Android, si tienes un dispositivo o emulador conectado, las pruebas se ejecutarán en ese dispositivo. Si tienes más de un dispositivo conectado, configura la variable de entorno ANDROID_DEVICE_SERIAL con el número de serie ADB del dispositivo en el que deseas ejecutar las pruebas.

CMake ofrece otras ventajas. Por ejemplo, el resultado de una ejecución de pruebas se puede publicar en un servidor web utilizando CDash sin prácticamente ningún esfuerzo.

CTest se adapta a marcos de pruebas unitarias muy diferentes y funciona de forma inmediata con QTest.

A continuación se muestra un ejemplo de un archivo CMakeLists.txt que especifica el nombre del proyecto y el lenguaje utilizado (en este caso, «mytest» y C++), los módulos de Qt necesarios para compilar la prueba (Qt Test) y los archivos que se incluyen en la prueba (tst_mytest.cpp).

project(mytest LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Test)

set(CMAKE_INCLUDE_CURRENT_DIR ON)

set(CMAKE_AUTOMOC ON)

enable_testing(true)

qt_add_executable(mytest tst_mytest.cpp)
add_test(NAME mytest COMMAND mytest)

target_link_libraries(mytest PRIVATE Qt::Test)

Para obtener más información sobre las opciones disponibles, consulta «Compilar con CMake».

Compilación con qmake

Si utilizas qmake como herramienta de compilación, solo tienes que añadir lo siguiente a tu archivo de proyecto:

QT += testlib

Si deseas ejecutar las pruebas mediante make check, añade la siguiente línea:

CONFIG += testcase

Para evitar que la prueba se instale en tu destino, añade la siguiente línea:

CONFIG += no_testcase_installs

Consulta el manual de qmake para obtener más información sobre make check.

Compilación con otras herramientas

Si utilizas otras herramientas de compilación, asegúrate de añadir la ubicación de los archivos de cabecera de Qt Test a tu ruta de inclusión (normalmente include/QtTest en el directorio de instalación de Qt). Si utilizas una versión de Qt para producción, enlaza tu prueba con la biblioteca QtTest. Para compilaciones de depuración, utiliza QtTest_debug.

Qt Test Argumentos de la línea de comandos

Sintaxis

La sintaxis para ejecutar una autoprueba tiene la siguiente forma sencilla:

testname [options] [testfunctions[:testdata]]...

Sustituye testname por el nombre de tu ejecutable. testfunctions puede contener los nombres de las funciones de prueba que se van a ejecutar. Si no se pasan testfunctions, se ejecutan todas las pruebas. Si añades el nombre de una entrada de testdata, la función de prueba se ejecutará únicamente con esos datos de prueba.

Por ejemplo:

/myTestDirectory$ testQString toUpper

Ejecuta la función de prueba denominada toUpper con todos los datos de prueba disponibles.

/myTestDirectory$ testQString toUpper toInt:zero

Ejecuta la función de prueba « toUpper » con todos los datos de prueba disponibles, y la función de prueba « toInt » con la fila de datos de prueba denominada « zero » (si los datos de prueba especificados no existen, la prueba asociada fallará y se informará de las etiquetas de datos disponibles).

/myTestDirectory$ testMyWidget -vs -eventdelay 500

Ejecuta la prueba de la función testMyWidget, muestra cada emisión de señal y espera 500 milisegundos tras cada evento simulado del ratón o del teclado.

Opciones

Opciones de registro

Las siguientes opciones de línea de comandos determinan cómo se muestran los resultados de las pruebas:

  • -o nombre_archivo,formato
    Writes output to the specified file, in the specified format (one of txt, csv, junitxml, xml, lightxml, teamcity or tap). Use the special filename - (hyphen) to log to standard output.
  • -o nombre_archivo
    Escribe la salida en el archivo especificado.
  • -txt
    Muestra los resultados en texto sin formato.
  • -csv
    Muestra los resultados como valores separados por comas (CSV), aptos para su importación a hojas de cálculo. Este modo solo es adecuado para pruebas de rendimiento, ya que omite los mensajes habituales de «aprobado/suspendido».
  • -junitxml
    Muestra los resultados como un documento XML de JUnit.
  • -xml
    Muestra los resultados como un documento XML.
  • -lightxml
    Muestra los resultados como un flujo de etiquetas XML.
  • -teamcity
    Muestra los resultados en formato TeamCity.
  • -tap
    Muestra los resultados en formato Test Anything Protocol (TAP).

La primera versión de la opción « -o » puede repetirse para registrar los resultados de las pruebas en varios formatos, pero no puede haber más de una instancia de esta opción registrando resultados de pruebas en la salida estándar.

Si se utiliza la primera versión de la opción « -o », no deben utilizarse ni la segunda versión de la opción « -o » ni las opciones « -txt », « -xml », « -lightxml », « -teamcity », « -junitxml » o « -tap ».

Si no se utiliza ninguna de las dos versiones de la opción « -o », los resultados de las pruebas se registrarán en la salida estándar. Si no se utiliza ninguna opción de formato, los resultados de las pruebas se registrarán en texto sin formato.

Opciones de detalle del registro de pruebas

Las siguientes opciones de línea de comandos controlan el nivel de detalle que se incluye en los registros de pruebas:

    • -silent
      Salida silenciosa; solo muestra errores fatales, fallos en las pruebas y mensajes de estado mínimos.
    • -v1
      Salida detallada; muestra cuándo se ejecuta cada función de prueba. (Esta opción solo afecta a la salida de texto sin formato.)
    • -v2
      Extended verbose output; shows each QCOMPARE() and QVERIFY(). (This option affects all output formats and implies -v1 for plain text output.)
    • -vs
      Muestra todas las señales que se emiten y las invocaciones de ranuras resultantes de dichas señales. (Esta opción afecta a todos los formatos de salida.)

    Opciones de prueba

    Las siguientes opciones de línea de comandos influyen en la forma en que se ejecutan las pruebas:

    • -functions
      Muestra todas las funciones de prueba disponibles en la prueba y, a continuación, se cierra.
    • -datatags
      Muestra todas las etiquetas de datos disponibles en la prueba. Una etiqueta de datos global va precedida de «__global__».
    • -eventdelay ms
      If no delay is specified for keyboard or mouse simulation (QTest::keyClick(), QTest::mouseClick() etc.), the value from this parameter (in milliseconds) is substituted.
    • -keydelay ms
      Igual que -eventdelay, pero solo afecta a la simulación del teclado y no a la del ratón.
    • -mousedelay ms
      Igual que -eventdelay, pero solo afecta a la simulación del ratón y no a la del teclado.
    • -maxwarnings número
      Establece el número máximo de advertencias que se mostrarán. 0 significa ilimitado; el valor por defecto es 2000.
    • -nocrashhandler
      Desactiva el gestor de fallos en plataformas Unix. En Windows, vuelve a activar el cuadro de diálogo «Informes de errores de Windows», que está desactivado por defecto. Esto resulta útil para depurar fallos.
    • -repeat n
      Ejecuta el conjunto de pruebas n veces o hasta que la prueba falle. Útil para detectar pruebas inestables. Si el valor es negativo, las pruebas se repiten indefinidamente. Está pensada como herramienta para desarrolladores y solo es compatible con el registrador de texto sin formato.
    • -skipblacklisted
      Omite las pruebas incluidas en la lista negra. Esta opción tiene como objetivo permitir una medición más precisa de la cobertura de pruebas, evitando que las pruebas de la lista negra inflen las estadísticas de cobertura. Cuando no se mida la cobertura de pruebas, se recomienda ejecutar las pruebas de la lista negra para detectar cualquier cambio en sus resultados, como un nuevo fallo o la resolución del problema que motivó su inclusión en la lista negra.
    • -platform name
      This command line argument applies to all Qt applications, but might be especially useful in the context of auto-testing. By using the "offscreen" platform plugin (-platform offscreen) it's possible to have tests that use QWidget or QWindow run without showing anything on the screen. Currently the offscreen platform plugin is only fully supported on X11.

    Opciones de evaluación comparativa

    Las siguientes opciones de línea de comandos controlan las pruebas de rendimiento:

    • -callgrind
      Utiliza Callgrind para cronometrar las pruebas de rendimiento (Linux y macOS).
    • -perf
      Utiliza eventos de Linux perf para cronometrar las pruebas de rendimiento
    • -tickcounter
      Utiliza los contadores de ticks de la CPU para cronometrar las pruebas de rendimiento. Requiere compatibilidad por parte del hardware.
    • -eventcounter
      Cuenta los eventos recibidos durante las pruebas de rendimiento.
    • -minimumvalue n
      Establece el valor mínimo aceptable de la medición.
    • -minimumtotal n
      Establece el total mínimo aceptable para ejecuciones repetidas de una función de prueba.
    • -iterations n
      Establece el número de iteraciones de acumulación.
    • -median n
      Establece el número de iteraciones medianas.
    • -vb
      Muestra información detallada sobre el rendimiento.

    Opciones varias

    • -help
      Muestra los posibles argumentos de la línea de comandos y ofrece ayuda útil.

    Qt Test Variables de entorno

    Puedes configurar determinadas variables de entorno para influir en la ejecución de una autoprueba:

    • QTEST_DISABLE_CORE_DUMP
      Si se establece esta variable en un valor distinto de cero, se desactivará la generación de un archivo de volcado de memoria.
    • QTEST_DISABLE_STACK_DUMP
      Si se establece esta variable en un valor distinto de cero, se impedirá que Qt Test muestre un seguimiento de la pila en caso de que una autoprueba agote el tiempo de espera o se bloquee.
    • QTEST_FATAL_FAIL
      Si se establece esta variable en un valor distinto de cero, un fallo en una autoprueba provocará la interrupción inmediata de toda la autoprueba. Esto resulta útil, por ejemplo, para depurar un fallo inestable o intermitente en una prueba, ejecutándola en un depurador. La compatibilidad con esta variable se añadió en Qt 6.1.

    Creación de una prueba de rendimiento

    Para crear una prueba de rendimiento, sigue las instrucciones para crear una prueba y, a continuación, añade la macro ` QBENCHMARK ` o ` QTest::setBenchmarkResult()` a la función de prueba que desees someter a la prueba de rendimiento. En el siguiente fragmento de código se utiliza la macro:

    class MyFirstBenchmark: public QObject
    {
        Q_OBJECT
    private slots:
        void myFirstBenchmark()
        {
            QString string1;
            QString string2;
            QBENCHMARK {
                string1.localeAwareCompare(string2);
            }
        }
    };

    Una función de prueba que mida el rendimiento debe contener una única macro « QBENCHMARK » o una única llamada a « setBenchmarkResult() ». No tiene sentido que aparezca más de una vez, ya que solo se puede obtener un resultado de rendimiento por función de prueba o por etiqueta de datos en una configuración basada en datos.

    Evita modificar el código de prueba que conforma (o influye en) el cuerpo de una macro ` QBENCHMARK `, o el código de prueba que calcula el valor pasado a ` setBenchmarkResult()`. Lo ideal es que las diferencias en los resultados de rendimiento sucesivos se deban únicamente a cambios en el producto que estás probando. Los cambios en el código de prueba pueden dar lugar a informes engañosos sobre un cambio en el rendimiento. Si necesitas modificar el código de prueba, indícalo claramente en el mensaje de confirmación.

    En una función de prueba de rendimiento, a QBENCHMARK o setBenchmarkResult() debe seguirle un paso de verificación utilizando QCOMPARE(), QVERIFY() y así sucesivamente. A continuación, puedes marcar un resultado de rendimiento como no válido si se ha medido una ruta de código distinta a la prevista. Una herramienta de análisis de rendimiento puede utilizar esta información para filtrar los resultados no válidos. Por ejemplo, una condición de error inesperada suele provocar que el programa se salga prematuramente de la ejecución normal y, por lo tanto, muestre falsamente un aumento drástico del rendimiento.

    Selección del back-end de medición

    Se medirá el código contenido en la macro QBENCHMARK y, posiblemente, también se repetirá varias veces para obtener una medición precisa. Esto depende del back-end de medición seleccionado. Hay varios back-ends disponibles. Se pueden seleccionar en la línea de comandos (véase Opciones de evaluación comparativa):

    NombreArgumento de la línea de comandosDisponibilidad
    Tiempo de ejecución(por defecto)Todas las plataformas
    Contador de ticks de la CPU-tickcounterWindows, macOS, Linux y muchos sistemas similares a UNIX.
    Contador de eventos-eventcounterTodas las plataformas
    Valgrind Callgrind-callgrindLinux (si está instalado)
    Linux Perf-perfLinux

    En resumen, el tiempo real siempre está disponible, pero requiere muchas repeticiones para obtener un resultado útil. Los contadores de ticks suelen estar disponibles y pueden proporcionar resultados con menos repeticiones, pero pueden ser susceptibles a problemas de escalado de la frecuencia de la CPU. Valgrind proporciona resultados exactos, pero no tiene en cuenta las esperas de E/S y solo está disponible en un número limitado de plataformas. El recuento de eventos está disponible en todas las plataformas y proporciona el número de eventos que recibió el bucle de eventos antes de que se enviaran a sus destinos correspondientes (esto podría incluir eventos que no sean de Qt).

    La solución de supervisión del rendimiento de Linux solo está disponible en Linux y ofrece muchos contadores diferentes, que se pueden seleccionar pasando una opción adicional -perfcounter countername, como -perfcounter cache-misses, -perfcounter branch-misses o -perfcounter l1d-load-misses. El contador predeterminado es cpu-cycles. La lista completa de contadores se puede obtener ejecutando cualquier ejecutable de prueba de rendimiento con la opción -perfcounterlist.

    • El uso del contador de rendimiento puede requerir habilitar el acceso a aplicaciones sin privilegios.
    • Los dispositivos que no admiten temporizadores de alta resolución utilizan por defecto una granularidad de un milisegundo.

    Consulta «Escribir una prueba de rendimiento» en el tutorial « Qt Test » para ver más ejemplos de pruebas de rendimiento.

    Uso de datos de prueba globales

    Puedes definir « initTestCase_data() » para configurar una tabla de datos de prueba global. Cada prueba se ejecuta una vez por cada fila de la tabla de datos de prueba global. Cuando la propia función de prueba está basada en datos, se ejecuta para cada fila de datos locales y para cada fila de datos globales. Así pues, si hay g filas en la tabla de datos global y d filas en la propia tabla de datos de la prueba, el número de ejecuciones de esta prueba es g veces d.

    Los datos globales se obtienen de la tabla mediante la macro QFETCH_GLOBAL().

    A continuación se presentan algunos casos de uso típicos de los datos globales de prueba:

    • Seleccionar entre los backends de base de datos disponibles en las pruebas QSql para ejecutar cada prueba en cada base de datos.
    • Realizar todas las pruebas de red con y sin SSL (HTTP frente a HTTPS) y mediante un proxy.
    • Probar un temporizador con un reloj de alta precisión y con uno de precisión aproximada.
    • Seleccionar si un analizador sintáctico debe leer desde un archivo « QByteArray » o desde un archivo « QIODevice ».

    Por ejemplo, para probar cada número proporcionado por roundTripInt_data() con cada configuración regional proporcionada por initTestCase_data():

    void TestQLocale::roundTripInt()
    {
        QFETCH_GLOBAL(QLocale, locale);
        QFETCH(int, number);
        bool ok;
        QCOMPARE(locale.toInt(locale.toString(number), &ok), number);
        QVERIFY(ok);
    }

    En la línea de comandos de una prueba, puedes pasar el nombre de una función (sin el prefijo del nombre de la clase de prueba) para ejecutar únicamente las pruebas de esa función. Si la clase de prueba tiene datos globales, o si la función está basada en datos, puedes añadir una etiqueta de datos, tras dos puntos, para ejecutar únicamente el conjunto de datos de esa etiqueta para la función. Para especificar tanto una etiqueta global como una etiqueta específica de la función de prueba, combínalas separadas por dos puntos, colocando primero la etiqueta de datos globales. Por ejemplo:

    ./testqlocale roundTripInt:zero

    ejecutará el caso de prueba « zero » de la prueba « roundTripInt() » anterior (suponiendo que su clase « TestQLocale » se haya compilado en un ejecutable « testqlocale ») en cada una de las configuraciones regionales especificadas por « initTestCase_data() », mientras que

    ./testqlocale roundTripInt:C

    ejecutará los tres casos de prueba de roundTripInt() únicamente en la configuración regional C y

    ./testqlocale roundTripInt:C:zero

    solo ejecutará el caso de prueba « zero » en la configuración regional C.

    Disponer de un control tan preciso sobre qué pruebas se van a ejecutar puede facilitar considerablemente la depuración de un problema, ya que solo es necesario recorrer paso a paso el único caso de prueba que se ha comprobado que falla.

    © 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.