DbUnit.NET

Getting Started

1. Step 1: Create your dataset file
2. Step 2: Create your test class
3. Step 3: Implement your [Test] methods

Getting Started for release 0.0.4.0 (alpha4)

Your tests need some data to work with. DbUnit.NET handles this by inserting the data you provide within a "dataset". This "dataset" is an xml file that specifies the tables and columns, along with the latters values, that should be created within the database.

The xml file can be in one of two formats, "flat" or "structured".

A "flat" XML is an XML file in which each child element to the files main element (which can be anything but <dataset> is suggested) specifies a single insert statement to be be executed. The elements name is the table name and the elements attributes specify the column names and values to be used.

The following is a sample of a flat XML dataset that specifies 2 inserts into the 'people' table:

<?xml version="1.0" encoding="utf-8" ?>
<dataset>
	<people id="1" given_names="Jo-Ann" surname="Smith" gender="F"/>
	<people id="2" given_names="Mary Jane" surname="Jones" gender="F"/>
</dataset>
			

A "structured" XML is an XML file in which each child element to the files main element (which can be anything but <dataset> is suggested) specifies a single table into which data is to be inserted. The child elements of these elements specify a single row of data and their child elements specify the columns and thier value for the column.

An example is probably a better explanation of what is above, so here is the same 2 inserts given above for the "flat" xml but expressed in "structed" XML.

<?xml version="1.0" encoding="utf-8" ?>
<dataset>
	<people>
		<row>
			<id>1</id>
			<given_names>Jo-Ann</given_names>
			<surname>Smith</surname>
			<gender>F</gender>
		</row>
		<row>
			<id>2</id>
			<given_names>Mary Jane</given_names>
			<surname>Jones</surname>
			<gender>F</gender>
		</row>
	</people>
</dataset>
			

It doesn't matter what the tag, above named <row>, is actually called this is merely a container so multiple rows can be specified to be inserted into a single table.

This dataset should be placed in the same directory as the test class by which it will be used and should be named YourClassNameDataSet.xml. It must also be included in the generated assembly as an Embedded Resource such that it is embedded within the same namespace as the test class.

Create an NUnit [TestFixture] class that extends DbUnitTestCase and provides the following:

• A [TestFixtureSetUp] method that initializes the connection to the database, the PrimaryKeyFilter to use on tear down, and the IDatabaseHandler to use to insert/delete the actual data
• A [SetUp] method that calls super.SetUp() and initializes your own test accordingly
• A [TearDown] method that calls super.TearDown()
• A [TestFixtureTearDown] method that closes the database connection
• (Optional): Override the GetDataSet() method to provide an alternative to the default "flat" dataset

The PrimaryKeyFilter must be loaded with the details of all primary keys of all the tables specified in the dataset. In the example given the primary key is the "id" column (see the SetUpFixture() method in the code sample below).

To use a "structured" XML you must override the GetDataSet() method. The example below does this.

The following is an example:

using System;
using System.Data;
using System.Data.SQLite;
using DbUnit.Framework;
using NUnit.Framework;

namespace Samples.Tests
{
	[TestFixture]
	public class SampleTest : DbUnitTestCase
	{
		private IDbConnection connection = null;

		[TestFixtureSetUp]
		public void SetUpFixture()
		{
			connection = new SQLiteConnection("Data Source=sample.db");
			connection.Open();

			PrimaryKeyFilter pkFilter = new PrimaryKeyFilter();
			pkFilter.Add("people", new PrimaryKey("id"));
			base.PKFilter = pkFilter;

			base.DatabaseHandler = new GenericDatabaseHandler(this.connection);
		}

		[TestFixtureTearDown]
		public void TearDownFixture()
		{
			connection.Close();
		}

		[SetUp]
		public void SetUpTestCase()
		{
			base.SetUp();
		}

		[TearDown]
		public void TearDownTestCase()
		{
			base.TearDown();
		}
		
		protected override IDataSet GetDataSet()
		{
			return new EmbeddedStructuredXmlDataSet(this.GetType());
		}
	}
}
		

Implement your [Test] methods as you normally would for NUnit. Your database is now initialized before and cleaned-up after each test method according to what you did in the previous steps.

DbUnit.NET now supports the use of identity (Auto-Increment) columns. This is achieved by specifying within a Structured XML the primary key column (the identity column) and the identity selector to use to retrieve the value once the insert has occured.

Here's an example followed by a brief explanation.

<?xml version="1.0" encoding="utf-8" ?>
<dataset>
	<Customers PrimaryKey="Id" IdentitySelector="SqliteIdentitySelector">
		<Customer>
			<Name>Acme Ltd</Name>
		</Customer>
	</Customers>
</dataset>
			

The <Customers> element specifies it is the Customers table that is to be inserted into.

The "PrimaryKey" attribute specifies that the primary key column (identity column) is called "id".

The "IdentitySelector" attribute specifies that the value of the identity should be retrieved by using the SqliteIdentitySelector class. This can also be SqlServerIdentitySelector, if MS SQL Server is the database being used.

Note that in the list of columns specified the primary key column is not specified. This is due to the fact that we want the database to generate us the value.

Getting Started for alpha3