View source for New Unit Test Structure

[[Category:Developing_Qt::QA]]

= New Unit Test Structure for Qt =

== Introduction ==

This article focuses on the structure beneath <tt>tests/auto/</tt> so that you know exactly where to put your tests.

== Autotest Structure ==

Whenever something is submitted to [https://codereview.qt-project.org/ Gerrit], it will be tested by [[CI_Configurations|CI System]].

The testing is done by executing tests located under <tt>tests/auto/</tt>.

Questions to ask:

* Where to put the test for my new class?
* Where is the test for the class containing my new function?

The proposed answer to these questions is:

The directory structure of the tests should resemble the directory structure of the Qt source itself as much as possible.

The structural resemblance has two advantages:

# It is easy to locate the test for a particular class.
# It is easy to test a certain functional area in isolation.

Consider the <tt>QMutex</tt> class for example. This resides in <tt>src/corelib/thread/</tt> and the corresponding test is located under <tt>tests/auto/corelib/thread/qmutex/</tt>.

As another example, let's say that you have made a change that is likely to affect code under <tt>src/corelib/</tt> only. You can now execute a recursive test runner (such as '<tt>make check</tt>') locally from <tt>tests/auto/corelib/</tt> and thus save time by running only the tests that are likely to be sensitive to the change. (Of course, at some point, a full test run needs to be executed, but that can happen less frequently.)

== Current state ==

By the time of this writing, test restructuring has been done for QtBase only (and there is still a bit
cleanup to be done). The principle should be applied to other modules as well, and will be the responsibility
of the Qt community as a whole.

The test structure in QtBase currently looks essentially like this:

<code>
auto
 corelib
 animation
 qabstractanimation <— tests for 'qabstractanimation' go here
 qanimationgroup
 ...
 ...
 thread
 qmutex <— tests for 'qmutex' go here
 qsemaphore
 ...
 ...
 dbus
 gui
 integrationtests
 network
 opengl
 other
 sql
 testlib
 tools
 xml
 v8
</code>