User Documentation

One Minute Introduction

Two Minute Introduction

Your own plugin

Coffee Break Introduction

Property substitution

FAQ

IDE Integration

Doclipse

Maven Integration

Maven2 Plugin

Maven1 Plugin

Plugins

• Actionscript plugin
• Beaninfo plugin
• Castor plugin
• Ejb plugin
• Externalizer plugin
• Hibernate plugin
• Interfaceextractor plugin
• Jdo plugin
• Jmx plugin
• Junit plugin
• Plugin plugin
• Portlet plugin
• Qtags plugin
• Spring plugin
• Struts plugin
• Tapestry plugin
• Web plugin
• Webwork plugin
• Xtags plugin
• Xwork plugin

Project Information

Mailing lists

Source Repositories

Open Issues

Team

Developer Documentation

Feeds

• Site
• News

Unit Testing the Plugin

Another area where XDoclet2 vastly improves over its predecessor is in the area of unit testing. In order to facilitate TDD of the plugins, Generama provides an abstract base test class - org.generama.AbstractPluginTestCase that all test cases need to extend. This is the very well known AbstractTestCase Unit testing pattern.

Concrete plugin test cases are required to provide implementation for the following abstract methods declared on the AbstractPluginTestCase -

protected abstract Plugin createPlugin (MetadataProvider metadataProvider,WriterMapper writerMapper) throws Exception;
protected abstract MetadataProvider createMetadataProvider () throws Exception;
protected abstract URL getExpected () throws Exception;
protected abstract void compare (URL expected, URL actual) throws Exception;

We saw earlier that Picocontainer injects the dependencies specified by the Plugin constructor. When running the tests within JUnit, we don't have access to Pico and its services. So the JUnit test case has to explicitly resolve those dependencies (generama's AbstractTestCase explicity injects the dependencies). This explains the existance of the first 2 factory methods. Also the AbstractTestCase employs the factory method to access the concrete Plugin class that it is testing.

Exercising behaviour on an object results in a side-effect and unit testing is about making sure that this is indeed the expected effect/behaviour. The abstract base test class accordingly leaves the implementation of the next 2 methods to the concrete classes.

Some of the common code generation activities in a j2ee project typically involve generating java source files (EJB remote/home interfaces from the bean definition), XML descriptor files (ejb-jar.xml generation from bean definition) and in some cases properties files too. Generama tries to make testing the corresponding plugins easier by providing default implementation for the abstract compare() method specified by AbstractPluginTestCase class -

• org.xdoclet.AbstractJavaGeneratingPluginTestCase
  
  Determines if the generated and the expected java source file are synactically the same.

• org.generama.tests.AbstractTextGeneratingPluginTestCase
  
  Does a line by line comparison of the 'expected' and 'actual' text files and hence sensitive to whitespaces.

• org.generama.tests.AbstractXMLGeneratingPluginTestCase
  
  Employs xmlunit to do the actual comparison

• org.generama.tests.AbstractPropertyGeneratingPluginTestCase
  
  Provides implementation for the abstract compare method by creating java.util.Properties objects out of the 'expected' and 'actual'
  
  parameters passed to it and relies on the 'equals' method implementation to do the actual comparison. Note that two java.util.Property
  
  instances are considered identical if their entry sets match.

import org.generama.tests.AbstractXMLGeneratingPluginTestCase;

public class CommandPluginTestCase extends AbstractXMLGeneratingPluginTestCase {

	
    /**
    * The Command and its implementation classes are under     
    * "D:/lab/XDoclet2/src/main/java" folder on my filesystem. QDox needs to know the    
    * location of the annotated source files.
    */

    protected MetadataProvider createMetadataProvider() throws IOException {

      URL reader = new File("D:/lab/XDoclet2/src/main/java").toURL();
      return new QDoxMetadataProvider(new File(reader.getPath()));
    }

    protected Plugin createPlugin(MetadataProvider metadataProvider, WriterMapper writerMapper) throws Exception {

      return new CommandPlugin (new JellyTemplateEngine(),(QDoxMetadataProvider)metadataProvider, writerMapper);
    }

    protected URL getExpected() throws IOException {
      return getResourceRelativeToThisPackage("/expected/command-mapping.xml");
    }

}

Allright so far so good. But where is the test method that JUnit needs at the minimal to do something? - As with AbstractTestCase design pattern, the org.generama.tests.AbstractPluginTestCase does it for us through 'testGenerateContent' method.

Its quite clear that it does what pico would have done when running the plugin from within the build file except that it does an assert on the 'expected' and 'actual' results obviously.

public void testGenerateContent() throws Throwable {
        try {
            plugin.start();
            Outcome out = writerMapper.getOutcome(null, null);
            compare(getExpected(), out.getURL());
        } catch (Throwable e) {
            //ommited for clarity
            throw e;
        }
    }

By offering an abstract test framework, XDoclet2 developers have kept their promise. So its upto the plugin developers to provide a robust test suite that verifies the correctness and explains the usage of the corresponding plugin.