Our sample project is an existing application that uses Spring as IOC container, we would like to expose service method to third-party applications. We have the interface and its implementation already.

public interface FileSystemService {
    SimpleFile getFileByPath(String filePath);
    ...
}

Enable Restful service

The request /filesystem/getFile/<path of file> will return the file information if it is existed. To make it happen, we add java REST annotation to our service:

@Path("/filesystem")
public interface FileSystemService {
    @GET
    @Path("/getFile/{filePath:.*}")
    @Produces("application/xml")
    SimpleFile getFileByPath(@PathParam("filePath") String filePath);
    ...
}

Because the path of file may contains the '/' character, '/' is also the special characters of Http request, thus in line 4 we must use regular expression * to tell RESTeasy that all requests starts with /getFille is mapped to method getFileByPath (for example: /getFile/content/A or /getFile/content/A/B/C is valid path). @Produces("application/xml") annotation tells RESTeasy that the output must be in XML form.

Content marshalling/unmarshalling

Class SimpleFile is the complex type, to force RESTeasy produces XML data to client you must instruct RESTeasy how to marshal SimpleFile class.

@XmlRootElement(namespace="http://www.esofthead.com/engroup")
public class SimpleFile extends Content {
    private long size;
        ...
}

Installation

It is easy to install RESTeasy in java application, read the Installation section of RESTeasy documentation. Read more Spring integration section if you want to integrate RESTeasy with Spring. And we finish enable RESTful support in our Java application! Like its name, it is easy to deploy Restful solution by using RESTeasy.

Unit test

After all above tasks, it is time to look unit test solution. RESTeasy provides two approaches to write unit test:

• Embedded Container:RESTeasy packages TJWS embeddable servlet container with JAX-RS. You can start the embedded server in your unit test and use Apache HttpClient to test your code. See the sample in attachment files for detail.
• Server side - Mock framework:If you are not comfortable with starting the embedded server and would like a simpler solution, RESTeasy Mock framework would be a good option.

  Create Dispatcher mock object and integrate RESTeasy with Spring

  dispatcher = MockDispatcherFactory.createDispatcher();
  SpringBeanProcessor processor = new SpringBeanProcessor(dispatcher,
                  null, null);
  factory = new ClassPathXmlApplicationContext("ecm-context-test.xml");
  factory.addBeanFactoryPostProcessor(processor);
   
  SpringResourceFactory noDefaults = new SpringResourceFactory(
                  "fileSystemService", factory, FileSystemService.class);
  dispatcher.getRegistry().addResourceFactory(noDefaults);

  Send the request and test expected output

  MockHttpRequest request = MockHttpRequest
                  .get("/filesystem/getFile/content/A");
  MockHttpResponse response = new MockHttpResponse();
  dispatcher.invoke(request, response);
   
  Assert.assertEquals(HttpServletResponse.SC_OK, response.getStatus());
  String responseBodyAsString = response.getContentAsString();
   
  JAXBContext jaxbContext = JAXBContext.newInstance(SimpleFile.class);
  Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
  SimpleFile resultFile = (SimpleFile) unmarshaller
                  .unmarshal(new StringReader(responseBodyAsString));
   
  Assert.assertEquals(ContentConstants.FILE_ROOT_PATH + "/A", resultFile
                  .getPath());

  The result of request method is a XML string, the result of marshaling SimpleFile object to XML. To avoid testing base on XML data, we use JAXB to unmarshal XML data to SimpleFile object and validate data on this POJO.

