Envers is a Hibernate module that can be configured to automatically audit changes made to your entities. Each audited entity are thus associated with a list of revisions, each revision capturing the state of the entity when a change occurs. There is however an obstacle I came across while I was "unit testing" my DAO, and that's what I want to share to avoid others to fall in the same pit. First, let's have an overview of the couple of steps needed to use Envers:

• Annotate your entity with the @Audited annotation:

  @Entity
  @Audited
  public class Person {
  
      // Properties
  }

• Register the Envers AuditEventListener in your Hibernate SessionFactory through Spring:
  

  <bean id="sessionFactory" class="org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean">
      <property name="dataSource" ref="dataSource" />
      <property name="packagesToScan" value="ch.frankel.blog.envers.entity" />
      <property name="hibernateProperties">
          <props>
              <prop key="hibernate.dialect">org.hibernate.dialect.H2Dialect</prop>
          </props>
      </property>
      <property name="schemaUpdate" value="true" />
      <property name="eventListeners">
          <map>
              <entry key="post-insert" value-ref="auditListener" />
              <entry key="post-update" value-ref="auditListener" />
              <entry key="post-delete" value-ref="auditListener" />
              <entry key="pre-collection-update" value-ref="auditListener" />
              <entry key="pre-collection-remove" value-ref="auditListener" />
              <entry key="post-collection-recreate" value-ref="auditListener" />
          </map>
      </property>
  </bean>
  
  <bean id="auditListener" class="org.hibernate.envers.event.AuditEventListener" />

• Configure the Hibernate transaction manager as your transaction manager. Note auditing won't be triggered if you use another transaction manager (DataSourceTransactionManager comes to mind):
  

  <bean id="transactionManager" class="org.springframework.orm.hibernate3.HibernateTransactionManager">
          <property name="sessionFactory" ref="sessionFactory" />
  </bean>
  

• Now is the time to create your test class:
  

  @ContextConfiguration("classpath:spring-persistence.xml")
  @TransactionConfiguration(defaultRollback = false)
  public class PersonDaoImplTest extends AbstractTransactionalTestNGSpringContextTests {
  
      @Autowired
      private PersonDao personDao;
  
      @BeforeMethod
      protected void setUp() {
  
          // Populate database
      }
  
      @Test
      public void personShouldBeAudited() {
  
          Person person = personDao.get(1L);
  
          person.setFirstName("Jane");
  
          List<Person> history = personDao.getPersonHistory(1L);
  
          assertNotNull(history);
          assertFalse(history.isEmpty());
          assertEquals(history.size(), 1);
      }
  }

Strangely, when you execute the previous test class, the test method fails when checking the list is not empty: it is, meaning there's no revision associated with the entity. Morevoer, nothing shows up in the log. However, the revision shows up in the audited table at the end of the test (provide you didn't clear the table after its execution). Comes the dreaded question: why? Well, it seems Hibernate post-event listeners are only called when the transaction is commited. In our case, it matches: the transaction is commited by Spring after method completion, and our test trie to assert inside the method. In order for our test to pass, we have to manually manage a transaction inside our method, to commit the update to the database.

@Test
public void personShouldBeAuditedWhenUpdatedWithManualTransaction() {

    PlatformTransactionManager txMgr = applicationContext.getBean(PlatformTransactionManager.class);

	// A new transaction is required, the wrapping transaction is for Envers
    TransactionStatus status = txMgr.getTransaction(new DefaultTransactionDefinition(PROPAGATION_REQUIRES_NEW));

    Person person = personDao.get(1L);

    person.setFirstName("Jane");

    txMgr.commit(status);

    List<Person> history = personDao.getPersonHistory(1L);

    assertNotNull(history);
    assertFalse(history.isEmpty());
    assertEquals(history.size(), 1);
}

On one hand, the test passes and the log shows the SQL commands accordingly. On the other hand, the cost is the additional boilerplate code needed to make it pass. Of course, one could (should?) question the need to test the feature in the first place. Since it's a functionality brought by a library, the reasoning behind could be that if you don't trust the library, don't use it at all. In my case, it was the first time I used Envers, so there's no denying I had to build the trust between me and the library. Yet, even with trusted libraries, I do test specific cases: for example, when using Hibernate, I create test classes to verify that complex queries get me the right results. As such, auditing qualifies as a complex use-case whose misbehaviors I want to be aware of as soon as possible. You'll find the sources for this article here, in Maven/Eclipse format.