Amarok/Development/UnitTesting

From KDE Community Wiki

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