An OpenFuture project

Log4Unit is a JUnit extension combining JUnit with Log4J. The intention is to create test protocols for JUnit.

JUnit is asymmetrical in the sense that it focusses on the documentation of test failures and errors. Successful execution of a test case is not further documented. In order to obtain a test protocol that documents the initial settings, the test case execution and its results, a logging component is required. Log4J as the current de facto standard is selected for this extension.

The current version is 0.2.0 is available for download as log4unit-0.2.0.tar.gz and log4unit-0.2.0.zip.

It is provided under GNU Lesser General Public License.

Extensions of JUnit

• LoggedTestCase --> TestCase
  The class junit.framework.TestCase does not contain any methods for logging. Hence, the subclass junit.log4j.LoggedTestCase is introduced providing methods for logging:
  • debug() --> org.apache.log4j.Category.debug()
  • info() --> org.apache.log4j.Category.info()
  • warn() --> org.apache.log4j.Category.warn()
  • fatal() --> org.apache.log4j.Category.fatal()

  In order to configure the logging, place a log4j.properties file in your classpath. If Log4J is not present, the console is used for logging.

  Hint: Please be aware, that assertions are not logged via Log4J, since LoggedTestCase does *not* override the assert... methods of TestCase.

• TestRunner
  junit.swingui.TestRunner is extended by junit.logswingui.TestRunner providing the ability to view and save test protocols. In order to write logging results to this protocol, configure junit.log4j.JUnitAppender as Log4J appender in your Log4J configuration. Here an example configuration:

  -------------------------------------------------------------------------------------
  # junit is set to be a junit.logswingui.LoggedTestResult
  log4j.appender.junit=junit.log4j.JUnitAppender
  
  # junit uses PatternLayout.
  log4j.appender.junit.layout=junit.log4j.JUnitLayout
  log4j.appender.junit.layout.ConversionPattern=%d{dd MMM yyyy HH:mm:ss,SSS} - %m %T%n
  -------------------------------------------------------------------------------------
    

• JUnitAppender
  A new Log4J appender is introduced to provide the coupling to the JUnit test runner. Since appenders are instantiated by the configurator of Log4J we need a singleton to populate the logging events to the test runner (JUnitAppenderSingleton).

Usage

• Derive your test cases from junit.log4j.LoggedTestCase
• Place logging messages in your test case using the info(), debug(), ... methods.
• Place the file log4j.properties somewhere in the class path. This file contains the Log4J configuration.
• Add the log4j JAR to your classpath
• Use junit.logswingui.TestRunner as new test runner, if you want to have access to the test protocol:
  java junit.logswingui.TestRunner [-noloading] [TestCase]

Frequently Asked Questions

• [Q]: I tried to use it but all I get in my logfile is DEBUG - Log4J successfully instantiated.
  [A]: The regular assert...() methods are not extended, i.e. messages generated by assert...() methods are NOT written to the log files. Use debug(), info(), warn() or fatal() instead.
• [Q]: Do I have to use the Log4Unit TestRunner?
  [A]: No, you can use any JUnit TestRunner, if you could live without the "Protocol" button of junit.logswingui.TestRunner.
• [Q]: May I run my test cases without Log4J?
  [A]: Yes. If Log4J is not in the classpath, all log messages will automatically be written to stdout.

Requirements

• JUnit version 3.8.1: http://www.junit.org
• Log4J version 1.2.8: http://jakarta.apache.org/log4j

Older versions

Version 0.1.2: log4unit-0.1.2.tar.gz, log4unit-0.1.2.zip.