Chapter 1: Writing a Unit Test | Qt Test | Qt 6.10.3
Description: How to write a unit test.

- Qt 6.10
- Qt Test
- Qt Test Tutorial
- Chapter 1: Writing a Unit Test
- Qt 6.10.3 Reference Documentation

Qt Test Tutorial ◦ Chapter 2: Data Driven Testing

# Chapter 1: Writing a Unit Test

This first chapter demonstrates how to write a simple unit test and how to run the test case as a stand-alone executable.

## Writing a Test

Let's assume you want to test the behavior of our QString class. First, you need a class that contains your test functions. This class has to inherit from QObject:

     #include <QTest>

     class TestQString: public QObject
     {
         Q_OBJECT
     private slots:
         void toUpper();
     };

Note: You need to include the QTest header and declare the test functions as private slots so the test framework finds and executes it.

Then you need to implement the test function itself. The implementation could look like this:

     void TestQString::toUpper()
     {
         QString str = "Hello";
         QVERIFY(str.toUpper() == "HELLO");
     }

The QVERIFY() macro evaluates the expression passed as its argument. If the expression evaluates to true, the execution of the test function continues. Otherwise, a message describing the failure is appended to the test log, and the test function stops executing.

But if you want a more verbose output to the test log, you should use the QCOMPARE() macro instead:

     void TestQString::toUpper()
     {
         QString str = "Hello";
         QCOMPARE(str.toUpper(), QString("HELLO"));
     }

If the strings are not equal, the contents of both strings are appended to the test log, making it immediately visible why the comparison failed.

## Preparing the Stand-Alone Executable

Finally, to make our test case a stand-alone executable, the following two lines are needed:

     QTEST_MAIN(TestQString)
     #include "testqstring.moc"

The QTEST_MAIN() macro expands to a simple `main()` method that runs all the test functions. Note that if both the declaration and the implementation of our test class are in a `.cpp` file, we also need to include the generated moc file to make Qt's introspection work.

## Building the Executable

You can build the test case executable using CMake or qmake.

### Building with CMake

Configure your build settings in your CMakeLists.txt file:

     # Copyright (C) 2022 The Qt Company Ltd.
     # SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

     cmake_minimum_required(VERSION 3.16)
     project(tutorial1 LANGUAGES CXX)

     find_package(Qt6 REQUIRED COMPONENTS Core Gui Test Widgets)

     qt_standard_project_setup()

     qt_add_executable(tutorial1
         testqstring.cpp
     )

     set_target_properties(tutorial1 PROPERTIES
         WIN32_EXECUTABLE TRUE
         MACOSX_BUNDLE TRUE
     )

     target_link_libraries(tutorial1 PRIVATE
         Qt6::Core
         Qt6::Gui
         Qt6::Test
         Qt6::Widgets
     )

     install(TARGETS tutorial1
         BUNDLE  DESTINATION .
         RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
         LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
     )

     qt_generate_deploy_app_script(
         TARGET tutorial1
         OUTPUT_SCRIPT deploy_script
         NO_UNSUPPORTED_PLATFORM_ERROR
     )
     install(SCRIPT ${deploy_script})

Next, from the command line, run either `cmake` or use the `qt-cmake` convenience script located in `Qt-prefix/<version>/<platform>/bin/qt-cmake`:

     <Qt-prefix>/<version>/<platform>/bin/qt-cmake <source-dir> <build-dir> -G Ninja

Then, run your preferred generator tool to build the executable. Here, we're using Ninja:

     ninja

### Building with qmake

Configure your build settings in your `.pro` file:

     QT += widgets testlib

     SOURCES = testqstring.cpp

     # install
     target.path = $$[QT_INSTALL_EXAMPLES]/qtestlib/tutorial1
     INSTALLS += target

Next, run `qmake`, and, finally, run `make` to build your executable:

     qmake
     make

Note: If you're using windows, replace `make` with `nmake` or whatever build tool you use.

## Running the Executable

Running the resulting executable should give you the following output:

     ********* Start testing of TestQString *********
     Config: Using QtTest library %VERSION%, Qt %VERSION%
     PASS   : TestQString::initTestCase()
     PASS   : TestQString::toUpper()
     PASS   : TestQString::cleanupTestCase()
     Totals: 3 passed, 0 failed, 0 skipped
     ********* Finished testing of TestQString *********

Congratulations! You just wrote and executed your first unit test using the Qt Test framework.

Qt Test Tutorial ◦ Chapter 2: Data Driven Testing