Contents

• Classes
• Types
• Functions
• Macros
• Detailed Description

Detailed Description

TheQTest namespace contains all the functions and declarations that are related to theQTestLib tool.

Please refer to theQTestLib Manual documentation for information on how to write unit tests.

Classes

classQTouchEventSequence

TheQTouchEventSequence class is used to simulate a sequence of touch events.More...

Type Documentation

enum QTest::AttributeIndex

This enum numbers the different tests.

enum QTest::KeyAction

This enum describes possible actions for key handling.

enum QTest::LogElementType

The enum specifies the kinds of test log messages.

enum QTest::MouseAction

This enum describes possible actions for mouse handling.

enum QTest::QBenchmarkMetric

This enum lists all the things that can be benchmarked.

This enum was introduced or modified in Qt 4.7.

See alsoQTest::benchmarkMetricName() andQTest::benchmarkMetricUnit().

enum QTest::SkipMode

This enum describes the modes for skipping tests during execution of the test data.

See alsoQSKIP().

enum QTest::TestFailMode

This enum describes the modes for handling an expected failure of theQVERIFY() orQCOMPARE() macros.

See alsoQEXPECT_FAIL().

Function Documentation

void QTest::addColumn(constchar * name,T * dummy = 0)

Adds a column with typeT to the current test data.name is the name of the column.dummy is a workaround for buggy compilers and can be ignored.

To populate the column with values,newRow() can be used. UseQFETCH() to fetch the data in the actual test.

Example:

void myTestFunction_data() {QTest::addColumn<int>("intval");QTest::addColumn<QString>("str");QTest::addColumn<double>("dbl");QTest::newRow("row1")<<1<<"hello"<<1.5;}

To add custom types to the testdata, the type must be registered withQMetaType viaQ_DECLARE_METATYPE().

Note: This macro can only be used in a test's data function that is invoked by the test framework.

SeeData Driven Testing for a more extensive example.

See alsoQTest::newRow(),QFETCH(), andQMetaType.

constchar * QTest::benchmarkMetricName(QBenchmarkMetric metric)

Returns the enum valuemetric as a character string.

This function was introduced in Qt 4.7.

constchar * QTest::benchmarkMetricName(QBenchmarkMetric metric)

Returns the enum valuemetric as a character string.

This function was introduced in Qt 4.7.

constchar * QTest::benchmarkMetricUnit(QBenchmarkMetric metric)

Retuns the units of measure for the specifiedmetric.

This function was introduced in Qt 4.7.

constchar * QTest::benchmarkMetricUnit(QBenchmarkMetric metric)

Retuns the units of measure for the specifiedmetric.

This function was introduced in Qt 4.7.

constchar * QTest::currentAppName()

Returns the name of the binary that is currently executed.

constchar * QTest::currentDataTag()

Returns the name of the current test data. If the test doesn't have any assigned testdata, the function returns 0.

bool QTest::currentTestFailed()

Returns true if the current test function failed, otherwise false.

constchar * QTest::currentTestFunction()

Returns the name of the test function that is currently executed.

Example:

