Encapsulating AutoFixture Customizations by Mark Seemann
AutoFixture is designed around the 80-20 principle. If your code is well-designed I'd expect a default instance of Fixture to be able to create specimens of your classes without too much trouble. There are cases where AutoFixture needs extra help:
- If a class consumes interfaces a default Fixture will not be able to create it. However, this is easily fixed through one of the AutoMocking Customizations.
- If an API has circular references, Fixture might enter an infinite recursion, but you can easily customize it to cut off one the references.
- Some constructors may only accept arguments that don't fit with the default specimens created by Fixture. There are ways to deal with that as well.
I could keep on listing examples, but let's keep it at that. The key assumption underlying AutoFixture is that these special cases are a relatively small part of the overall API you want to test - preferably much less than 20 percent.
Still, to address those special cases you'll need to customize a Fixture instance in some way, but you also want to keep your test code DRY.
As the popularity of AutoFixture grows, I'm getting more and more glimpses of how people address this challenge: Some derive from Fixture, others create extension methods or other static methods, while others again wrap creation of Fixture instances in Factories or Builders.
There really is no need to do that. AutoFixture has an idiomatic way to encapsulate Customizations. It's called… well… a Customization, which is just another way to say that there's an ICustomization interface that you can implement. This concept corresponds closely to the modularization APIs for several well-known DI Containers. Castle Windsor has Installers, StructureMap has Registries and Autofac has Modules.
The ICustomization interface is simple and has a very gentle learning curve:
public interface ICustomization { void Customize(IFixture fixture); }
Anything you can do with a Fixture instance you can also do with the IFixture instance passed to the Customize method, so this is the perfect place to encapsulate common Customizations to AutoFixture. Note that the AutoMocking extensions as well as several other optional behaviors for AutoFixture are already defined as Customizations.
Using a Customization is also easy:
var fixture = new Fixture() .Customize(new DomainCustomization());
You just need to invoke the Customize method on the Fixture. That's no more difficult than calling a custom Factory or extension method - particularly if you also use a Visual Studio Code Snippet.
When I start a new unit testing project, one of the first things I always do is to create a new ‘default' customization for that project. It usually doesn't take long before I need to tweak it a bit - if nothing else, then for adding the AutoMoqCustomization. To apply separation of concerns I encapsulate each Customization in its own class and compose them with a CompositeCustomization:
public class DomainCustomization : CompositeCustomization { public DomainCustomization() : base( new AutoMoqCustomization(), new FuncCustomization()) { } }
Whenever I need to make sweeping changes to my Fixtures I can simply modify DomainCustomization or one of the Customizations it composes.
In fact, these days I rarely explicitly create new Fixture instances, but rather encapsulate them in a custom AutoDataAttribute like this:
public class AutoDomainDataAttribute : AutoDataAttribute { public AutoDomainDataAttribute() : base(new Fixture() .Customize(new DomainCustomization())) { } }
This means that I can reuse the DomainCustomization across normal, imperative unit tests as well as the declarative, xUnit.net-powered data theories I normally prefer:
[Theory, AutoDomainData] public void CanReserveReturnsTrueWhenQuantityIsEqualToRemaining( Capacity sut, Guid id) { var result = sut.CanReserve(sut.Remaining, id); Assert.True(result); }
Using Customizations to encapsulate your own specializations makes it easy to compose and manage them in an object-oriented fashion.
