ThePersistenceTester

The persistence tester is a utility for testing your ORM configuration (such as NHibernate mappings) by testing whether an object can be saved to a database and then retrieved. This process includes comparing to verify that "what was loaded" is equal to "what was saved".

Most common configuration/mapping mistakes can be detected by this test process. The process is also suitable for automation. The intent of the CSF.PersistenceTester package is to provide that automation in a convenient manner.

Recommended usage

Using the persistence tester begins with the TestPersistence static class. The recommended way to use the persistence tester is as follows.

// 'provider' is an IGetsDataConnection
// 'entity' is the object for which you wish to test

var result = TestPersistence
  .UsingConnectionProvider(provider)
  .WithSetup(c => { /* Optional setup action */ })
  .WithEntity(entity)
  .WithEqualityRule(r => r.ForAllOtherProperties());

Begin with a connection provider

The first step is to get our create an instance of IGetsDataConnection for your chosen ORM. For NHibernate, you would use a SessionFactoryAdapter.

This data-connection-provider should be created in the same (or a very similar) way as it is created in production. Ideally it will provide a connection to a database which uses the same schema as production but is otherwise empty.

Create an instance of the entity to test

The persistence tester must save and then retrieve an object to/from the database (using the ORM). Create an instance of the object type with which to test and pass it to the WithEntity method.

The created entity should be valid to save to the database (obeying rules such as data-type maximum lengths etc).

Use the setup action to add required data

If saving the entity (above) would require other supporting data to exist in the database (for example rows in 'parent' tables) then use the WithSetup method to save them.

If no setup action is required or appropriate then the WithSetup method may be omitted.

Use equality rules to compare the retrieved object with the saved one

The WithEqualityRule method allows the developer to configure an instance of CSF.EqualityRules in order to compare the saved and retrieved copies of the entity.

Alternative: Use an equality comparer

Instead of an equality rule created with CSF.EqualityRules, you may use any implementation of IEqualityComparer<T> which is suitable for the saved/retrieved entity type.

Note that if using an equality comparer and not a rule, you will receive less detailed failure results if the retrieved entity is not equal to the saved one.

Write one such persistence test for each entity type

Each usage of the persistence tester determines whether one entity type may be saved/loaded successfully. Write one such test for each entity type in your application, in order to have full confidence that everything may be saved & loaded correctly.

If using NUnit 3.x, use the integration

An integration package is provided for NUnit version 3.x: CSF.PersistenceTester.NUnit this provides a test constraint class which allows convenient assertion that the test was successful, and clearly formats the failure result of it was not.

// 'result' is the result of the persistence test
Assert.That(result, Persisted.Successfully());