@@ -54,8 +54,9 @@ Developers guide for QGIS
3.1. The QGIS testing framework - an overview
3.2. Creating a unit test
3.3. Adding your unit test to CMakeLists.txt
3.4. Building your unit test
3.5. Run your tests
3.4. The ADD_QGIS_TEST macro explained
3.5. Building your unit test
3.6. Run your tests
4. HIG (Human Interface Guidelines)
5. Authors
@@ -1136,28 +1137,50 @@ line is the include for the MOC generated sources. You should replace
Adding your unit test to the build system is simply a matter of editing the
CMakeLists.txt in the test directory, cloning one of the existing test blocks,
and then search and replacing your test class name into it. For example:
and then replacing your test class name into it. For example:
#
# QgsRasterLayer test
#
SET(qgis_rasterlayertest_SRCS testqgsrasterlayer.cpp)
SET(qgis_rasterlayertest_MOC_CPPS testqgsrasterlayer.cpp)
QT4_WRAP_CPP(qgis_rasterlayertest_MOC_SRCS ${qgis_rasterlayertest_MOC_CPPS})
ADD_CUSTOM_TARGET(qgis_rasterlayertestmoc ALL DEPENDS ${qgis_rasterlayertest_MOC_SRCS})
ADD_EXECUTABLE(qgis_rasterlayertest ${qgis_rasterlayertest_SRCS})
ADD_DEPENDENCIES(qgis_rasterlayertest qgis_rasterlayertestmoc)
TARGET_LINK_LIBRARIES(qgis_rasterlayertest ${QT_LIBRARIES} qgis_core)
INSTALL(TARGETS qgis_rasterlayertest RUNTIME DESTINATION ${QGIS_BIN_DIR})
ADD_TEST(qgis_rasterlayertest ${QGIS_BIN_DIR}/qgis_rasterlayertest)
ADD_QGIS_TEST(rasterlayertest testqgsrasterlayer.cpp)
I'll run through these lines briefly to explain what they do, but if you are
not interested, just clone the block, search and replace e.g.
3.4. The ADD_QGIS_TEST macro explained
======================================
:'<,'>s/rasterlayer/mynewtest/g
I'll run through these lines briefly to explain what they do, but if you are
not interested, just do the step explained in the above section and section.
MACRO (ADD_QGIS_TEST testname testsrc)
SET(qgis_${testname}_SRCS ${testsrc} ${util_SRCS})
SET(qgis_${testname}_MOC_CPPS ${testsrc})
QT4_WRAP_CPP(qgis_${testname}_MOC_SRCS ${qgis_${testname}_MOC_CPPS})
ADD_CUSTOM_TARGET(qgis_${testname}moc ALL DEPENDS ${qgis_${testname}_MOC_SRCS})
ADD_EXECUTABLE(qgis_${testname} ${qgis_${testname}_SRCS})
ADD_DEPENDENCIES(qgis_${testname} qgis_${testname}moc)
TARGET_LINK_LIBRARIES(qgis_${testname} ${QT_LIBRARIES} qgis_core)
SET_TARGET_PROPERTIES(qgis_${testname}
PROPERTIES
# skip the full RPATH for the build tree
SKIP_BUILD_RPATH TRUE
# when building, use the install RPATH already
# (so it doesn't need to relink when installing)
BUILD_WITH_INSTALL_RPATH TRUE
# the RPATH to be used when installing
INSTALL_RPATH ${QGIS_LIB_DIR}
# add the automatically determined parts of the RPATH
# which point to directories outside the build tree to the install RPATH
INSTALL_RPATH_USE_LINK_PATH true)
IF (APPLE)
# For Mac OS X, the executable must be at the root of the bundle's executable folder
INSTALL(TARGETS qgis_${testname} RUNTIME DESTINATION ${CMAKE_INSTALL_PREFIX})
ADD_TEST(qgis_${testname} ${CMAKE_INSTALL_PREFIX}/qgis_${testname})
ELSE (APPLE)
INSTALL(TARGETS qgis_${testname} RUNTIME DESTINATION ${CMAKE_INSTALL_PREFIX}/bin)
ADD_TEST(qgis_${testname} ${CMAKE_INSTALL_PREFIX}/bin/qgis_${testname})
ENDIF (APPLE)
ENDMACRO (ADD_QGIS_TEST)
Lets look a little more in detail at the individual lines. First we define the
@@ -1166,16 +1189,16 @@ methodology I described above where class declaration and definition are in the
same file) its a simple statement:
SET(qgis_rasterlayertest_SRCS testqgsrasterlayer.cpp )
SET(qgis_${testname}_SRCS ${testsrc} ${util_SRCS} )
Since our test class needs to be run through the Qt meta object compiler (moc)
we need to provide a couple of lines to make that happen too:
SET(qgis_rasterlayertest_MOC_CPPS testqgsrasterlayer.cpp )
QT4_WRAP_CPP(qgis_rasterlayertest_MOC_SRCS ${qgis_rasterlayertest_MOC_CPPS })
ADD_CUSTOM_TARGET(qgis_rasterlayertestmoc ALL DEPENDS ${qgis_rasterlayertest_MOC_SRCS })
SET(qgis_${testname}_MOC_CPPS ${testsrc} )
QT4_WRAP_CPP(qgis_${testname}_MOC_SRCS ${qgis_${testname}_MOC_CPPS })
ADD_CUSTOM_TARGET(qgis_${testname}moc ALL DEPENDS ${qgis_${testname}_MOC_SRCS })
Next we tell cmake that it must make an executeable from the test class.
@@ -1185,8 +1208,8 @@ included the moc outputs directly into our test class, so that will give it
executeable:
ADD_EXECUTABLE(qgis_rasterlayertest ${qgis_rasterlayertest_SRCS })
ADD_DEPENDENCIES(qgis_rasterlayertest qgis_rasterlayertestmoc )
ADD_EXECUTABLE(qgis_${testname} ${qgis_${testname}_SRCS })
ADD_DEPENDENCIES(qgis_${testname} qgis_${testname}moc )
Next we need to specify any library dependencies. At the moment classes have
@@ -1196,38 +1219,49 @@ only. Of course you also need to link to the relevant qgis libraries as
required by your unit test.
TARGET_LINK_LIBRARIES(qgis_rasterlayertest ${QT_LIBRARIES} qgis_core)
Next I tell cmake to the same place as the qgis binaries itself. This is
something I plan to remove in the future so that the tests can run directly
from inside the source tree.
INSTALL(TARGETS qgis_rasterlayertest RUNTIME DESTINATION ${QGIS_BIN_DIR})
Finally here is where the best magic happens - we register the class with
ctest. If you recall in the overview I gave in the beginning of this section we
are using both QtTest and CTest together. To recap, QtTest adds a main
method to your test unit and handles calling your test methods within the
class. It also provides some macros like QVERIFY that you can use as to test
for failure of the tests using conditions. The output from a QtTest unit test
is an executeable which you can run from the command line. However when you
have a suite of tests and you want to run each executeable in turn, and
better yet integrate running tests into the build process, the CTest is
what we use. The next line registers the unit test with CMake / CTest.
ADD_TEST(qgis_rasterlayertest ${QGIS_BIN_DIR}/qgis_rasterlayertest)
The last thing I should add is that if your test requires optional parts of the
build process (e.g. Postgresql support, GSL libs, GRASS etc.), you should take
care to enclose you test block inside a IF () block in the CMakeLists.txt file.
3.4. Building your unit test
TARGET_LINK_LIBRARIES(qgis_${testname} ${QT_LIBRARIES} qgis_core)
Next I tell cmake to install the tests to the same place as the qgis binaries
itself. This is something I plan to remove in the future so that the tests can
run directly from inside the source tree.
SET_TARGET_PROPERTIES(qgis_${testname}
PROPERTIES
# skip the full RPATH for the build tree
SKIP_BUILD_RPATH TRUE
# when building, use the install RPATH already
# (so it doesn't need to relink when installing)
BUILD_WITH_INSTALL_RPATH TRUE
# the RPATH to be used when installing
INSTALL_RPATH ${QGIS_LIB_DIR}
# add the automatically determined parts of the RPATH
# which point to directories outside the build tree to the install RPATH
INSTALL_RPATH_USE_LINK_PATH true)
IF (APPLE)
# For Mac OS X, the executable must be at the root of the bundle's executable folder
INSTALL(TARGETS qgis_${testname} RUNTIME DESTINATION ${CMAKE_INSTALL_PREFIX})
ADD_TEST(qgis_${testname} ${CMAKE_INSTALL_PREFIX}/qgis_${testname})
ELSE (APPLE)
INSTALL(TARGETS qgis_${testname} RUNTIME DESTINATION ${CMAKE_INSTALL_PREFIX}/bin)
ADD_TEST(qgis_${testname} ${CMAKE_INSTALL_PREFIX}/bin/qgis_${testname})
ENDIF (APPLE)
Finally the above uses ADD_TEST to register the test with cmake / ctest . Here
is where the best magic happens - we register the class with ctest. If you
recall in the overview I gave in the beginning of this section we are using
both QtTest and CTest together. To recap, QtTest adds a main method to your
test unit and handles calling your test methods within the class. It also
provides some macros like QVERIFY that you can use as to test for failure of
the tests using conditions. The output from a QtTest unit test is an
executeable which you can run from the command line. However when you have a
suite of tests and you want to run each executeable in turn, and better yet
integrate running tests into the build process, the CTest is what we use.
3.5. Building your unit test
============================
To build the unit test you need only to make sure that ENABLE_TESTS=true in the
@@ -1240,7 +1274,7 @@ cmake configuration. There are two ways to do this:
Other than that, just build QGIS as per normal and the tests should build too.
3.5 . Run your tests
3.6 . Run your tests
===================
The simplest way to run the tests is as part of your normal build process: