Amarok/Development/UnitTesting

This is a small tutorial for testers and developers.

Testers: how to run unit tests

Basically it's quite simple. You need a build compiled with -DCMAKE_BUILD_TYPE=debugfull. Those support the --test parameter to run all available unit tests:

amarok --test log

runs the tests and writes the result to log files

 amarok --test stdout

runs the tests and shows results on stdout.

I really recommend doing that on a testing profile only.

The logging location is your Amarok profile folder (in the subfolder testresults/), where for each run a new folder is being created. Inside you can see logs for each test class. In a perfect world no test should fail.

Developers: How to write unit tests

Adding a test

1. Create a new test class TestYourClassName in the tests/ subdirectory of the Amarok sources. Try to keep the same directory structure as in src/.
   • inherit it from QObject, don't forget the Q_OBJECT macro
   • adjust the constructor to match the already available tests, don't forget to change the log file name
2. Create a CMakeLists.txt that feeds your .cpp file to QT4_AUTOMOC
3. adjust src/CMakeLists.txt
   • if needed add your test directory to the include_directories
   • add your .cpp file to amaroklib_LIB_SRCS in debug builds (just search for "test" to find the current locations in that file)
4. add the test to App.cpp: App::runUnitTests()
5. recompile, run it :)

The test itself

• QtTest documentation
• you are very likely going to need the QCOMPARE und QVERIFY macros
• one test function for each method to test (not always possible), call it testYourMethodName
• tests should not influence other tests
• initialization stuff can be done in initTestCase(), cleanup in cleanupTestCase()
• if your test does something asynchronously (eg in another thread) check TestDirectoryLoader as example

test data

• can be found in tests/data/, will be installed to KStandardDirs::installPath( "data" ) + QDir::toNativeSeparators( "amarok/testdata/" )

Possible errors

• no tests are being run -> you forgot the Q_OBJECT macro