I include two samples unit test for two approaches FileSystemRestTest-EmbeddedServer.java and FileSystemRestTest-MockFramework.java.This unit test sample is gotten from our engroup ECM module (you can get the Engroup product at http://esofthead.com/node/25), the unit test can not run because it lacks some classes of Engroup ECM module (this module is released in upcoming Engroup 1.5 version) but it provides the detail how to write unit test with RESTeasy.

• Some questions and answers of unit test (http://blog.esofthead.com/?p=51)
• Enhance the unit test using Annotation approach (http://blog.esofthead.com/?p=67)
• Unitils - enhance unit test using Annotation approach (http://blog.esofthead.com/?p=77) - Unit test spring bean and database testing with unitils library.
• Unit test with Spring Dynamic Modules (http://blog.esofthead.com/?p=106) - Unit & Integration test for Spring DM.
• Integration Jackrabbit OCM and Spring (http://blog.esofthead.com/?p=174) - Unit test against content repository.

Introduction
There are some techniques to write testing application services interact with database. There are:

Using Mock Object

Mock object are simulated objects that mimic the behavior of real objects in controlled ways. Using the mock object could be increase the performance of unit test, reduce the cost of maintenance also reduce the complexity of setting the test objects. In java world, easymock (http://easymock.org/) is the good mock library to help developers write mock easily.

Using Development Database

Testing runs against the development database. It has separated testing database per each workspace. It takes more time in setting testing environment, more time to execution, but it is useful in case we need to write the testing for database test script (not focus on business on service layer).
Database testing with DbUnit

DbUnit (http://www.dbunit.org/) is a JUnit extension targeted at database-driven projects that, among other things, puts your database into a known state between test runs. You should use dbUnit to write unit/integration testing on service layer. However, dbUnit could not be use in:

• Performance testing: development performance could say nothing about the performance of database.
• Stress/Volume testing: you could not write millions of database records using xml format.

With the completed database schema which has many foreign keys, it may takes you much time to maintain the known state of database, so one practice is omitting all foreign keys in testing database. It will reduce much time of maintaining database test script.

Integrate DbUnit and Spring Testing

Spring provides the excellent testing framework since 2.5 supports java annotation (http://static.springframework.org/spring/docs/2.5.x/reference/testing.html). To configure the Test Context, Spring use the test runner is SpringJUnit4ClassRunner. So in order to integrate DbUnit with Spring Testing framework, we extended this runner by our own class EngroupClassRunner and our testing has format:

@RunWith(EngroupClassRunner.class)
@ContextConfiguration(locations = { "/spring-service-test.xml" })
public class ExtendedTest{
    ...
    @DataSet
    @Test
    public void testSave() {
        ...
    }
}

With EngroupClassRunner, it would use the database script locates in the same location in testing class (for example: the database script would be located at com/engroup/module/hr/service/EducationTest.xml if the test class has the full name com.engroup.module.hr.service.EducationTest).

Override the database source to database testing configuration

Replace the spring configuration file by another spring configuration file in testing. For example: replace the code

<osgi:reference id="dataSource" interface="javax.sql.DataSource" />
<bean id="hrSqlMapClient"
    class="org.springframework.orm.ibatis.SqlMapClientFactoryBean">
    <property name="configLocation"
        value="classpath:hr-sqlmap-config.xml" />
    <property name="dataSource" ref="dataSource" />
</bean>

By

<bean id="dataSource"
  class="com.engroup.test.DataSourceFactoryBean" />

<bean id="commonSqlMapClient"
        class="org.springframework.orm.ibatis.SqlMapClientFactoryBean">
    <property name="configLocation"
        value="classpath:common-sqlmap-config.xml" />
    <property name="dataSource" ref="dataSource" />
</bean>

with com.engroup.test.DataSourceFactoryBean is the factory bean creates the data source from testing configuration and points to testing database.

and you write the database script in xml format as usual dbUnit format:

<!DOCTYPE dataset SYSTEM "../../../../../../engroup.dtd" >
<dataset>
    <m_hr_education id="1" course="Java" durationinmonth="10" institute="USA"/>
    <m_hr_education id="2" course="C#" durationinmonth="5" institute="VN"/>
</dataset>

Finally, you run the test to see whether your service is ok.

I include the some core classes of Engroup testing, not the whole package could be testable (because if I do so, you must have the testing database at your side). Here is the attachment.

Basic Jackrabbit OCM and Spring configuration

<bean id="repository"
  class="org.springmodules.jcr.jackrabbit.RepositoryFactoryBean">
    <property name="configuration"
      value="classpath:jackrabbit-repo-test.xml" />
    <property name="homeDir" value="." />
 </bean>

 <bean id="jcrSessionFactory"
  class="org.springmodules.jcr.jackrabbit.ocm.JackrabbitSessionFactory">
     <property name="repository" ref="repository" />
     <property name="credentials">
         <bean class="javax.jcr.SimpleCredentials">
             <constructor-arg index="0" value="superuser" />
             <!-- create the credentials using a bean factory -->
             <constructor-arg index="1">
                 <bean factory-bean="password" factory-method="toCharArray" />
             </constructor-arg>
         </bean>
     </property>
     <property name="skipExistingNamespaces" value="true"/>
     <property name="namespaces">
         <props>
             <prop key="engroup">http://esofthead.com/engroup</prop>
         </props>
     </property>
     <property name="nodeTypes2Import" value="custom_nodetypes_test.xml" />
 </bean>
 <!-- create the password to return it as a char[] -->
 <bean id="password" class="java.lang.String">
     <constructor-arg index="0" value="superuser" />
 </bean>
 <bean id="jcrMappingTemplate"
  class="org.springmodules.jcr.jackrabbit.ocm.JcrMappingTemplate">
     <constructor-arg index="0" ref="jcrSessionFactory" />
     <constructor-arg index="1" ref="jcrMappingDescriptor" />
 </bean>

Declaring annotation classes

<bean id="jcrMappingDescriptor"
  class="org.apache.jackrabbit.ocm.mapper.impl.annotation.AnnotationMapperImpl">
    <constructor-arg index="0">
        <list>
            <value>com.engroup.module.ecm.domain.Content</value>
            <value>com.engroup.module.ecm.domain.File</value>
            <value>com.engroup.module.ecm.domain.Folder</value>
            <value>com.engroup.module.ecm.domain.Resource</value>
        </list>
     </constructor-arg>
 </bean>

Transaction support

 <bean id="jcrTransactionManager"
  class="org.springmodules.jcr.jackrabbit.LocalTransactionManager">
     <property name="sessionFactory" ref="jcrSessionFactory" />
 </bean>
 <bean id="baseTransactionProxy"
  class="org.springframework.transaction.interceptor.TransactionProxyFactoryBean"
  abstract="true">
     <property name="transactionManager">
         <ref bean="jcrTransactionManager" />
     </property>
     <property name="transactionAttributes">
         <props>
             <prop key="save*">PROPAGATION_REQUIRED</prop>
             <prop key="*">PROPAGATION_REQUIRED,readonly</prop>
         </props>
     </property>
 </bean>

 <bean id="internalFileSystemService"
  class="com.engroup.module.ecm.service.impl.FileSystemServiceImpl">
     <property name="jcrTemplate" ref="jcrMappingTemplate" />
 </bean>

 <bean id="fileSystemService" parent="baseTransactionProxy">
     <qualifier value="proxy" />
     <property name="proxyInterfaces">
         <value>
             com.engroup.module.ecm.service.FileSystemService
         </value>
      </property>
      <property name="target">
          <ref bean="internalFileSystemService" />
      </property>
      <property name="transactionAttributes">
          <props>
              <prop key="*">PROPAGATION_REQUIRED</prop>
          </props>
      </property>
 </bean>

Custom JCR node types

Depends on your context, you could want to write custom JCR node types such as add description field into File class. Fairly easy to do so by declaring custom node types in custom_nodetypes_test.xml file:

<!--It is a must node type for OCM support-->
<nodeType name="ocm:discriminator" isMixin="true">
    <supertypes>
        <supertype>nt:base</supertype>
    </supertypes>
    <propertyDefinition name="ocm_classname" requiredType="String"
        autoCreated="false" mandatory="true" onParentVersion="COPY"
        protected="false" multiple="false" />
 </nodeType> 

 <nodeType name="engroup:hierarchyNode" isMixin="false"
  hasOrderableChildNodes="false" primaryItemName="">
     <supertypes>
         <supertype>nt:hierarchyNode</supertype>
     </supertypes>
     <propertyDefinition name="jcr:description" requiredType="String"
         autoCreated="false" mandatory="false" onParentVersion="COPY"
         protected="false" multiple="false" />
     <propertyDefinition name="jcr:owner" requiredType="String"
         autoCreated="false" mandatory="false" onParentVersion="COPY"
         protected="false" multiple="false" />
 </nodeType>

Writing unit test

Unit test is our standard and it is time to write some test cases to test Engroup ECM API. We will use the Spring
Test Framework to test our spring bean. One more concern is choosing appropriate Jackrabbit Persistent Manager for
testing. Jackrabbit supports various Persistent Manager such as File System, Database, InMemory. In our product, we
use Database Persistent Manager, but for testing purpose the InMemory Persistent Manager is the good choice for fast
and cleaning data after running test. You could configure it in Jackrabbit configuration file

<FileSystem class="org.apache.jackrabbit.core.fs.mem.MemoryFileSystem"/>
...Workspace section
    <PersistenceManager class="org.apache.jackrabbit.core.persistence.mem.InMemPersistenceManager">
        <param name="persistent" value="false"/>
    </PersistenceManager>
...Version section
    <PersistenceManager class="org.apache.jackrabbit.core.persistence.mem.InMemPersistenceManager">
        <param name="persistent" value="false"/>
    </PersistenceManager>

Write FileSystemService unit test:

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = { "/ecm-context-test.xml" })
public class FileSystemServiceTest {
    @Autowired
    @Qualifier("proxy")
    protected FileSystemService fileSystemService;
...
}

And add some test method:

@Test
public void testUpdateFileWithVersion() {
    Resource resource = new Resource();
    resource.setData(new ByteArrayInputStream("this is the content"
            .getBytes()));
    resource.setLastModified(Calendar.getInstance());
    resource.setMimeType("plain/text");
    File file = new File();
    file.setPath("/A");
    file.setResource(resource);
    fileSystemService.save(file);

    Resource resource2 = new Resource();
    resource2.setData(new ByteArrayInputStream("this is the content 2"
            .getBytes()));
    resource2.setLastModified(Calendar.getInstance());
    resource2.setMimeType("plain/x");
    file.setResource(resource2);
    fileSystemService.update(file);
    Collection<Version> versions = fileSystemService
            .getVersionHistory(ContentConstants.FILE_ROOT_PATH + "/A");
    Assert.assertEquals(2, versions.size());
    File latestFileVersion = fileSystemService.getFileByVersion(
            ContentConstants.FILE_ROOT_PATH + "/A", "1.0");
    Assert.assertEquals("plain/x", latestFileVersion.getResource()
            .getMimeType());
    fileSystemService.remove(file);
}

You could download the example, see more details how to integrate Jackrabbit OCM and Spring, run the test and provide your feedbacks if any.

Source code

Scenario: I would like to test login function of some application use Ldap server as user information database. The unit test will launch the embedded LdapServer in each test method as the excellent guideline describe here http://directory.apache.org/apacheds/1.5/using-apacheds-for-unit-tests.html. Typically, I would like each test class launch embedded ldap server use the annotation EmbeddingServer:

@RunWith
(UnitilsJUnit4TestClassRunner.class)
@EmbeddingLdapServer
public classRoleLdapServiceTest {
@Test
public voidtestFindRole() {
Assert.assertNotNull(roleLdapService.findRoleName("ROLE_ADMINISTRATOR"));
Assert.assertNull(roleLdapService.findRoleName ("ROLE_TEST"));
...
}
...
}

To add the new module to Unitils is very simple:

1. Add the new module name in unitils.properties (you can see how to use unitils.properties to configure modules at http://unitils.sourceforge.net/tutorial.html#Unitils%20Modules):
   unitils.modules=database,dbunit,hibernate,easymock,inject,spring, ldap (Note that database, dbunit, hibernate, easymock,inject and spring are the built-in modules of Unitils, and I add ldap module for my ldap unit testing).
2. Add the related information for initializing our module in the same unitils.properties file
   unitils.module.ldap.className=org.nextss.util.test.ldap.LdapModule
   unitils.module.ldap.enabled=true
   ldap.username=uid=admin,ou=system
   ldap.password=secret
   ldap.authentication.method=simple
   ldap.factory.classname=org.apache.directory.server.jndi.ServerContextFactory
3. Create the annotation class that new module supports

   @Target(ElementType.TYPE)
   @Retention(RetentionPolicy.RUNTIME)
   public @interfaceEmbeddingLdapServer {
   }

   EmbeddingLdapServer is annotated to class and it is retained in runtime as we define in requirement

4. Create Module class corresponds the new module. This class must inherit the interface org.unitils.core.Module and override two methods void init(Properties configuration) and TestListener createTestListener(). The usage of these two classes are:
   - init is used to load any pre-defined configuration of defined module (in unitils.properties file)
   - createTestListener creates the TestListener for test events with the following orders:

5. • [Unitils] beforeAll
   • [Unitils] beforeTestClass - TestClass1
   • [Test] testBeforeClass - TestClass1 (not for JUnit3)
   • [Unitils] beforeTestSetUp - TestClass1
   • [Test] testSetUp - TestClass1
   • [Unitils] beforeTestMethod - TestClass1 - test1
   • [Test] testMethod - TestClass1 - test1
   • [Unitils] afterTestMethod - TestClass1 - test1
   • [Test] testTearDown - TestClass1
   • [Unitils] afterTestTearDown - TestClass1
   • [Unitils] beforeTestSetUp - TestClass1
   • [Test] testSetUp - TestClass1
   • [Unitils] beforeTestMethod - TestClass1 - test2
   • [Test] testMethod - TestClass1 - test2
   • [Unitils] afterTestMethod - TestClass1 - test2
   • [Test] testTearDown - TestClass1
   • [Unitils] afterTestTearDown - TestClass1
   • [Test] testAfterClass - TestClass1 (not for JUnit3)
   • [Unitils] afterTestClass - TestClass1
   • [Unitils] afterAll

In our case, we write the new module names LdapListener. Because, we want unitils read the annotation EmbeddingLdapServer at the beginning of running test class, we will override the method beforeTestClass:

@Override
public void beforeTestClass(Class<?> testClass) {
EmbeddingLdapServerclassAnnotation = getClassLevelAnnotation(EmbeddingLdapServer.class, testClass);
if(classAnnotation != null) {
log.debug("before test class");
serverOnline= false;
doDelete= true;
configuration= newLdapServerConfigDecorator();
port= -1;
}
super.beforeTestClass(testClass);
}

Next, we setup the partition'nextss' for ldapServer in method beforeTestSetUp after ldap server is started:
@Override
public void beforeTestSetUp(Object testObject) {
EmbeddingLdapServerclassAnnotation = getClassLevelAnnotation(EmbeddingLdapServer.class, testObject.getClass());
if(classAnnotation != null) {
// Add partition 'nextss'
MutablePartitionConfiguration pcfg = newMutablePartitionConfiguration();
pcfg.setId("nextss");
try{
pcfg.setSuffix("dc=nextss");
} catch(NamingException e) {
throw new RuntimeException(e);
}
....
}

After creating the partition, we import the data by using ldif file:
@Override
public void beforeTestMethod(Object testObject, Method testMethod) {
Class<?> testClass = testObject.getClass();
EmbeddingLdapServerclassAnnotation = getClassLevelAnnotation(EmbeddingLdapServer.class, testClass);
if(classAnnotation != null) {
try{
setUp();
} catch(Exception e) {
throw new RuntimeException(e);
}
InputStream ldifStream = testClass.getResourceAsStream(testClass.getSimpleName()+ ".ldif");
if(ldifStream == null) {
throw new NextssException("File: "+ testClass.getSimpleName() + ".ldif is not found");
}
try{
importLdif(ldifStream);
} catch(NamingException e) {
throw new NextssException(e);
}
}
super.beforeTestMethod(testObject, testMethod);
}

And the last, not miss to clean up data after each test method :
@Override
public void afterTestMethod(Object testObject, Method testMethod,Throwable testThrowable) {
EmbeddingLdapServerclassAnnotation = getClassLevelAnnotation(EmbeddingLdapServer.class, testObject.getClass());
if(classAnnotation != null) {
try{
tearDown();
} catch(Exception e) {
throw new RuntimeException();
}
}
super.afterTestMethod(testObject, testMethod, testThrowable);
}

It is very simple, right? . You can start writing test with Embedded Ldap Server will run and import data before each test method.
UserLdapServiceTest.javaLdapModule.javaLdapServerConfigDecorator.javaEmbeddingLdapServer.java

• DRY principle (Don't repeat yourself)
• Re-use test set up across test cases: put non-trivial test data in test set up method
• Clean test code as productive code

2. Evident data

3. All non-trivial methods must be passed unit test with 100% coverage ratio.

4. Unit test independent with:

• Other unit tests, order of unit test running
• Environment (operating system, hardware configuration, database …)

5. Fix broken test as soon as possible (it should be immediately)

6. After fixing defect, write unit test to prevent it re-occurs

7. All test cases must be passed at the end of working day

8. Test project code, not library code

9. Minimal maintenance of test code

10. If you can not write unit test for some functionality that means your code has problem! Refactor it immediately