:mod:`junit` -- Annotations for JUnit 4.X
=========================================

.. module:: lib.junit
   :synopsis: Defines Jython annotations and test runners for of use of JUnit 4.
.. moduleauthor:: Kay Schluehr <kay@fiber-space.de>

JUnit 4 Annotations
-------------------

The following Python decorators produce Java annotations and correct signatures.
For example the Java annotation ``Before`` corresponds to the ``Before`` decorator in Jython which is defined as ::

    Before = annotation.extract(Before)(signature("public void _()")

Annotations on static method like ``BeforeClass`` are defined as

    BeforeClass = annotation.extract(BeforeClass)(signature("public static void _()")

Following annotations are supported

* **Before**
* **After**
* **Test**
* **BeforeClass**
* **AfterClass**
* **Ignore**

The ``Ignore`` decorator is defined as

| ``Ignore = annotation.extract(Ignore)``

An appropriate signature has still to be added.

Testrunner
----------

A simple test runner called ``testClasses`` was implemented. It uses traceback extraction to analyze Python
exceptions and writes failure messages to stdout.

.. function:: testClasses(*testclass)

    :param testclass: a sequence of Jython classes. All of them have to be decorated by ``jannotations.JavaClass``.
                      At least one method decorated with ``@test`` must be implemented.
                      Otherwise test initialization fails and a ``ValueError`` exception is raised.

**Example:**

.. sourcecode:: jython

    from jynx.lib.junit import*
    from java.lang import Object
    from jynx.jannotations import JavaClass

    @JavaClass
    class TestClass(Object):

        @BeforeClass
        def once(cls):
            print "\nRun 'TestClass' tests ..."

        @Test
        def nullTest1(self):
            assertTrue("length of empty list is not 0", len([]) != 0)


Running the ``TestClass`` with the ``testClasses`` runner ::

    testClasses(TestClass)

yields following result ::

    Run 'TestClass' tests ...

    There was 1 failure:

       1) nullTest1(TestClassBase)

          java.lang.AssertionError: length of empty list is not 0
          ...
          assertTrue("length of empty list is not 0", len([]) != 0)
          ...
          at C:\lang\Jython\jython2.5rc4\Lib\site-packages\jynx\tests\test_jannotations.py : 48