“Test Runner” is a unit testing framework that fully supports testing qooxdoo classes. It is similar to but does not require JSUnit or any other JavaScript unit testing framework. If you look at the application section of a qooxdoo distribution under application/testrunner/, you will find the Test Runner tailored to test the functionality of qooxdoo framework classes. It provides a convenient interface to test classes that have been written to that end. You can run single tests, or run a whole suite of them at once.

But the Test Runner framework can also be deployed for your own application. It provides a GUI, a layer of infrastructure and a certain interface for arbitrary test classes. So now you can write your own test classes and take advantage of the Test Runner environment.

This section assumes that your qooxdoo application bears on the structure of the qooxdoo skeleton application. Then this is what you have to do:

• You have to code test classes that perform the indiviudal tests. These test classes have to comply to the following constraints:
  • They have to be within the name space of your application.
  • They have to be derived from testrunner.TestCase.
  • They have to define member functions with names starting with test*. These methods will be available as individual tests.
  • Apart from that you are free to add other member functions, properties etc., and to instantiate other classes to your own content. But you will usually want to instantiate classes of your current application and invoke their methods in the test functions.
  • In order to communicate the test results back to the Test Runner framework exceptions are used. No exception means the test went fine, throwing an exception from the test method signals a failure. Return values from the test methods are not evaluated.
  • To model your test method behaviour, you can use the methods inherited from testrunner.TestCase which encapsulate exceptions in the form of assertions:
    • assert, assertFalse, assertEquals, assertNumber, ... - These functions take values which are compared (either among each other or to some predefined value) and a message string, and raise an exception if the comparison fails.
    • A similar list of methods of the form assert*DebugOn is available, which are only evaluated if the debug variant qx.debug is on (see Variants).
    • See the documentation for the testrunner.TestCase class for more information on the available assertions (btw, the API reference is easily created by make api in the testrunner directory).

• Run make test from the directory of your application Makefile. This will generate the appropriate test application for you, which will be available in the subfolder test as test/index.html. Open this file in your browser and run your tests.
• Equally, you can invoke make test-source. This will generate the test application, but allows you to use the source version of your application to run the tests on. In doing so the test application links directly into the source tree of your application. This allows for test-driven development where you simultaneously develop your source classes, the test classes and run the tests. All you need to do is to change the URL of the “test backend application” (the textfield in the upper middle of the TestRunner frame) from tests.html (which is the default) to tests-source.html. (Caveat: If make test-source is the first thing you did, you might get an error when TestRunner starts, since the default tests.html has not been built; just change the URL and continue). For example, the resulting URL will look something like this:

  html/tests-source.html?testclass=<your_app_name> 

  After that, you just reload the backend application by hitting the reload button to the right to see and test your changes in the TestRunner.

The test classes of your application introduce dependencies to the “testrunner.*” name space. This might result in unresolved class dependencies when you make source (or its shorter equivalent make), since the build process for a source version by default and for convenience includes all classes it finds. Thus, your test classes get included as well, and with them the dependency to the testrunner classes. (You might see corresponding error messages during the build process run and when you load your app).

There are three options to amend for this, with the first option being the recommended way of handling this scenario. All options are easily set up adjusting the Makefile of your application:

• You either explicitly exclude the custom test classes form the source version (which is the recommended way), using

  APPLICATION_ADDITIONAL_SOURCE_OPTIONS = --exclude-without-dependencies=your.testclasses.*
  
  

  (provided that your testclasses are in the your.testclasses name space).

• Or you force the inclusion of the testrunner classes by using

  APPLICATION_ADDITIONAL_CLASS_PATH = $(QOOXDOO_PATH)/frontend/application/testrunner/source/class
  APPLICATION_ADDITIONAL_CLASS_URI = ../$(QOOXDOO_PATH)/frontend/application/testrunner/source/class
  
  

  (This still leaves some nasty error messages).

• Or you generally restrict your source version to only the required classes (not recommended either) by using

  APPLICATION_COMPLETE_SOURCE = false
  
  

  This restricts the included classes to only those that are actually used by your application, which automatically rules out the test classes. But be aware that you now have to do a make source (or make) whenever you use previously unused qooxdoo classes in your application code so they get included.