void MyTestClass::cleanup(){if (qstrcmp(currentTestFunction(),"myDatabaseTest")==0) {// clean up all database connections        closeAllDatabases();    }}

void QTest::ignoreMessage(QtMsgType type, constchar * message)

Ignores messages created byqDebug() orqWarning(). If themessage with the correspondingtype is outputted, it will be removed from the test log. If the test finished and themessage was not outputted, a test failure is appended to the test log.

Note: Invoking this function will only ignore one message. If the message you want to ignore is outputted twice, you have to call ignoreMessage() twice, too.

Example:

QDir dir;QTest::ignoreMessage(QtWarningMsg,"QDir::mkdir: Empty or null file name(s)");dir.mkdir("");

The example above tests thatQDir::mkdir() outputs the right warning when invoked with an invalid file name.

[static]void QTest::keyClick(QWidget * widget,Qt::Key key,Qt::KeyboardModifiers modifier = Qt::NoModifier,int delay = -1)

Simulates clicking ofkey with an optionalmodifier on awidget. Ifdelay is larger than 0, the test will wait fordelay milliseconds.

Examples:

QTest::keyClick(myWidget,Qt::Key_Escape);QTest::keyClick(myWidget,Qt::Key_Escape,Qt::ShiftModifier,200);

The first example above simulates clicking theescape key onmyWidget without any keyboard modifiers and without delay. The second example simulates clickingshift-escape onmyWidget with a following 200 ms delay of the test.

See alsoQTest::keyClicks().

[static]void QTest::keyClick(QWidget * widget,char key,Qt::KeyboardModifiers modifier = Qt::NoModifier,int delay = -1)

This is an overloaded function.

Simulates clicking ofkey with an optionalmodifier on awidget. Ifdelay is larger than 0, the test will wait fordelay milliseconds.

Example:

QTest::keyClick(myWidget,'a');

The example above simulates clickinga onmyWidget without any keyboard modifiers and without delay of the test.

See alsoQTest::keyClicks().

[static]void QTest::keyClicks(QWidget * widget, constQString & sequence,Qt::KeyboardModifiers modifier = Qt::NoModifier,int delay = -1)

Simulates clicking asequence of keys on awidget. Optionally, a keyboardmodifier can be specified as well as adelay (in milliseconds) of the test before each key click.

Example:

QTest::keyClicks(myWidget,"hello world");

The example above simulates clicking the sequence of keys representing "hello world" onmyWidget without any keyboard modifiers and without delay of the test.

See alsoQTest::keyClick().

[static]void QTest::keyEvent(KeyAction action,QWidget * widget,Qt::Key key,Qt::KeyboardModifiers modifier = Qt::NoModifier,int delay = -1)

Sends a Qt key event towidget with the givenkey and an associatedaction. Optionally, a keyboardmodifier can be specified, as well as adelay (in milliseconds) of the test before sending the event.

[static]void QTest::keyEvent(KeyAction action,QWidget * widget,char ascii,Qt::KeyboardModifiers modifier = Qt::NoModifier,int delay = -1)

This is an overloaded function.

Sends a Qt key event towidget with the given keyascii and an associatedaction. Optionally, a keyboardmodifier can be specified, as well as adelay (in milliseconds) of the test before sending the event.

[static]void QTest::keyPress(QWidget * widget,Qt::Key key,Qt::KeyboardModifiers modifier = Qt::NoModifier,int delay = -1)

Simulates pressing akey with an optionalmodifier on awidget. Ifdelay is larger than 0, the test will wait fordelay milliseconds.

Note: At some point you should release the key usingkeyRelease().

See alsoQTest::keyRelease() andQTest::keyClick().

[static]void QTest::keyPress(QWidget * widget,char key,Qt::KeyboardModifiers modifier = Qt::NoModifier,int delay = -1)

This is an overloaded function.

Simulates pressing akey with an optionalmodifier on awidget. Ifdelay is larger than 0, the test will wait fordelay milliseconds.

Note: At some point you should release the key usingkeyRelease().

See alsoQTest::keyRelease() andQTest::keyClick().

[static]void QTest::keyRelease(QWidget * widget,Qt::Key key,Qt::KeyboardModifiers modifier = Qt::NoModifier,int delay = -1)

Simulates releasing akey with an optionalmodifier on awidget. Ifdelay is larger than 0, the test will wait fordelay milliseconds.

See alsoQTest::keyPress() andQTest::keyClick().

[static]void QTest::keyRelease(QWidget * widget,char key,Qt::KeyboardModifiers modifier = Qt::NoModifier,int delay = -1)

This is an overloaded function.

Simulates releasing akey with an optionalmodifier on awidget. Ifdelay is larger than 0, the test will wait fordelay milliseconds.

See alsoQTest::keyClick().

void QTest::mouseClick(QWidget * widget,Qt::MouseButton button,Qt::KeyboardModifiers modifier = 0,QPoint pos = QPoint(),int delay = -1)

Simulates clicking a mousebutton with an optionalmodifier on awidget. The position of the click is defined bypos; the default position is the center of the widget. Ifdelay is specified, the test will wait for the specified amount of milliseconds before pressing and before releasing the button.

See alsoQTest::mousePress() andQTest::mouseRelease().

void QTest::mouseDClick(QWidget * widget,Qt::MouseButton button,Qt::KeyboardModifiers modifier = 0,QPoint pos = QPoint(),int delay = -1)

Simulates double clicking a mousebutton with an optionalmodifier on awidget. The position of the click is defined bypos; the default position is the center of the widget. Ifdelay is specified, the test will wait for the specified amount of milliseconds before each press and release.

See alsoQTest::mouseClick().

void QTest::mouseMove(QWidget * widget,QPoint pos = QPoint(),int delay = -1)

Moves the mouse pointer to awidget. Ifpos is not specified, the mouse pointer moves to the center of the widget. If adelay (in milliseconds) is given, the test will wait before moving the mouse pointer.

void QTest::mousePress(QWidget * widget,Qt::MouseButton button,Qt::KeyboardModifiers modifier = 0,QPoint pos = QPoint(),int delay = -1)

Simulates pressing a mousebutton with an optionalmodifier on awidget. The position is defined bypos; the default position is the center of the widget. Ifdelay is specified, the test will wait for the specified amount of milliseconds before the press.

See alsoQTest::mouseRelease() andQTest::mouseClick().

void QTest::mouseRelease(QWidget * widget,Qt::MouseButton button,Qt::KeyboardModifiers modifier = 0,QPoint pos = QPoint(),int delay = -1)

Simulates releasing a mousebutton with an optionalmodifier on awidget. The position of the release is defined bypos; the default position is the center of the widget. Ifdelay is specified, the test will wait for the specified amount of milliseconds before releasing the button.

See alsoQTest::mousePress() andQTest::mouseClick().

QTestData & QTest::newRow(constchar * dataTag)

Appends a new row to the current test data.dataTag is the name of the testdata that will appear in the test output. Returns a QTestData reference that can be used to stream in data.

Example:

void myTestFunction_data(){QTest::addColumn<QString>("aString");QTest::newRow("just hello")<<QString("hello");QTest::newRow("a null string")<<QString();}

Note: This macro can only be used in a test's data function that is invoked by the test framework.

SeeData Driven Testing for a more extensive example.

See alsoaddColumn() andQFETCH().

int QTest::qExec(QObject * testObject,int argc = 0,char ** argv = 0)

Executes tests declared intestObject. In addition, the private slotsinitTestCase(),cleanupTestCase(),init() andcleanup() are executed if they exist. SeeCreating a Test for more details.

Optionally, the command line argumentsargc andargv can be provided. For a list of recognized arguments, readQTestLib Command Line Arguments.

For stand-alone tests, the convenience macroQTEST_MAIN() can be used to declare a main method that parses the command line arguments and executes the tests.

Returns 0 if all tests passed. Returns a value other than 0 if tests failed or in case of unhandled exceptions. The return value from this function is also the exit code of the test application when theQTEST_MAIN() macro is used.

The following example will run all tests inMyFirstTestObject andMySecondTestObject:

MyFirstTestObject test1;QTest::qExec(&test1);MySecondTestObject test2;QTest::qExec(&test2);

Note: This function is not reentrant, only one test can run at a time. A test that was executed with qExec() can't run another test via qExec() and threads are not allowed to call qExec() simultaneously.

If you have programatically created the arguments, as opposed to getting them from the arguments inmain(), it is likely of interest to use QTest::qExec(QObject *, constQStringList &) since it is Unicode safe.

See alsoQTEST_MAIN().

int QTest::qExec(QObject * testObject, constQStringList & arguments)

This is an overloaded function.

Behaves identically toqExec(QObject *, int, char**) but takes aQStringList ofarguments instead of achar** list.

This function was introduced in Qt 4.4.

void QTest::qSleep(int ms)

Sleeps forms milliseconds, blocking execution of the test. qSleep() will not do any event processing and leave your test unresponsive. Network communication might time out while sleeping. UseqWait() to do non-blocking sleeping.

ms must be greater than 0.

Note: The qSleep() function calls eithernanosleep() on unix orSleep() on windows, so the accuracy of time spent in qSleep() depends on the operating system.

Example:

QTest::qSleep(250);

See alsoqWait().

[static]void QTest::qWait(int ms)

Waits forms milliseconds. While waiting, events will be processed and your test will stay responsive to user interface events or network communication.

Example:

int i=0;while (myNetworkServerNotResponding()&& i++<50)QTest::qWait(250);

The code above will wait until the network server is responding for a maximum of about 12.5 seconds.

See alsoQTest::qSleep().

[static]bool QTest::qWaitForWindowShown(QWidget * window)

Waits until thewindow is shown in the screen. This is mainly useful for asynchronous systems like X11, where a window will be mapped to screen some time after being asked to show itself on the screen. Returns true.

Example:

QWidget widget;widget.show();QTest::qWaitForWindowShown(&widget);

This function was introduced in Qt 4.6.

void QTest::setBenchmarkResult(qreal result,QBenchmarkMetric metric)

Sets the benchmark result for this test function toresult.

Use this function if you want to report benchmark results without using the QBENCHMARK macro. Usemetric to specify howQTestLib should interpret the results.

The context for the result will be the test function name and any data tag from the _data function. This function can only be called once in each test function, subsequent calls will replace the earlier reported results.

Note that the -iterations command line argument has no effect on test functions without the QBENCHMARK macro.

This function was introduced in Qt 4.7.

char * QTest::toHexRepresentation(constchar * ba,int length)

Returns a pointer to a string that is the stringba represented as a space-separated sequence of hex characters. If the input is considered too long, it is truncated. A trucation is indicated in the returned string as an ellipsis at the end.

length is the length of the stringba.

char * QTest::toString(constT & value)

Returns a textual representation ofvalue. This function is used byQCOMPARE() to output verbose information in case of a test failure.

You can add specializations of this function to your test to enable verbose output.

Note: The caller of toString() must delete the returned data usingdelete[]. Your implementation should return a string created withnew[] orqstrdup().

Example:

namespaceQTest {template<>char*toString(const MyPoint&point)    {QByteArray ba="MyPoint(";        ba+=QByteArray::number(point.x())+", "+QByteArray::number(point.y());        ba+=")";return qstrdup(ba.data());    }}

The example above defines a toString() specialization for a class calledMyPoint. Whenever a comparison of two instances ofMyPoint fails,QCOMPARE() will call this function to output the contents ofMyPoint to the test log.

See alsoQCOMPARE().

char * QTest::toString(constQLatin1String & string)

This is an overloaded function.

Returns a textual representation of the givenstring.

char * QTest::toString(constQString & string)

This is an overloaded function.

Returns a textual representation of the givenstring.

char * QTest::toString(constQByteArray & ba)

This is an overloaded function.

Returns a textual representation of the byte arrayba.

See alsoQTest::toHexRepresentation().

char * QTest::toString(constQTime & time)

This is an overloaded function.

Returns a textual representation of the giventime.

char * QTest::toString(constQDate & date)

This is an overloaded function.

Returns a textual representation of the givendate.

char * QTest::toString(constQDateTime & dateTime)

This is an overloaded function.

Returns a textual representation of the date and time specified bydateTime.

char * QTest::toString(constQChar & character)

This is an overloaded function.

Returns a textual representation of the givencharacter.

char * QTest::toString(constQPoint & point)

This is an overloaded function.

Returns a textual representation of the givenpoint.

char * QTest::toString(constQSize & size)

This is an overloaded function.

Returns a textual representation of the givensize.

char * QTest::toString(constQRect & rectangle)

This is an overloaded function.

Returns a textual representation of the givenrectangle.

char * QTest::toString(constQUrl & url)

This is an overloaded function.

Returns a textual representation of the givenurl.

This function was introduced in Qt 4.4.

char * QTest::toString(constQPointF & point)

This is an overloaded function.

Returns a textual representation of the givenpoint.

char * QTest::toString(constQSizeF & size)

This is an overloaded function.

Returns a textual representation of the givensize.

char * QTest::toString(constQRectF & rectangle)

This is an overloaded function.

Returns a textual representation of the givenrectangle.

char * QTest::toString(constQVariant & variant)

This is an overloaded function.

Returns a textual representation of the givenvariant.

QTouchEventSequence QTest::touchEvent(QWidget * widget = 0,QTouchEvent::DeviceType deviceType = QTouchEvent::TouchScreen)

Creates and returns aQTouchEventSequence for the devicedeviceType to simulate events forwidget.

When adding touch events to the sequence,widget will also be used to translate the position provided to screen coordinates, unless another widget is provided in the respective calls to press(), move() etc.

The touch events are committed to the event system when the destructor of theQTouchEventSequence is called (ie when the object returned runs out of scope).

Macro Documentation

QBENCHMARK

This macro is used to measure the performance of code within a test. The code to be benchmarked is contained within a code block following this macro.

For example:

void TestBenchmark::simple(){QString str1= QLatin1String("This is a test string");QString str2= QLatin1String("This is a test string");    QCOMPARE(str1.localeAwareCompare(str2),0);    QBENCHMARK {        str1.localeAwareCompare(str2);    }}

See alsoCreating a Benchmark andWriting a Benchmark.

QBENCHMARK_ONCE

The QBENCHMARK_ONCE macro is for measuring performance of a code block by running it once.

This macro is used to measure the performance of code within a test. The code to be benchmarked is contained within a code block following this macro.

Unlike QBENCHMARK, the contents of the contained code block is only run once. The elapsed time will be reported as "0" if it's to short to be measured by the selected backend. (Use)

This function was introduced in Qt 4.6.

See alsoCreating a Benchmark andWriting a Benchmark.

QCOMPARE( actual, expected)

The QCOMPARE macro compares anactual value to anexpected value using the equals operator. Ifactual andexpected are identical, execution continues. If not, a failure is recorded in the test log and the test won't be executed further.

In the case of comparing floats and doubles,qFuzzyCompare() is used for comparing. This means that comparing to 0 will likely fail. One solution to this is to compare to 1, and add 1 to the produced output.

QCOMPARE tries to output the contents of the values if the comparison fails, so it is visible from the test log why the comparison failed.

QCOMPARE is very strict on the data types. Bothactual andexpected have to be of the same type, otherwise the test won't compile. This prohibits unspecified behavior from being introduced; that is behavior that usually occurs when the compiler implicitly casts the argument.

If you use QCOMPARE() to compare twoQStringList objects, it will start comparing the objects from the end of the lists.

For your own classes, you can useQTest::toString() to format values for outputting into the test log.

Note:This macro can only be used in a test function that is invoked by the test framework.

Example:

QCOMPARE(QString("hello").toUpper(),QString("HELLO"));

See alsoQVERIFY() andQTest::toString().

QEXPECT_FAIL( dataIndex, comment, mode)

The QEXPECT_FAIL() macro marks the nextQCOMPARE() orQVERIFY() as an expected failure. Instead of adding a failure to the test log, an expected failure will be reported.

If aQVERIFY() orQCOMPARE() is marked as an expected failure, but passes instead, an unexpected pass (XPASS) is written to the test log.

The parameterdataIndex describes for which entry in the test data the failure is expected. Pass an empty string ("") if the failure is expected for all entries or if no test data exists.

comment will be appended to the test log for the expected failure.

mode is aQTest::TestFailMode and sets whether the test should continue to execute or not.

Note: This macro can only be used in a test function that is invoked by the test framework.

Example 1:

QEXPECT_FAIL("","Will fix in the next release", Continue);QCOMPARE(i,42);QCOMPARE(j,43);

In the example above, an expected fail will be written into the test output if the variablei is not 42. If the variablei is 42, an unexpected pass is written instead. The QEXPECT_FAIL() has no influence on the secondQCOMPARE() statement in the example.

Example 2:

QEXPECT_FAIL("data27","Oh my, this is soooo broken", Abort);QCOMPARE(i,42);

The above testfunction will not continue executing for the test data entrydata27.

See alsoQTest::TestFailMode,QVERIFY(), andQCOMPARE().

QFAIL( message)

This macro can be used to force a test failure. The test stops executing and the failuremessage is appended to the test log.

Note: This macro can only be used in a test function that is invoked by the test framework.

Example:

if (sizeof(int)!=4)    QFAIL("This test has not been ported to this platform yet.");

QFETCH( type, name)

The fetch macro creates a local variable namedname with the typetype on the stack.name has to match the element name from the test's data. If no such element exists, the test will assert.

Assuming a test has the following data:

void TestQString::toInt_data(){QTest::addColumn<QString>("aString");QTest::addColumn<int>("expected");QTest::newRow("positive value")<<"42"<<42;QTest::newRow("negative value")<<"-42"<<-42;QTest::newRow("zero")<<"0"<<0;}

The test data has two elements, aQString calledaString and an integer calledexpected. To fetch these values in the actual test:

void TestQString::toInt(){     QFETCH(QString, aString);     QFETCH(int, expected);     QCOMPARE(aString.toInt(), expected);}

aString andexpected are variables on the stack that are initialized with the current test data.

Note: This macro can only be used in a test function that is invoked by the test framework. The test function must have a _data function.

QSKIP( description, mode)

The QSKIP() macro stops execution of the test without adding a failure to the test log. You can use it to skip tests that wouldn't make sense in the current configuration. The textdescription is appended to the test log and should contain an explanation why the test couldn't be executed.mode is aQTest::SkipMode and describes whether to proceed with the rest of the test data or not.

Note: This macro can only be used in a test function that is invoked by the test framework.

Example:

if (!QSqlDatabase::drivers().contains("SQLITE"))    QSKIP("This test requires the SQLITE database driver", SkipAll);

See alsoQTest::SkipMode.

QTEST( actual, testElement)

QTEST() is a convenience macro forQCOMPARE() that compares the valueactual with the elementtestElement from the test's data. If there is no such element, the test asserts.

Apart from that, QTEST() behaves exactly asQCOMPARE().

Instead of writing:

QFETCH(QString, myString);QCOMPARE(QString("hello").toUpper(), myString);

you can write:

QTEST(QString("hello").toUpper(),"myString");

See alsoQCOMPARE().

QTEST_APPLESS_MAIN( TestClass)

Implements a main() function that executes all tests inTestClass.

Behaves likeQTEST_MAIN(), but doesn't instantiate aQApplication object. Use this macro for really simple stand-alone non-GUI tests.

See alsoQTEST_MAIN().

QTEST_MAIN( TestClass)

Implements a main() function that instantiates an application object and theTestClass, and executes all tests in the order they were defined. Use this macro to build stand-alone executables.

IfQT_GUI_LIB is defined, the application object will be aQApplication, otherwise it will be aQCoreApplication. If qmake is used and the configuration includesQT += gui, thenQT_GUI_LIB will be defined automatically.

Note: On platforms that have keypad navigation enabled by default (eg: Symbian), this macro will forcfully disable it to simplify the usage of key events when writing autotests. If you wish to write a test case that uses keypad navigation, you should enable it either in theinitTestCase() orinit() functions of your test case.

Example:

class TestQString:publicQObject {... };QTEST_MAIN(TestQString)

See alsoQTEST_APPLESS_MAIN(),QTest::qExec(), andQApplication::setNavigationMode().

QTEST_NOOP_MAIN()

Implements a main() function with a test class that does absolutely nothing. Use this macro to create a test that produces valid test output but just doesn't execute any test, for example in conditional compilations:

#ifdef Q_WS_X11    QTEST_MAIN(MyX11Test)#else// do nothing on non-X11 platforms    QTEST_NOOP_MAIN#endif

See alsoQTEST_MAIN().

QVERIFY2( condition, message)

The QVERIFY2() macro behaves exactly likeQVERIFY(), except that it outputs a verbosemessage whencondition is false. Themessage is a plain C string.

Example:

QVERIFY2(1+1==2,"A breach in basic arithmetic occurred.");

See alsoQVERIFY() andQCOMPARE().

QVERIFY( condition)

The QVERIFY() macro checks whether thecondition is true or not. If it is true, execution continues. If not, a failure is recorded in the test log and the test won't be executed further.

Note: This macro can only be used in a test function that is invoked by the test framework.

Example:

QVERIFY(1+1==2);

See alsoQCOMPARE().

QWARN( message)

Appendsmessage as a warning to the test log. This macro can be used anywhere in your tests.

Note: This function isthread-safe.