SOLID is a set of principles that, if applied consistently, has some surprising effect on code. In a previous post I provided a sketch of what it means to meticulously apply the Single Responsibility Principle. In this article I will describe what happens when you follow the Open/Closed Principle (OCP) to its logical conclusion.

In case a refresher is required, the OCP states that a class should be open for extension, but closed for modification. It seems to me that people often forget the second part. What does it mean?

It means that once implemented, you shouldn’t touch that piece of code ever again (unless you need to correct a bug).

Then how can new functionality be added to a code base? This is still possible through either inheritance or polymorphic recomposition. Since the L in SOLID signifies the Liskov Substitution Principle, SOLID code tends to be based on loosely coupled code composed into an application through copious use of interfaces – basically, Strategies injected into other Strategies and so on (also due to Dependency Inversion Principle). In order to add functionality, you can create new implementations of these interfaces and redefine the application’s Composition Root. Perhaps you’d be wrapping existing functionality in a Decorator or adding it to a Composite.

Once in a while, you’ll stop using an old implementation of an interface. Should you then delete this implementation? What would be the point? At a certain point in time, this implementation was valuable. Maybe it will become valuable again. Leaving it as an potential building block seems a better choice.

Thus, if we think about working with code as a CRUD endeavor, SOLID code can be Created and Read, but never Updated or Deleted. In other words, true SOLID code is append-only code.

Example: Changing AutoFixture’s Number Generation Algorithm

In early 2011 an issue was reported for AutoFixture: Anonymous numbers were created in monotonically increasing sequences, but with separate sequences for each number type:

integers: 1, 2, 3, 4, 5, …

decimals: 1.0, 2.0, 3.0, 4.0, 5.0, …

and so on. However, the person reporting the issue thought it made more sense if all numbers shared a single sequence. After thinking about it a little while, I agreed.

Because the AutoFixture code base is fairly SOLID we decided to leave the old implementations in place and implement the new behavior in new classes.

The old behavior was composed from a set of ISpecimenBuilders. As an example, integers were generated by this class:

public class Int32SequenceGenerator : ISpecimenBuilder

{

    private int i;

    public int CreateAnonymous()

    {

        return Interlocked.Increment(ref this.i);

    }

    public object Create(object request,

        ISpecimenContext context)

    {

        if (request != typeof(int))

        {

            return new NoSpecimen(request);

        }

        return this.CreateAnonymous();

    }

}

Similar implementations generated decimals, floats, doubles, etc. Instead of modifying any of these classes, we left them in the code base and created a new ISpecimenBuilder that generates all numbers from a single sequence:

public class NumericSequenceGenerator : ISpecimenBuilder

{

    private int value;

    public object Create(object request,

        ISpecimenContext context)

    {

        var type = request as Type;

        if (type == null)

            return new NoSpecimen(request);

        return this.CreateNumericSpecimen(type);

    }

    private object CreateNumericSpecimen(Type request)

    {

        var typeCode = Type.GetTypeCode(request);

        switch (typeCode)

        {

            case TypeCode.Byte:

                return (byte)this.GetNextNumber();

            case TypeCode.Decimal:

                return (decimal)this.GetNextNumber();

            case TypeCode.Double:

                return (double)this.GetNextNumber();

            case TypeCode.Int16:

                return (short)this.GetNextNumber();

            case TypeCode.Int32:

                return this.GetNextNumber();

            case TypeCode.Int64:

                return (long)this.GetNextNumber();

            case TypeCode.SByte:

                return (sbyte)this.GetNextNumber();

            case TypeCode.Single:

                return (float)this.GetNextNumber();

            case TypeCode.UInt16:

                return (ushort)this.GetNextNumber();

            case TypeCode.UInt32:

                return (uint)this.GetNextNumber();

            case TypeCode.UInt64:

                return (ulong)this.GetNextNumber();

            default:

                return new NoSpecimen(request);

        }

    }

    private int GetNextNumber()

    {

        return Interlocked.Increment(ref this.value);

    }

}

Adding a new class in itself has no effect, so in order to recompose the default behavior of AutoFixture, we changed a class called DefaultPrimitiveBuilders by removing the old ISpecimenBuilders like Int32SequenceGenerator and instead adding NumericSequenceGenerator:

yield return new StringGenerator(() => 

    Guid.NewGuid());

yield return new ConstrainedStringGenerator();

yield return new StringSeedRelay();

yield return new NumericSequenceGenerator();

yield return new CharSequenceGenerator();

yield return new RangedNumberGenerator();

// even more builders...

NumericSequenceGenerator is the fourth class being yielded here. Before we added NumericSequenceGenerator, this class instead yielded Int32SequenceGenerator and similar classes. These were removed.

The DefaultPrimitiveBuilders class is part of AutoFixture’s default Facade and is the closest we get to a Composition Root for the library. Recomposing this Facade enabled us to change the behavior of AutoFixture without modifying (other) existing classes.

As Enrico (who implemented this change) points out, the beauty is that the previous behavior is still in the box, and all it takes is a single method call to bring it back:

var fixture = new Fixture().Customize(

    new NumericSequencePerTypeCustomization());

The only class we had to modify was the DefaultPrimitiveBuilders, which is where the object graph is composed. In applications this corresponds to the Composition Root, so even in the face of SOLID code, you still need to modify the Composition Root in order to recompose the application. However, use of a good DI Container and a strong set of conventions can do much to minimize the required editing of such a class.

SOLID versus Refactoring

SOLID is a goal I strive towards in the way I write code and design APIs, but I don’t think I’ve ever written a significant code base which is perfectly SOLID. While I consider AutoFixture a ‘fairly’ SOLID code base, it’s not perfect, and I’m currently performing some design work in order to change some abstractions for version 3.0. This will require changing some of the existing types and thereby violating the OCP.

It’s worth noting that as long as you can stick with the OCP you can avoid introducing breaking changes. A breaking change is also an OCP violation, so adhering to the OCP is more than just an academic exercise – particularly if you write reusable libraries.

Still, while none of my code is perfect and I occasionally have to refactor, I don’t refactor much. By definition, refactoring means violating the OCP, and while I have nothing against refactoring code when it’s required, I much prefer putting myself in a situation where it’s rarely necessary in the first place.

I’ve often been derided for my lack of use of Resharper. When replying that I have little use for Resharper because I write SOLID code and thus don’t do much refactoring, I’ve been ridiculed for being totally clueless. People don’t realize the intimate relationship between SOLID and refactoring. I hope this post has helped highlight that connection.

Greg Young gave a talk at GOTO Aarhus 2011 titled Developers have a mental disorder, which was (semi-)humorously meant, but still addressed some very real concerns about the cognitive biases of software developers as a group. While I have no intention to provide a complete resume of the talk, Greg said one thing that made me think a bit (more) about SOLID code. To paraphrase, it went something like this:

Developers have a tendency to attempt to solve specific problems with general solutions. This leads to coupling and complexity. Instead of being general, code should be specific.

This sounds correct at first glance, but once again I think that SOLID code offers a solution. Due to the Single Responsibility Principle each SOLID concrete (pardon the pun) class will tend to very specifically address a very narrow problem.

Such a class may implement one (or more) general-purpose interface(s), but the concrete type is specific.

The difference between the generality of an interface and the specificity of a concrete type becomes more and more apparent the better a code base applies the Reused Abstractions Principle. This is best done by defining an API in terms of Role Interfaces, which makes it possible to define a few core abstractions that apply very broadly, while implementations are very specific.

As an example, consider AutoFixture’s ISpecimenBuilder interface. This is a very central interface in AutoFixture (in fact, I don’t even know just how many implementations it has, and I’m currently too lazy to count them). As an API, it has proven to be very generally useful, but each concrete implementation is still very specific, like the CurrentDateTimeGenerator shown here:

public class CurrentDateTimeGenerator : ISpecimenBuilder

{

    public object Create(object request, 

        ISpecimenContext context)

    {

        if (request != typeof(DateTime))

        {

            return new NoSpecimen(request);

        }

        return DateTime.Now;

    }

}

This is, literally, the entire implementation of the class. I hope we can agree that it’s very specific.

In my opinion, SOLID is a set of principles that can help us keep an API general while each implementation is very specific.

In SOLID code all concrete types are specific.

For the last couple of months I’ve been working on setting up AutoFixture for Continuous Delivery (thanks to the nice people at http://teamcity.codebetter.com/ for supplying the CI service) and I think I’ve finally succeeded. I’ve just pushed some code from my local Mercurial repository, and 5 minutes later the release is live on both the CodePlex site as well as on the NuGet Gallery.

The plan for AutoFixture going forward is to maintain Continuous Delivery and switch the versioning scheme from ad hoc to Semantic Versioning. This means that obviously you’ll see releases much more often, and versions are going to be incremented much more often. Since the previous release the current release incidentally ended at version 2.2.44, but since the versioning scheme has now changed, you can expect to see 2.3, 2.4 etc. in rapid succession.

While I’ve been mostly focused on setting up Continuous Delivery, Nikos Baxevanis and Enrico Campidoglio have been busy writing new features:

• Support for anonymous delegates
• Heuristics for static factory methods
• Inline AutoData Theories
• More anonymous numbers

Apart from these excellent contributions, other new features are

• Added StableFiniteSequenceCustomization
• Added [FavorArrays], [FavorEnumerables] and [FavorLists] attributes to xUnit.net extension
• Added a Generator<T> class
• Added a completely new project/package called Idioms, which contains convention-based tests (more about this later)
• Probably some other things I’ve forgotten about…

While you can expect to see version numbers to increase more rapidly and releases to occur more frequently, I’m also beginning to think about AutoFixture 3.0. This release will streamline some of the API in the root namespace, which, I’ll admit, was always a bit haphazard. For those people who care, I have no plans to touch the API in the Ploeh.AutoFixture.Kernel namespace. AutoFixture 3.0 will mainly target the API contained in the Ploeh.AutoFixture namespace itself.

Some of the changes I have in mind will hopefully make the default experience with AutoFixture more pleasant – I’m unofficially thinking about AutoFixture 3.0 as the ‘pit of success’ release. It will also enable some of the various outstanding feature requests.

Feedback is, as usual, appreciated.

Recently I had the inclination to do the Tennis Kata a couple of times. The first time I saw it I thought it wasn’t terribly interesting as an exercise in C# development. It would basically just be an application of the State pattern, so I decided to make it a bit more interesting. More or less by intuition I decided to give myself the following constraints:

• All types must be immutable
• All members must have a cyclomatic complexity of 1

Now that’s more interesting :)

Given these constraints, what would be the correct approach? Given that this is a finite state machine with a fixed number of states, the Visitor pattern will be a good match.

Each player’s score can be modeled as a Value Object that can be one of these types:

• ZeroPoints
• FifteenPoints
• ThirtyPoints
• FortyPoints
• AdvantagePoint
• GamePoint

All of these classes implement the IPoints interface:

public interface IPoints

{

    IPoints Accept(IPoints visitor);

    IPoints LoseBall();

    IPoints WinBall(IPoints opponentPoints);

    IPoints WinBall(AdvantagePoint opponentPoints);

    IPoints WinBall(FortyPoints opponentPoints);

}

The interesting insight here is that until the opponent's score reaches FortyPoints nothing special happens. Those states can be effectively collapsed into the WinBall(IPoints) method. However, when the opponent either has FortyPoints or AdvantagePoint, special things happen, so IPoints has specialized methods for those cases. All implementations should use double dispatch to invoke the correct overload of WinBall, so the Accept method must be implemented like this:

public IPoints Accept(IPoints visitor)

{

    return visitor.WinBall(this);

}

That’s the core of the Visitor pattern in action. When the implementer of the Accept method is either FortyPoints or AdvantagePoint, the specialized overload will be invoked.

It’s now possible to create a context around a pair of IPoints (called a Game) to implement a method to register that Player 1 won a ball:

public Game PlayerOneWinsBall()

{

    var newPlayerOnePoints = this.PlayerTwoScore

        .Accept(this.PlayerOneScore);

    var newPlayerTwoPoints = 

        this.PlayerTwoScore.LoseBall();

    return new Game(

        newPlayerOnePoints, newPlayerTwoPoints);

}

A similar method for player two simply reverses the roles. (I’m currently reading Lean Architecture, but have yet to reach the chapter on DCI. However, considering what I’ve already read about DCI, this seems to fit the bill pretty well… although I might be wrong on that account.)

The context calculates new scores for both players and returns the result as a new instance of the Game class. This keeps the Game and IPoints implementations immutable.

The new score for the winner depends on the opponent’s score, so the appropriate overload of WinBall should be invoked. The Visitor implementation makes it possible to pick the right overload without resorting to casts and if statements. As an example, the FortyPoints class implements the three WinBall overloads like this:

public IPoints WinBall(IPoints opponentPoints)

{

    return new GamePoint();

}

public IPoints WinBall(FortyPoints opponentPoints)

{

    return new AdvantagePoint();

}

public IPoints WinBall(AdvantagePoint opponentPoints)

{

    return this;

}

It’s also important to correctly implement the LoseBall method. In most cases, losing a ball doesn’t change the current state of the loser, in which case the implementation looks like this:

public IPoints LoseBall()

{

    return this;

}

However, when the player has advantage and loses the ball, he or she loses the advantage, so for the AdvantagePoint class the implementation looks like this:

public IPoints LoseBall()

{

    return new FortyPoints();

}

To keep things simple I decided to implicitly model deuce as both players having FortyPoints, so there’s not explicit Deuce class. Thus, AdvantagePoint returns FortyPoints when losing the ball.

Using the Visitor pattern it’s possible to keep the cyclomatic complexity at 1. The code has no branches or loops. It’s immutable to boot, so a game might look like this:

[Fact]

public void PlayerOneWinsAfterHardFight()

{

    var game = new Game()

        .PlayerOneWinsBall()

        .PlayerOneWinsBall()

        .PlayerOneWinsBall()

        .PlayerTwoWinsBall()

        .PlayerTwoWinsBall()

        .PlayerTwoWinsBall()

        .PlayerTwoWinsBall()

        .PlayerOneWinsBall()

        .PlayerOneWinsBall()

        .PlayerOneWinsBall();

    Assert.Equal(new GamePoint(), game.PlayerOneScore);

    Assert.Equal(new FortyPoints(), game.PlayerTwoScore);

}

In case you’d like to take a closer look at the code I’m attaching it to this post. It was driven completely by using the AutoFixture.Xunit extension, so if you are interested in idiomatic AutoFixture code it’s also a good example of that.

Since I announced AutoFixture 2.1 beta 1 no issues have been reported, so I’ve now promoted the release to the official 2.1 release. This means that if you already downloaded AutoFixture 2.1 beta 1, you already have the 2.1 binaries. If not, you can head over to the release page to get it.

The NuGet packages will soon be available.

Update (2011.5.4): The NuGet packages are now available.

It gives me great pleasure to announce that AutoFixture 2.1 beta 1 is now available for download. Compared to version 2.0 this release mostly contains added features as well as a few bug fixes. The release page contains a list of the new features.

The general availability of beta 1 of AutoFixture 2.1 marks the beginning of a trial period. If no new issues are reported within the next few weeks, a final version 2.1 will be released. If too many issues are reported, a new beta version may be necessary.

Please report any issues you find.

NuGet packages will follow the RTW version.

When AutoFixture creates complex objects it invokes the constructors of the types in question. When a class exposes more than one constructor, the default behavior is to pick the constructor with the fewest number  of arguments. This is the exact opposite of most DI Containers that select the greediest constructor.

For a DI Container it makes more sense to select the greediest constructor because that maximizes the chance that all dependencies are properly being auto-wired.

The reason that AutoFixture’s default behavior is different is that it maximizes the chance that an object graph can be created at all. If a convenience overload is available, this gives AutoFixture a better chance to compose the object graph.

This works well until a class comes along and introduces the wrong kind of ambiguity. Consider this case of Bastard Injection (Dependency Injection in .NET, section 5.2):

public class Bastard

{

    private readonly IFoo foo;

    public Bastard()

        : this(new DefaultFoo())

    {

    }

    public Bastard(IFoo foo)

    {

        if (foo == null)

        {

            throw new ArgumentNullException("foo");

        }

        this.foo = foo;

    }

    public IFoo Foo

    {

        get { return this.foo; }

    }

}

By default AutoFixture will use the default constructor which means that the Foo will always be the instance of DefaultFoo owned by the Bastard class itself. This is problematic if we wish to inject and freeze a Test Double because even if we freeze an IFoo instance, it will never be injected because the default constructor is being invoked.

var fixture = new Fixture();

fixture.Register<IFoo>(

    fixture.CreateAnonymous<DummyFoo>);

var b = fixture.CreateAnonymous<Bastard>();

Assert.IsAssignableFrom<DefaultFoo>(b.Foo);

As the above unit test demonstrates, even though the Register method call defines a mapping from IFoo to DummyFoo, the Foo property is an instance of DefaultFoo. The DummyFoo instance is never injected into the Bastard instance since the default constructor is used.

Your first reaction in such a case should be to get rid of all convenience constructors to make the the class’ constructor unambiguous. However, it’s also possible to change AutoFixture’s behavior.

The following is a description of a feature that will be a available in AutoFixture 2.1. It’s not available in AutoFixture 2.0, but is already available in the code repository. Thus, if you can’t wait for AutoFixture 2.1 you can download the source and build it.

As always, AutoFixture’s very extensible interface makes it possible to change this behavior. Constructor selection is guided by an interface called IConstructorQuery, and while ModestConstructorQuery is the default implementation, there’s also an implementation called GreedyConstructorQuery.

To change the behavior specifically for the Bastard class the Fixture instance must be customized. The following unit test demonstrates how to do that.

var fixture = new Fixture();

fixture.Customize<Bastard>(c => c.FromFactory(

    new ConstructorInvoker(

        new GreedyConstructorQuery())));

fixture.Register<IFoo>(

    fixture.CreateAnonymous<DummyFoo>);

var b = fixture.CreateAnonymous<Bastard>();

Assert.IsAssignableFrom<DummyFoo>(b.Foo);

Notice that the only difference from before is an additional call to the Customize method where Bastard is modified to use greedy constructor selection. This changes the factory for the Bastard type, but not for any other types.

If you’d rather prefer to completely change the overall constructor selection behavior for AutoFixture you can add the GreedyConstructorQuery wrapped in a ConstructorInvoker to the Fixture’s Customizations:

var fixture = new Fixture();

fixture.Customizations.Add(

    new ConstructorInvoker(

        new GreedyConstructorQuery()));

fixture.Register<IFoo>(

    fixture.CreateAnonymous<DummyFoo>);

var b = fixture.CreateAnonymous<Bastard>();

Assert.IsAssignableFrom<DummyFoo>(b.Foo);

In this unit test, the only change from the previous is that instead of assigning the GreedyConstructorQuery specifically to Bastard, it’s now assigned as the new default strategy. All specimens created by AutoFixture will be created by invoking their most greedy constructor.

As always I find the default behavior more attractive, but the option to change behavior is there if you need it.

I just got a question about AutoFixture’s way of dealing with enumerables, and since I suspect this is something that might surprise a few people I found it reasonable to answer in a blog post.

In short, this unit test succeeds:

var fixture = new Fixture();

var expected = fixture.CreateMany<string>();

Assert.False(expected.SequenceEqual(expected));

If this doesn’t surprise you, then read the assertion again. The sequence is expected to not equal itself!

This behavior is by design.

(I’ve always wanted to write that.) The reason is that the return type of the CreateMany method is IEnumerable<T>, and that interface makes no guarantee that it will return the same sequence every time you iterate over it. The implementation may be a Generator.

According to its principle of Constrained Non-determinism, AutoFixture goes to great lengths to ensure that since IEnumerable<T> might be non-deterministic, it will be. This can be very useful in flushing out incorrect assumptions made by the SUT.

This behavior is carried forward by the MultipleCustomization. This unit test also succeeds:

var fixture = new Fixture()

    .Customize(new MultipleCustomization());

var expected =

    fixture.CreateAnonymous<IEnumerable<string>>();

Assert.False(expected.SequenceEqual(expected));

The behavior is the same because with the MultipleCustomization IEnumerable<T> acts as a relationship type. The class responsible for this behavior is called FiniteSequenceRelay, but AutoFixture 2.1 will also ship with an alternative StableFiniteSequenceRelay which wraps the sequence in a List<T>.

To change the default behavior you can add the StableFiniteSequenceRelay to a Fixture’s customizations:

var fixture = new Fixture();

var stableRelay = new StableFiniteSequenceRelay();

fixture.Customizations.Add(stableRelay);

var expected =

    fixture.CreateMany<string>();

Assert.True(expected.SequenceEqual(expected));

The above unit test succeeds. Notice that the assertion now verifies that the sequence of strings is equal to itself.

Just like MultipleCustomization the StableFiniteSequenceRelay class will be available in AutoFixture 2.1, but is not availale in 2.0.

As always, it’s best to encapsulate this behavior change into a Customization:

public class StableFiniteSequenceCustomization :

    ICustomization

{

    public void Customize(IFixture fixture)

    {

        var stableRelay = 

            new StableFiniteSequenceRelay();

        fixture.Customizations.Add(stableRelay);

    }

}

This makes it easier to bundle it with the MultipleCustomization if we want all the other benefits of conventions for multiples:

public class StableMultipeCustomization : 

    CompositeCustomization

{

    public StableMultipeCustomization()

        : base(

            new StableFiniteSequenceCustomization(),

            new MultipleCustomization())

    {

    }

}

With the StableMultipleCustomization the following unit test now passes:

var fixture = new Fixture()

    .Customize(new StableMultipeCustomization());

var expected =

    fixture.CreateAnonymous<IEnumerable<string>>();

Assert.True(expected.SequenceEqual(expected));

I still prefer the default behavior for its potential to act as an early warning system, but as I realize that this behavior may be problematic in some scenarios, the StableFiniteSequenceRelay provides an easy way to change that behavior.

Update (2011.8.10): StableFiniteSequenceCustomization is now part of AutoFixture and will be available in AutoFixture 2.2.

My latest MSDN Magazine article, this time about CQRS on Windows Azure, is now available at the April MSDN Magazine web site.

It’s mostly meant as an introduction to CQRS as well as containing some tips and tricks that are specific to applying CQRS on Windows Azure.

As an added bonus the code sample download contains lots of idiomatic unit tests written with AutoFixture’s xUnit.net extensions, so if you’d like to see the result of my TDD work with AutoFixture, there’s a complete code base to look at there.

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.

In my previous post I described how to customize a Fixture instance to populate lists with items instead of returning empty lists. While it’s pretty easy to do so, the drawback is that you have to do it explicitly for every type you want to influence. In this post I will follow up by describing how to enable some general conventions that simply populates all collections that the Fixture resolves.

This post describes a feature that will be available in AutoFixture 2.1. It’s not available in AutoFixture 2.0, but is already available in the code repository. Thus, if you can’t wait for AutoFixture 2.1 you can download the source and built it.

Instead of having to create multiple customizations for IEnumerable<int>, IList<int>, List<int>, IEnumerable<string>, IList<string>, etc. you can simply enable these general conventions as easy as this:

var fixture = new Fixture()

    .Customize(new MultipleCustomization());

Notice that enabling conventions for populating sequences and lists with ‘many’ items is an optional customization that you must explicitly add.

This feature must be explicitly enabled. There are several reasons for that:

• It would be a breaking change if AutoFixture suddenly started to behave like this by default.
• The MultipleCustomization targets not only concrete types such as List<T> and Collection<T>, but also interfaces such as IEnumerable<T>, IList<T> etc. Thus, if you also use AutoFixture as an Auto-Mocking container, I wanted to provide the ability to define which customization takes precedence.

With that simple customization enabled, all requested IEnumerable<T> are now populated. The following will give us a finite, but populated list of integers:

var integers = 

    fixture.CreateAnonymous<IEnumerable<int>>();

This will give us a populated List<int>:

var list = fixture.CreateAnonymous<List<int>>();

This will give us a populated Collection<int>:

var collection = 

    fixture.CreateAnonymous<Collection<int>>();

As implied above, it also handles common list interfaces, so this gives us a populated IList<T>:

var list = fixture.CreateAnonymous<IList<int>>();

The exact number of ‘many’ is as always determined by the Fixture’s RepeatCount.

As this code is still (at the time of publishing) in preview, I would love to get feedback on this feature.

How do you get AutoFixture to create populated lists or sequences of items? Recently I seem to have been getting this question a lot, and luckily it’s quite easy to answer.

Let’s first look at the standard AutoFixture behavior and API.

You can ask AutoFixture to create an anonymous List like this:

var list = fixture.CreateAnonymous<List<int>>();

Seen from AutoFixture’s point of view, List<int> is just a class like any other. It has a default constructor, so AutoFixture just uses that and returns an instance. You get back an instance, no exceptions are thrown, but the list is empty. What if you’d rather want a populated list?

There are many ways to go about this. A simple, low-level solution is to populate the list after creation:

fixture.AddManyTo(list);

However, you may instead prefer getting a populated list right away. This is also possible, but before we look at how to get there, I’d like to point out a feature that surprisingly few users notice. You can create many anonymous specimens at once:

var integers = fixture.CreateMany<int>();

Armed with this knowledge, as well as the knowledge of how to map types, we can now create this customization to map IEnumerable<int> to CreateMany<int>:

fixture.Register(() => fixture.CreateMany<int>());

The Register method is really a generic method, but since we have type inference, we don’t have to write it out. However, since CreateMany<int>() returns IEnumerable<int>, this is the type we register. Thus, every time we subsequently resolve IEnumerable<int>, we will get back a populated sequence.

Getting back to the original List<int> example, we can now customize it to a populated list like this:

fixture.Register(() =>

    fixture.CreateMany<int>().ToList());

Because the ToList() extension method returns List<T>, this call registers List<int> so that we will get back a populated list of integers every time the fixture resolves List<int>.

What about other collection types that don’t have a nice LINQ extension method? Personally, I never use Collection<T>, but if you wanted, you could customize it like this:

fixture.Register(() =>

    new Collection<int>(

        fixture.CreateMany<int>().ToList()));

Since Collection<T> has a constructor overload that take IList<T> we can customize the type to use this specific overload and populate it with ‘many’ items.

Finally, we can combine all this to map from collection interfaces to populated lists. As an example, we can map from IList<int> to a populated List<int> like this:

fixture.Register<IList<int>>(() => 

    fixture.CreateMany<int>().ToList());

When we use the Register method to map types we can no longer rely on type inference. Instead, we must explicitly register IList<int> against a delegate that creates a populated List<int>. Because List<int> implements IList<int> this compiles. Whenever this fixture instance resolves IList<int> it will create a populated List<int>.

All of this describes what you can do with the strongly typed API available in AutoFixture 2.0. It’s easy and very flexible, but the only important drawback is that it’s not general. All of the customizations in this post specifically address lists and sequences of integers, but not lists of any other type. What if you would like to expand this sort of behavior to any List<T>, IEnumerable<T> etc?

Stay tuned, because in the next post I will describe how to do that.

Back in the days of AutoFixture 1.0 I occasionally got the feedback that although people liked the engine and its features, they didn’t like the data it generated. I think they particularly didn’t like all the Guids, but Håkon Forss suggested combining Object Hydrator’s data generator with AutoFixture.

In fact, this suggestion made me realize that AutoFixture 1.0’s engine wasn’t extensible enough, which again prompted me to build AutoFixture 2.0. Now that AutoFixture 2.0 is out, what would be more fitting than to examine whether we can do what Håkon suggested?

It turns out to be pretty easy to customize AutoFixture to use Object Hydrator’s data generator. The main part is creating a custom ISpecimenBuilder that acts as an Adapter of Object Hydrator:

public class HydratorAdapter : ISpecimenBuilder

{

    private readonly IMap map;

    public HydratorAdapter(IMap map)

    {

        if (map == null)

        {

            throw new ArgumentNullException("map");

        }

        this.map = map;

    }

    #region ISpecimenBuilder Members

    public object Create(object request,

        ISpecimenContext context)

    {

        var pi = request as PropertyInfo;

        if (pi == null)

        {

            return new NoSpecimen(request);

        }

        if ((!this.map.Match(pi))

            || (this.map.Type != pi.PropertyType))

        {

            return new NoSpecimen(request);

        }

        return this.map.Mapping(pi).Generate();

    }

    #endregion

}

The IMap interface is defined by Object Hydrator, ISpecimenBuilder and NoSpecimen are AutoFixture types and the rest are BCL types.

Each HydratorAdapter adapts a single IMap instance. The IMap interface only works with PropertyInfo instances, so the first thing to do is to examine the request to figure out whether it’s a request for a PropertyInfo at all. If this is the case and the map matches the request, we ask it to generate a specimen for the property.

To get all of Object Hydrator’s maps into AutoFixture, we can now define this customization:

public class ObjectHydratorCustomization :

    ICustomization

{

    #region ICustomization Members

    public void Customize(IFixture fixture)

    {

        var builders = from m in new DefaultTypeMap()

                        select new HydratorAdapter(m);

        fixture.Customizations.Add(

            new CompositeSpecimenBuilder(builders));

    }

    #endregion

}

The ObjectHydratorCustomization simply projects all maps from Object Hydrator’s DefaultTypeMap into instances of HydratorAdapter and adds these as customizations to the fixture.

This enables us to use Object Hydrator with any Fixture instance like this:

var fixture = new Fixture()

    .Customize(new ObjectHydratorCustomization());

To prove that this works, here’s a dump of a Customer type created in this way:

{

  "Id": 1,

  "FirstName": "Raymond",

  "LastName": "Reeves",

  "Company": "Carrys Candles",

  "Description": "Lorem ipsum dolor sit",

  "Locations": 53,

  "IncorporatedOn": "\/Date(1376154940000+0200)\/",

  "Revenue": 33.57,

  "WorkAddress": {

    "AddressLine1": "32373 BALL Lane",

    "AddressLine2": "29857 DEER PARK Dr.",

    "City": "fullerton",

    "State": "NM",

    "PostalCode": "27884",

    "Country": "GI"

  },

  "HomeAddress": {

    "AddressLine1": "66377 NORTH STAR Pl.",

    "AddressLine2": "33406 MAY Dr.",

    "City": "miami",

    "State": "MD",

    "PostalCode": "18361",

    "Country": "PH"

  },

  "Addresses": [],

  "HomePhone": "(388)538-1266",

  "Type": 0

}

Without Object Hydrator’s data generators, this would have looked like this instead:

{

  "Id": 1,

  "FirstName": "FirstNamebf53cb4c-3aae-4963-bb0c-ad0219293736",

  "LastName": "LastName079f7ab2-d026-48c5-8cfb-76e0568d1d79",

  "Company": "Company9ffe4640-2534-4ef7-b066-fb6bbe3a668c",

  "Description": "Descriptionf5843974-b14b-4bce-b3cc-63ad6aaf3ab2",

  "Locations": 2,

  "IncorporatedOn": "\/Date(1290169587222+0100)\/",

  "Revenue": 1.0,

  "WorkAddress": {

    "AddressLine1": "AddressLine1f4d50570-423e-4a74-8348-1c54402ffe48",

    "AddressLine2": "AddressLine2031fe3e2-40c1-4ec3-b445-e88c213457e9",

    "City": "Citycd33fce3-66bb-457d-8f99-98a16c0c5bf1",

    "State": "State40bebd6d-6073-4421-8a74-e910ff9d09e3",

    "PostalCode": "PostalCode1da93f22-799b-4f6b-a5ce-f4816f8bbb05",

    "Country": "Countryfa2ad951-ce0c-42a4-ab55-c077b6e03f00"

  },

  "HomeAddress": {

    "AddressLine1": "AddressLine145cbffeb-d7a9-4778-b297-d010c30b7614",

    "AddressLine2": "AddressLine2e86d6476-5bdc-4940-a8ee-975bf3f65d49",

    "City": "City6ae3aab9-7c73-4768-ae7d-a6ea515c816a",

    "State": "State56de6222-fd84-46b0-ace0-c6098dbd0681",

    "PostalCode": "PostalCodeca1af9af-a97b-4966-b156-cfbebd6d5e38",

    "Country": "Country6960eebe-fe6f-4b63-ad73-7ba6a2b95791"

  },

  "Addresses": [],

  "HomePhone": "HomePhone623f9d6f-febe-4c9f-87f8-e90d7e57eb46",

  "Type": 0

}

One limitation of Object Hydrator is that it requires the classes to have default constructors. AutoFixture doesn’t have that constraint, and to prove that I defined the only available Customer constructor like this:

public Customer(int id)

With AutoFixture, this is not a problem and the Customer instance is created as described above.

With the extensibility model of AutoFixture 2.0 I am pleased to be able to verify that Håkon Forss (and others) can now have the best of both worlds :)

AutoFixture now includes a Rhino Mocks-based auto-mocking feature similar to the Moq-based auto-mocking customization previously described.

The developer of this great optional feature, the talented but discreet Mikkel has this to say:

“The auto-mocking capabilities of AutoFixture now include auto-mocking using Rhino Mocks, completely along the same lines as the existing Moq-extension. Although it will not be a part of the .zip-distribution before the next official release, it can be built from the latest source code (November 13, 2010) which contains the relevant VS2008 solution: AutoRhinoMock.sln. It is built on Rhino.Mocks version 3.6.0.0. To use it, add a reference to Ploeh.AutoFixture.AutoRhinoMock.dll and customize the Fixture instance with:

var fixture = new Fixture()

    .Customize(new AutoRhinoMockCustomization());

“which automatically will result in mocked instances of requests for interfaces and abstract classes.”

I’m really happy to see the AutoFixture eco-system grow in this way, as it both demonstrates how AutoFixture gives you great flexibility and enables you to work with the tools you prefer.

As previous posts have described, AutoFixture creates Anonymous Variables based on the notion of being able to always hit within a well-behaved Equivalence Class for a given type. This works well a lot of the time because AutoFixture has some sensible defaults: numbers are positive integers and strings are GUIDs.

This last part only works as long as strings are nothing but opaque blobs to the consuming class. This is, however, not an unreasonable assumption. Consider classes that implement Entities such as Person or Address. Strings will often take the form of FirstName, LastName, Street, etc. In all such cases, the value of the string usually doesn’t matter.

However, there will always be cases where the value of a string has a special meaning of its own. It will often be best to let AutoFixture guide us towards a better API design, but this is not always possible. Sometimes there are rules that constrain the formatting of a string.

As an example, consider a Money class with this constructor:

public Money(decimal amount, string currencyCode)
{
    if (currencyCode == null)
    {
        throw new ArgumentNullException("...");
    }
    if (!CurrencyCodes.IsValid(currencyCode))
    {
        throw new ArgumentException("...");
    }
 
    this.amount = amount;
    this.currencyCode = currencyCode;
}

Notice that the constructor only allows properly formatted currency codes (such as e.g. “DKK”, “USD”, “AUD”, etc.) through, while other strings will throw an exception. AutoFixture’s default behavior of creating GUIDs as strings is problematic, as the Money constructor will throw on a GUID.

We could attempt to fix this by changing the way AutoFixture generates strings in general, but that may not be the best solution as it may interfere with other string values. It is, however, easy to do:

fixture.Inject("DKK");

This simply injects the “DKK” string into the fixture, causing all subsequent strings to have the same value. However, a hypothetical Pizza class with Name and Description properties in addition to a Price property of type Money will now look like this:

{
  "Name": "DKK",
  "Price": {
    "Amount": 1.0,
    "CurrencyCode": "DKK"
  },
  "Description": "DKK"
}

What we really want is to customize only the currency code. This is where the extremely customizable architecture of AutoFixture can help us. As the documentation explains, lots of different request will flow through the kernel’s Chain of Responsibility to create a Money instance. To populate the two parameters of the Money constructor, two ParameterInfo requests will be issued – one for each parameter. We can take advantage of this to create a custom ISpecimenBuilder that only addresses string parameters with the name currencyCode.

public class CurrencyCodeSpecimenBuilder : 
    ISpecimenBuilder
{
    public object Create(object request,
        ISpecimenContext context)
    {
        var pi = request as ParameterInfo;
        if (pi == null)
        {
            return new NoSpecimen(request);
        }
        if (pi.ParameterType != typeof(string)
            || pi.Name != "currencyCode")
        {
            return new NoSpecimen(request);
        }
 
        return "DKK";
    }
}

It simply examines the request to determine whether this is something that it should address at all. Only if the request is a ParameterInfo representing a string parameter named currencyCode do we deal with it. In any other case we return NoSpecimen, which simply tells AutoFixture that it should ask another ISpecimenBuilder instead.

Here we just return the hard-coded string “DKK”, but we could easily have expanded the example to use a more varied generation algorithm. I will leave that, as well as how to generalize this in other ways, as exercises to the reader.

With CurrencyCodeSpecimenBuilder available, we can add it to the Fixture like this:

fixture.Customizations.Add(
    new CurrencyCodeSpecimenBuilder());

With this customization added, a Pizza instance now looks like this:

{
  "Name": "namec6b7a923-ea78-4817-9e24-a6863a597645",
  "Price": {
    "Amount": 1.0,
    "CurrencyCode": "DKK"
  },
  "Description": "Description63ef17d7-876d-46d8-af73-1ed91f83e699"
}

Notice how only the currency code is affected while all other string values are created by the default algorithm.

In a nutshell, a custom ISpecimenBuilder can be used to implement all sorts of custom conventions for AutoFixture. The one shown here applies the string “DKK” to all string parameters named currencyCode. This mean that the convention isn’t necessarily constrained to the Money constructor, but applies to all ParamterInfo instances that fit the specification.

It gives me great pleasure to announce the release of AutoFixture 2.0. This release fixes a few minor issues since beta 1, but apart from that there are no significant changes.

This is a major release compared to AutoFixture 1.1, featuring a completely new kernel, as well as new features and extensibility points. The beta 1 announcement sums up the changes. Get it here.

AutoFixture 2.0 comes with a new extension for xUnit.net data theories. For those of us using xUnit.net, it can help make our unit tests more succinct and declarative.

AutoFixture’s support for xUnit.net is implemented in a separate assembly. AutoFixture itself has no dependency on xUnit.net, and if you use another unit testing framework, you can just ignore the existence of the Ploeh.AutoFixture.Xunit assembly.

Let’s go back and revisit the previous test we wrote using AutoFixture and its auto-mocking extension:

[Fact]

public void AddWillPipeMapCorrectly()

{

    // Fixture setup

    var fixture = new Fixture()

        .Customize(new AutoMoqCustomization());

    var basket = fixture.Freeze<Basket>();

    var mapMock = fixture.Freeze<Mock<IPizzaMap>>();

    var pizza = fixture.CreateAnonymous<PizzaPresenter>();

    var sut = fixture.CreateAnonymous<BasketPresenter>();

    // Exercise system

    sut.Add(pizza);

    // Verify outcome

    mapMock.Verify(m => m.Pipe(pizza, basket.Add));

    // Teardown

}

Notice how all of the Fixture Setup phase is only used to create various objects that will be used in the test. First we create the fixture object, and then we use it to create four other objects. That turns out to be a pretty common idiom when using AutoFixture, so it’s worthwhile to reduce the clutter if possible.

With xUnit.net’s excellent extensibility features, we can. AutoFixture 2.0 now includes the AutoDataAttribute in a separate assembly. AutoDataAttribute derives from xUnit.net’s DataAttribute (just like InlineDataAttribute), and while we can use it as is, it becomes really powerful if we combine it with auto-mocking like this:

public class AutoMoqDataAttribute : AutoDataAttribute

{

    public AutoMoqDataAttribute()

        : base(new Fixture()

            .Customize(new AutoMoqCustomization()))

    {

    }

}

This is a custom attribute that combines AutoFixture’s two optional extensions for auto-mocking and xUnit.net support. With the AutoMoqDataAttribute in place, we can now rewrite the above test like this:

[Theory, AutoMoqData]

public void AddWillPipeMapCorrectly([Frozen]Basket basket,

    [Frozen]Mock<IPizzaMap> mapMock, PizzaPresenter pizza,

    BasketPresenter sut)

{

    // Fixture setup

    // Exercise system

    sut.Add(pizza);

    // Verify outcome

    mapMock.Verify(m => m.Pipe(pizza, basket.Add));

    // Teardown

}

The AutoDataAttribute simply uses a Fixture object to create the objects declared in the unit tests parameter list. Notice that the test is no longer a [Fact], but rather a [Theory].

The only slightly tricky thing to notice is that when we declare a parameter object, it will automatically map to a call to the CreateAnonymous method for the parameter type. However, when we need to invoke the Freeze method, we can add the [Frozen] attribute in front of the parameter.

The best part about data theories is that they don’t prevent us from writing normal unit tests in the same Test Class, and this carries over to the [AutoData] attribute. We can use it when it’s possible, but for those more complex tests where we need to interact with a Fixture instance, we can still write a normal [Fact].

One of my Twitter followers who appears to be using AutoFixture recently asked me this:

So with the AutoMoqCustomization I feel like I should get Mocks with concrete types too (except the sut) - why am I wrong?

AutoFixture’s extention for auto-mocking with Moq was never meant as a general modification of behavior. Customizations extend the behavior of AutoFixture; they don’t change it. There’s a subtle difference. In any case, the auto-mocking customization was always meant as a fallback mechanism that would create Mocks for interfaces and abstract types because AutoFixture doesn’t know how to deal with those.

Apparently @ZeroBugBounce also want concrete classes to be issued as Mock instances, which is not quite the same thing; AutoFixture already has a strategy for that (it’s called ConstructorInvoker).

Nevertheless I decided to spike a little on this to see if I could get it working. It turns out I needed to open some of the auto-mocking classes a bit for extensibility (always a good thing), so the following doesn’t work with AutoFixture 2.0 beta 1, but will probably work with the RTW. Also please not that I’m reporting on a spike; I haven’t thoroughly tested all edge cases.

That said, the first thing we need to do is to remove AutoFixture’s default ConstructorInvoker that invokes the constructor of concrete classes. This is possible with this constructor overload:

public Fixture(DefaultRelays engineParts)

This takes as input a DefaultRelays instance, which is more or less just an IEnumerable<ISpecimenBuilder> (the basic building block of AutoFixture). We need to replace that with a filter that removes the ConstructorInvoker. Here’s a derived class that does that:

public class FilteringRelays : DefaultEngineParts

{

    private readonly Func<ISpecimenBuilder, bool> spec;

    public FilteringRelays(Func<ISpecimenBuilder, bool> specification)

    {

        if (specification == null)

        {

            throw new ArgumentNullException("specification");

        }

        this.spec = specification;

    }

    public override IEnumerator<ISpecimenBuilder> GetEnumerator()

    {

        var enumerator = base.GetEnumerator();

        while (enumerator.MoveNext())

        {

            if (this.spec(enumerator.Current))

            {

                yield return enumerator.Current;

            }

        }

    }

}

DefaultEngineParts already derive from DefaultRelays, so this enables us to use the overloaded constructor to remove the ConstructorInvoker by using these filtered relays:

Func<ISpecimenBuilder, bool> concreteFilter

    = sb => !(sb is ConstructorInvoker);

var relays = new FilteringRelays(concreteFilter);

The second thing we need to do is to tell the AutoMoqCustomization that it should Mock all types, not just interfaces and abstract classes. With the new (not in beta 1) overload of the constructor, we can now supply a Specification that determines which types should be mocked.:

Func<Type, bool> mockSpec = t => true;

We can now create the Fixture like this to get auto-mocking of all types:

var fixture = new Fixture(relays).Customize(

    new AutoMoqCustomization(new MockRelay(mockSpec)));

With this Fixture instance, we can now create concrete classes that are mocked. Here’s the full test that proves it:

[Fact]

public void CreateAnonymousMockOfConcreteType()

{

    // Fixture setup

    Func<ISpecimenBuilder, bool> concreteFilter

        = sb => !(sb is ConstructorInvoker);

    var relays = new FilteringRelays(concreteFilter);

    Func<Type, bool> mockSpec = t => true;

    var fixture = new Fixture(relays).Customize(

        new AutoMoqCustomization(new MockRelay(mockSpec)));

    // Exercise system

    var foo = fixture.CreateAnonymous<Foo>();

    foo.DoIt();

    // Verify outcome

    var fooTD = Mock.Get(foo);

    fooTD.Verify(f => f.DoIt());

    // Teardown

}

Foo is this concrete class:

public class Foo

{

    public virtual void DoIt()

    {

    }

}

Finally, a word of caution: this is a spike. It’s not fully tested and is bound to fail in certain cases: at least one case is when the type to be created is sealed. Since Moq can’t create a Mock of a sealed type, the above code will fail in that case. However, we can address this issue with some more sophisticated filters and Specifications. However, I will leave that up to the interested reader (or a later blog post).

All in all I think this provides an excellent glimpse of the degree of extensibility that is built into AutoFixture 2.0’s kernel.

The new internal architecture of AutoFixture 2.0 enables some interesting features. One of these is that it becomes easy to extend AutoFixture to become an auto-mocking container.

Since I personally use Moq, the AutoFixture 2.0 .zip file includes a new assembly called Ploeh.AutoFixture.AutoMoq that includes an auto-mocking extension that uses Moq for Test Doubles.

Please note that AutoFixture in itself has no dependency on Moq. If you don’t want to use Moq, you can just ignore the Ploeh.AutoFixture.AutoMoq assembly.

Auto-mocking with AutoFixture does not have to use Moq. Although it only ships with Moq support, it is possible to write an auto-mocking extension for a different dynamic mock library.

To use it, you must first add a reference to Ploeh.AutoFixture.AutoMoq. You can now create your Fixture instance like this:

var fixture = new Fixture()

    .Customize(new AutoMoqCustomization());

What this does is that it adds a fallback mechanism to the fixture. If a type falls through the normal engine without being handled, the auto-mocking extension will check whether it is a request for an interface or abstract class. If this is so, it will relay the request to a request for a Mock of the same type.

A different part of the extension handles requests for Mocks, which ensures that the Mock will be created and returned.

Splitting up auto-mocking into a relay and a creational strategy for Mock objects proper also means that we can directly request a Mock if we would like that. Even better, we can use the built-in Freeze support to freeze a Mock, and it will also automatically freeze the auto-mocked instance as well (because the relay will ask for a Mock that turns out to be frozen).

Returning to the original frozen pizza example, we can now rewrite it like this:

[Fact]

public void AddWillPipeMapCorrectly()

{

    // Fixture setup

    var fixture = new Fixture()

        .Customize(new AutoMoqCustomization());

    var basket = fixture.Freeze<Basket>();

    var mapMock = fixture.Freeze<Mock<IPizzaMap>>();

    var pizza = fixture.CreateAnonymous<PizzaPresenter>();

    var sut = fixture.CreateAnonymous<BasketPresenter>();

    // Exercise system

    sut.Add(pizza);

    // Verify outcome

    mapMock.Verify(m => m.Pipe(pizza, basket.Add));

    // Teardown

}

Notice that we can simply freeze Mock<IPizzaMap> which also automatically freeze the IPizzaMap instance as well. When we later create the SUT by requesting an anonymous BasketPresenter, IPizzaMap is already frozen in the fixture, so the correct instance will be injected into the SUT.

This is similar to the behavior of the custom FreezeMoq extension method I previously described, but now this feature is baked in.

It gives me great pleasure to announce that AutoFixture 2.0 beta 1 is now available for download. Compared to version 1.1 AutoFixture 2.0 is implemented using a new and much more open and extensible engine that enables many interesting scenarios.

Despite the new engine and the vastly increased potential, the focus on version 2.0 has been to ensure that the current, known feature set was preserved.

What’s new?

While AutoFixture 2.0 introduces new features, this release is first and foremost an upgrade to a completely new internal architecture, so the number of new releases is limited. Never the less, the following new features are available in version 2.0:

• Support for enums
• Full support of arrays
• Optional tracing
• Improved extensibility
• Optional auto-mocking with Moq (implemented as a separate, optional assembly)
• Optional extensions for xUnit.net (implemented as a separate, optional assembly)

There are still open feature requests for AutoFixture, so now that the new engine is in place I can again focus on implementing some of the features that were too difficult to address with the old engine.

Breaking changes

Version 2.0 introduces some breaking changes, although the fundamental API remains recognizable.

• A lot of the original methods on Fixture are now extension methods on IFixture (a new interface). The methods include CreateAnonymous<T>, CreateMany<T> and many others, so you will need to include a using directive for Ploeh.AutoFixture to compile the unit test code.
• CreateMany<T> still returns IEnumerable<T>, but the return value is much more consistently deferred. This means that in almost all cases you should instantly stabilize the sequence by converting it to a List<T>, an array or similar.
• Several methods are now deprecated in favor of new methods with better names.

A few methods were also removed, but only those that were already deprecated in version 1.1.

Roadmap

The general availability of beta 1 of AutoFixture 2.0 marks the beginning of a trial period. If no new issues are reported within the next few weeks, a final version 2.0 will be released. If too many issues are reported, a new beta version may be necessary.

Please report any issues you find.

After the release of the final version 2.0 my plan is currently to focus on the Idioms project, although there are many other new features that might warrant my attention.

Blog posts about the new features will also follow soon.

The last time I presented a sample of an AutoFixture-based unit test, I purposely glossed over the state-based verification that asserted that the resulting state of the basket variable was that the appropriate Pizza was added:

Assert.IsTrue(basket.Pizze.Any(p =>

    p.Name == pizza.Name), "Basket has added pizza.");

The main issue with this assertion is that the implied equality expression is rather weak: we consider a PizzaPresenter instance to be equal to a Pizza instance if their Name properties match.

What if they have other properties (like Size) that don’t match? If this is the case, the test would be a false negative. A match would be found in the Pizze collection, but the instances would not truly represent the same pizza.

How do we resolve this conundrum without introducing equality pollution? AutoFixture offers one option in the form of the generic Likeness<TSource, TDestination> class. This class offers convention-based test-specific equality mapping from TSource to TDestination and overriding the Equals method.

One of the ways we can use it is by a convenience extension method. This unit test is a refactoring of the test from the previous post, but now using Likeness:

[TestMethod]

public void AddWillAddToBasket_Likeness()

{

    // Fixture setup

    var fixture = new Fixture();

    fixture.Register<IPizzaMap, PizzaMap>();

    var basket = fixture.Freeze<Basket>();

    var pizza = fixture.CreateAnonymous<PizzaPresenter>();

    var expectedPizza = 

        pizza.AsSource().OfLikeness<Pizza>();

    var sut = fixture.CreateAnonymous<BasketPresenter>();

    // Exercise system

    sut.Add(pizza);

    // Verify outcome

    Assert.IsTrue(basket.Pizze.Any(expectedPizza.Equals));

    // Teardown

}

Notice how the Likeness instance is created with the AsSource() extension method. The pizza instance (of type PizzaPresenter) is the source of the Likeness, whereas the Pizza domain model type is the destination. The expectedPizza instance is of type Likeness<PizzaPresenter, Pizza>.

The Likeness class overrides Equals with a convention-based comparison: if two properties have the same name and type, they are equal if their values are equal. All public properties on the destination must have equal properties on the source.

This allows me to specify the Equals method as the predicate for the Any method in the assertion:

Assert.IsTrue(basket.Pizze.Any(expectedPizza.Equals));

When the Any method evalues the Pizze collection, it executes the Equals method on Likeness, resulting in a convention-based comparison of all public properties and fields on the two instances.

It’s possible to customize the comparison to override the behavior for certain properties, but I will leave that to later posts. This post only scratches the surface of what Likeness can do.

To use Likeness, you must add a reference to the Ploeh.SemanticComparison assembly. You can create a new instance using the public constructor, but to use the AsSource extension method, you will need to add a using directive:

using Ploeh.SemanticComparison.Fluent;

AutoFixture 1.1 is now available on the CodePlex site! Compared to the Release Candidate, there are no changes.

The 1.1 release page has more details about this particular release, but essentially this is the RC promoted to release status.

Release 1.1 is an interim release that addresses a few issues that appeared since the release of version 1.0. Work continues on AutoFixture 2.0 in parallel.

In my previous posts I demonstrated interaction-based unit tests that verify that a pizza is correctly being added to a shopping basket. An alternative is a state-based test where we examine the contents of the shopping basket after exercising the SUT. Here’s an initial attempt:

[TestMethod]

public void AddWillAddToBasket()

{

    // Fixture setup

    var fixture = new Fixture();

    fixture.Register<IPizzaMap>(

        fixture.CreateAnonymous<PizzaMap>);

    var basket = fixture.Freeze<Basket>();

    var pizza = fixture.CreateAnonymous<PizzaPresenter>();

    var sut = fixture.CreateAnonymous<BasketPresenter>();

    // Exercise system

    sut.Add(pizza);

    // Verify outcome

    Assert.IsTrue(basket.Pizze.Any(p => 

        p.Name == pizza.Name), "Basket has added pizza.");

    // Teardown

}

In this case the assertion examines the Pizze collection (you did know that the plural of pizza is pizze, right?) of the frozen Basket to verify that it contains the added pizza.

The tricky part is that the Pizze property is a collection of Pizza instances, and not PizzaPresenter instances. The injected IPizzaMap instance is responsible for mapping from PizzaPresenter to Pizza, but since we are rewriting this as a state-based test, I thought it would also be interesting to write the test without using Moq. Instead, we can use the real implementation of IPizzaMap, but this means that we must instruct AutoFixture to map from the abstract IPizzaMap to the concrete PizzaMap.

We see that happening in this line of code:

fixture.Register<IPizzaMap>(

    fixture.CreateAnonymous<PizzaMap>);

Notice the method group syntax: we pass in a delegate to the CreateAnonymous method, which means that every time the fixture is asked to create an IPizzaMap instance, it invokes CreateAnonymous<PIzzaMap>() and uses the result.

This is, obviously, a general-purpose way in which we can map compatible types, so we can write an extension method like this one:

public static void Register<TAbstract, TConcrete>(

    this Fixture fixture) where TConcrete : TAbstract

{

    fixture.Register<TAbstract>(() =>

        fixture.CreateAnonymous<TConcrete>());

}

(I’m slightly undecided on the name of this method. Map might be a better name, but I just like the equivalence to some common DI Containers and their Register methods.) Armed with this Register overload, we can now rewrite the previous Register statement like this:

fixture.Register<IPizzaMap, PizzaMap>();

It’s the same amount of code lines, but I find it slightly more succinct and communicative.

The real point of this blog post, however, is that you can map abstract types to concrete types, and that you can always write extension methods to encapsulate your own AutoFixture idioms.

AutoFixture 1.1 Release Candidate 1 is now available on the CodePlex site.

Users are encouraged to evaluate this RC and submit feedback. If no bugs or issues are reported within the next week, we will promote RC1 to version 1.1.

The release page has more details about this particular release.

My previous post about AutoFixture’s Freeze functionality included this little piece of code that I didn’t discuss:

var mapMock = new Mock<IPizzaMap>();

fixture.Register(mapMock.Object);

In case you were wondering, this is Moq interacting with AutoFixture. Here we create a new Test Double and register it with the fixture. This is very similar to AutoFixture’s built-in Freeze functionality, with the difference that we register an IPizzaMap instance, which isn’t the same as the Mock<IPizzaMap> instance.

It would be nice if we could simply freeze a Test Double emitted by Moq, but unfortunately we can’t directly use the Freeze method, since Freeze<Mock<IPizzaMap>>() would freeze a Mock<IPizzaMap>, but not IPizzaMap itself. On the other hand, Freeze<IPizzaMap>() wouldn’t work because we haven’t told the fixture how to create IPizzaMap instances, but even if we had, we wouldn’t have a Mock<IPizzaMap> against which we could call Verify.

On the other hand, it’s trivial to write an extension method to Fixture:

public static Mock<T> FreezeMoq<T>(this Fixture fixture)

    where T : class

{

    var td = new Mock<T>();

    fixture.Register(td.Object);

    return td;

}

I chose to call the method FreezeMoq to indicate its affinity with Moq.

We can now rewrite the unit test from the previous post like this:

[TestMethod]

public void AddWillPipeMapCorrectly_FreezeMoq()

{

    // Fixture setup

    var fixture = new Fixture();

    var basket = fixture.Freeze<Basket>();

    var mapMock = fixture.FreezeMoq<IPizzaMap>();

    var pizza = fixture.CreateAnonymous<PizzaPresenter>();

    var sut = fixture.CreateAnonymous<BasketPresenter>();

    // Exercise system

    sut.Add(pizza);

    // Verify outcome

    mapMock.Verify(m => m.Pipe(pizza, basket.Add));

    // Teardown

}

You may think that saving only a single line of code may not be that big a deal, but if you also need to perform Setups on the Mock, or if you have several different Mocks to configure, you may appreciate the encapsulation. I know I sure do.

In my previous blog post, I introduced AutoFixture’s Freeze feature, but the example didn’t fully demonstrate the power of the concept. In this blog post, we will turn up the heat on the frozen pizza a notch.

The following unit test exercises the BasketPresenter class, which is simply a wrapper around a Basket instance (we’re doing a pizza online shop, if you were wondering). In true TDD style, I’ll start with the unit test, but I’ll post the BasketPresenter class later for reference.

[TestMethod]

public void AddWillPipeMapCorrectly()

{

    // Fixture setup

    var fixture = new Fixture();

    var basket = fixture.Freeze<Basket>();

    var mapMock = new Mock<IPizzaMap>();

    fixture.Register(mapMock.Object);

    var pizza = fixture.CreateAnonymous<PizzaPresenter>();

    var sut = fixture.CreateAnonymous<BasketPresenter>();

    // Exercise system

    sut.Add(pizza);

    // Verify outcome

    mapMock.Verify(m => m.Pipe(pizza, basket.Add));

    // Teardown

}

The interesting thing in the above unit test is that we Freeze a Basket instance in the fixture. We do this because we know that the BasketPresenter somehow wraps a Basket instance, but we trust the Fixture class to figure it out for us. By telling the fixture instance to Freeze the Basket we know that it will reuse the same Basket instance throughout the entire test case. That includes the call to CreateAnonymous<BasketPresenter>.

This means that we can use the frozen basket instance in the Verify call because we know that the same instance will have been reused by the fixture, and thus wrapped by the SUT.

When you stop to think about this on a more theoretical level, it fortunately makes a lot of sense. AutoFixture’s terminology is based upon the excellent book xUnit Test Patterns, and a Fixture instance pretty much corresponds to the concept of a Fixture. This means that freezing an instance simply means that a particular instance is constant throughout that particular fixture. Every time we ask for an instance of that class, we get back the same frozen instance.

In DI Container terminology, we just changed the Basket type’s lifetime behavior from Transient to Singleton.

For reference, here’s the BasketPresenter class we’re testing:

public class BasketPresenter

{

    private readonly Basket basket;

    private readonly IPizzaMap map;

    public BasketPresenter(Basket basket, IPizzaMap map)

    {

        if (basket == null)

        {

            throw new ArgumentNullException("basket");

        }

        if (map == null)

        {

            throw new ArgumentNullException("map");

        }

        this.basket = basket;

        this.map = map;

    }

    public void Add(PizzaPresenter presenter)

    {

        this.map.Pipe(presenter, this.basket.Add);

    }

}

If you are wondering about why this is interesting at all, and why we don’t just pass in a Basket through the BasketPresenter’s constructor, it’s because we are using AutoFixture as a SUT Factory. We want to be able to refactor BasketPresenter (and in this case particularly its constructor) without breaking a lot of existing tests. The level of indirection provided by AutoFixture gives us just that ability because we never directly invoke the constructor.

Coming up: more fun with the Freeze concept!

One of the important points of AutoFixture is to hide away all the boring details that you don’t care about when you are writing a unit test, but that the compiler seems to insist upon. One of these details is how you create a new instance of your SUT.

Every time you create an instance of your SUT using its constructor, you make it more difficult to refactor that constructor. This is particularly true when it comes to Constructor Injection because you often need to define a Test Double in each unit test, but even for primitive types, it’s more maintenance-friendly to use a SUT Factory.

AutoFixture is a SUT Factory, so we can use it to create instances of our SUTs. However, how do we correlate constructor parameters with variables in the test when we will not use the constructor directly?

This is where the Freeze method comes in handy, but let’s first examine how to do it with the core API methods CreateAnonymous and Register.

Imagine that we want to write a unit test for a Pizza class that takes a name in its constructor and exposes that name as a property. We can write this test like this:

[TestMethod]

public void NameIsCorrect()

{

    // Fixture setup

    var fixture = new Fixture();

    var expectedName = fixture.CreateAnonymous("Name");

    fixture.Register(expectedName);

    var sut = fixture.CreateAnonymous<Pizza>();

    // Exercise system

    string result = sut.Name;

    // Verify outcome

    Assert.AreEqual(expectedName, result, "Name");

    // Teardown

}

The important lines are these two:

var expectedName = fixture.CreateAnonymous("Name");

fixture.Register(expectedName);

What’s going on here is that we create a new string, and then we subsequently Register this string so that every time the fixture instance is asked to create a string, it will return this particular string. This also means that when we ask AutoFixture to create an instance of Pizza, it will use that string as the constructor parameter.

It turned out that we used this coding idiom so much that we decided to encapsulate it in a convenience method. After some debate we arrived at the name Freeze, because we essentially freeze a single anonymous variable in the fixture, bypassing the default algorithm for creating new instances. Incidentally, this is one of very few methods in AutoFixture that breaks CQS, but although that bugs me a little, the Freeze concept has turned out to be so powerful that I live with it.

Here is the same test rewritten to use the Freeze method:

[TestMethod]

public void NameIsCorrect_Freeze()

{

    // Fixture setup

    var fixture = new Fixture();

    var expectedName = fixture.Freeze("Name");

    var sut = fixture.CreateAnonymous<Pizza>();

    // Exercise system

    string result = sut.Name;

    // Verify outcome

    Assert.AreEqual(expectedName, result, "Name");

    // Teardown

}

In this example, we only save a single line of code, but apart from that, the test also becomes a little more communicative because it explicitly calls out that this particular string is frozen.

However, this is still a pretty lame example, but while I intend to follow up with a more complex example, I wanted to introduce the concept gently.

For completeness sake, here’s the Pizza class:

public class Pizza

{

    private readonly string name;

    public Pizza(string name)

    {

        if (name == null)

        {

            throw new ArgumentNullException("name");

        }

        this.name = name;

    }

    public string Name

    {

        get { return this.name; }

    }

}

As you can see, the test simply verifies that the constructor parameter is echoed by the Name property, and the Freeze method makes this more explicit while we still enjoy the indirection of not invoking the constructor directly.

AutoFixture 1.0 is now available on the CodePlex site! Compared to Release Candidate 2 there are no changes.

The 1.0 release page has more details about this particular release, but essentially this is RC2 promoted to release status.

It's been almost a year since I started development on AutoFixture and I must say that it has been an exciting and fulfilling experience! The API has evolved, but has turned out to be surprisingly flexible, yet robust. I even had some positive surprises along the way as it dawned on me that I could do new fancy things I hadn't originally considered.

If you use the Likeness feature (of which I have yet to write), you will run into this bug in Visual Studio. The bug is only in IntelliSense, so any code using Likeness will compile and work just fine.

While this release marks the end of AutoFixture's initial days, it also marks the beginning of AutoFixture 2.0. I already have lots of plans for making it even more extensible and powerful, as well as plans for utility libraries that integrate with, say, Moq or Rhino Mocks. It's going to be an exciting new voyage!

AutoFixture 1.0 Release Candidate 2 is now available on the CodePlex site! Compared to Release Candidate 1 there are very few changes, but the test period uncovered the need for a few extra methods on a recent addition to the library. RC2 contains these additional methods.

This resets the clock for the Release Candidate trial period. Key users have a chance to veto this release until a week from now. If no-one complains within that period, we will promote RC2 to version 1.0.

The RC2 release page has more details about this particular release.

AutoFixture 1.0 Release Candidate 1 is now available on the CodePlex site! AutoFixture is now almost ten months old and has seen extensive use internally in Safewhere during most of this time. It has proven to be very stable, expressive and generally a delight to use.

If all goes well, the Release Candidate period will be short. Key users have a chance to veto the this version, but if no-one complains within a week from now, we will promote RC1 to version 1.0.

The RC1 release page has more detail about this particular release.

In a previous post I described how AutoFixture's Do method can let you invoke commands on your SUT with Dummy values for the parameters you don't care about.

The Get method is the equivalent method you can use when the member you are invoking returns a value. In other words: if you want to call a method on your SUT to get a value, but you don't want the hassle of coming up with values you don't care about, you can let the Get method supply those values for you.

In today's example I will demonstrate a unit test that verifies the behavior of a custom ASP.NET MVC ModelBinder. If you don't know anything about ASP.NET MVC it doesn't really matter. The point is that a ModelBinder must implement the IModelBinder interface that defines a single method:

In many cases we don't care about one or the other of these parameters, but we still need to supply them when unit testing.

The example is a bit more complex than some of my other sample code, but once in a while I like to provide you with slightly more realistic AutoFixture examples. Still, it's only 10 lines of code, but it looks like a lot more because I have wrapped several of the lines so that the code is still readable on small screens.

The first part simply creates the Fixture object and customizes it to disable AutoProperties for all ControllerContext instances (otherwise we would have to set up a lot of Test Doubles for such properties as HttpContext, RequestContext etc.).

The next part of the test sets up a ModelBindingContext instance that will be used to exercise the SUT. In this test case, the bindingContext parameter of the BindModel method is important, so I explicitly set that up. On the other hand, I don't care about the controllerContext parameter in this test case, so I ask the Get method to take care of that for me:

The Get method creates a Dummy value for the ControllerContext, whereas I can still use the outer variable bindingContext to call the BindModel method. The return value of the BindModel method is returned to the result variable by the Get method.

Like the Do methods, the Get methods are generic methods. The one invoked in this example has this signature:

There are also overloads that works with the versions of the Func delegate that takes two, three and four parameters.

As the Do methods, the Get methods are convenience methods that let you concentrate on writing the test code you care about while it takes care of all the rest. You could have written a slightly more complex version that didn't use Get but instead used the CreateAnonymous method to create an Anonymous Variable for the ControllerContext, but this way is slightly more succinct.

A reader asked me how AutoFixture can deal with arrays as fields on a class. More specifically, given a class like MyClassA, how can AutoFixture assign a proper array with initialized values to Items?

public class MyClassA

{

    public MyClassB[] Items;

    public MyClassC C;

    public MyClassD D;

}

Ignoring the bad practice of publicly exposing fields, the main problem is that AutoFixture has no inherent understanding of arrays, so if we try to create a new instance of MyClassA by invoking the CreateAnonymous method, we would end up with Items being an array of nulls.

Obviously we want a populated array instead. There are at least a couple of ways to reach this goal.

The simplest is just to create it and modify it afterwards:

var mc = fixture.CreateAnonymous<MyClassA>();

mc.Items = fixture.CreateMany<MyClassB>().ToArray();

Although the CreateAnomymous method will assign an unitialized array, we immediately overwrite the value with an initialized array. The CreateMany method returns an IEnumerable<MyClassB> on which we can use the ToArray extension method to create an array.

The next option is to do almost the same thing, but as a single operation:

var mc = fixture.Build<MyClassA>()

    .With(x => x.Items, 

        fixture.CreateMany<MyClassB>().ToArray())

    .CreateAnonymous();

Besides the different syntax and the lower semicolon count, the biggest difference is that in this case the Items field is never assigned an unitialized array because the With method ensures that the specified value is assigned immediately.

If you get tired of writing this Builder sequence every time you want to create a new MyClassA instance, you can Customize the Fixture:

fixture.Customize<MyClassA>(ob =>

    ob.With(x => x.Items, 

        fixture.CreateMany<MyClassB>().ToArray()));

With this customization, every time we invoke

var mc = fixture.CreateAnonymous<MyClassA>();

we will get an instance of MyClassA with a properly initialized Items array.

I hope you find one or more of these methods useful.

In unit testing an important step is to exercise the SUT. The member you want to invoke is often a method that takes one or more parameters, but in some test cases you don't care about the values of those parameters – you just want to invoke the method.

You can always make up one or more Dummy parameters and pass them to the method in question, but you could also use one of AutoFixture's Do convenience methods. There are several overloads that all take delegates that specify the action in question while providing you with Dummies of any parameters you don't care about.

A good example is WPF's ICommand interface. The most prevalent method is the Execute method that takes a single parameter parameter:

Most of the time we don't really care about the parameter because we only care that the command was invoked. However, we still need to supply a value for the parameter when we unit test our ICommand implementations. Obviously, we could just pass in a new System.Object every time, but why not let AutoFixture take care of that for us?

(You may think that new'ing up a System.Object is something you can easily do yourself, but imagine other APIs that require much more complex input parameters, and you should begin to see the potential.)

Here's a state-based unit test that verifies that the Message property of the MyViewModel class has the correct value after the FooCommand has been invoked:

Notice how the Do method takes an Action<object> to specify the method to invoke. AutoFixture automatically supplies an instance for the parameter parameter using the same engine to create Anonymous variables that it uses for everything else.

The Do method in question is really a generic method with this signature:

There are also overloads that take two, three or four input parameters, corresponding to the available Action types available in the BCL.

These methods are simply convenience methods that allow you to express your test code more succinctly than you would otherwise have been able to do.

The following feature suggestion was recently posted in the AutoFixture Issue Tracker board:

"We're using AutoFixture to create random rows of data in our DB. A lot of times though, it creates strings that are too long for the database columns. It would be nice if the .With<string> method had an overload that took in a min/max length. We want the random data, but capped at a limit.

"fixture.Build<MyObject>.With(x = x.MyString, 0, 100);

"As an aside, this is for a project that uses Nhibernate and Fluent Nhibernate, which has these lengths already defined. I would be nice if AutoFixture could automatically pick up on that somehow."

I think such an feature is an excellent idea, but I don't think I will include in AutoFixture. Why not?

So far, I have kept the AutoFixture API pretty clean and very generic, and it is my belief that this is one of the main reasons it is so expressive and flexible. There are no methods that only work on specific types (such as strings), and I am reluctant to introduce them now.

In the last six months, I have identified a lot of specialized usage idioms that I would love to package into a reusable library, but I think that they will pollute the core AutoFixture API, so I'm going to put those in one or more optional 'add-on' libraries.

The ability to define strings that are constrained on length could be one such feature, but rather than wait for a helper library, I will show you have you can implement such a method yourself.

The first thing we need is a method that can create anonymous strings given length constraints. One possible implementation is this ConstrainedStringGenerator class:

public class ConstrainedStringGenerator

{

    private readonly int minimumLength;

    private readonly int maximumLength;

    public ConstrainedStringGenerator(int minimumLength, 

        int maximumLength)

    {

        if (maximumLength < 0)

        {

            throw new ArgumentOutOfRangeException("...");

        }

        if (minimumLength > maximumLength)

        {

            throw new ArgumentOutOfRangeException("...");

        }

        this.minimumLength = minimumLength;

        this.maximumLength = maximumLength;

    }

    public string CreateaAnonymous(string seed)

    {

        var s = string.Empty;

        while (s.Length < this.minimumLength)

        {

            s += GuidStringGenerator.CreateAnonymous(seed);

        }

        if (s.Length > this.maximumLength)

        {

            s = s.Substring(0, this.maximumLength);

        }

        return s;

    }

}

The CreateAnonymous method uses AutoFixture's GuidStringGenerator class to create anonymous strings of the required length. For this implementation I chose a basic algorithm, but I'm sure you can create one that is more sophisticated if you need it.

Th next thing we need to do is to implement the desired With method. That can be done with an extension method works on ObjectBuilder<T>:

public static class ObjectBuilderExtension

{

    public static ObjectBuilder<T> With<T>(

        this ObjectBuilder<T> ob,

        Expression<Func<T, string>> propertyPicker,

        int minimumLength,

        int maximumLength)

    {

        var me = (MemberExpression)propertyPicker.Body;

        var name = me.Member.Name;

        var generator =

            new ConstrainedStringGenerator(

                minimumLength, maximumLength);

        var value = generator.CreateaAnonymous(name);

        return ob.With(propertyPicker, value);

    }

}

The method takes the same input as ObjectBuilder<T>'s With method, plus the two integers that constrain the length. Note that the propertyPicker expression has been constrained to deal only with strings.

In this implementation, we use the ConstrainedStringGenerator class to generate the desired value for the property, where after we can use the existing With method to assign the value to the property in question.

This now allows us to write Build statements like the one originally requested:

var mc = fixture.Build<MyClass>()

    .With(x => x.SomeText, 0, 100)

    .CreateAnonymous();

The other part of the request, regarding NHibernate integration, I will leave to the interested reader – mostly because I have never used NHibernate, so I have no clue how to do it. I would, however, love to see a blog post with that addition.

This entire example is now part of the AutoFixture test suite, so if you are interested in looking at it in more detail, you can get it from the AutoFixture source code (available at CodePlex).

AutoFixture beta 1 is now available on the CodePlex site! We have been using AutoFixture quite intensively in Safewhere for almost half a year now, and the core of it has turned out to be stable and much more powerful than I originally imagined.

During that period, I have discovered and fixed a few bugs, but the most positive experience has been how extended usage has inspired us to come up with numerous ideas to new cool features. Some of these features are already implemented in the current release, and the rest are listed on the AutoFixture site.

The beta 1 release page has more details about this particular release.

A few months ago I described how you can use AutoFixture's With method to assign property values as part of building up an anonymous variable. In that scenario, the With method is used to explicitly assign a particular, pre-defined value to a property.

There's another overload of the With method that doesn't take an explicit value, but rather uses AutoFixture to create an anonymous value for the property. So what's the deal with that if AutoFixture's default behavior is to assign anonymous values to all writable properties?

In short it's an opt-in mechanism that only makes sense if you decide to opt out of the AutoProperties features.

As always, let's look at an example. This time, I've decided to show you a slightly more realistic example so that you can get an idea of how AutoFixture can be used to aid in unit testing. This also means that the example is going to be a little more complex than usual, but it's still simple.

Imagine that we wish to test that an ASP.NET MVC Controller Action returns the correct result. More specifically, we wish to test that the Profile method on MyController returns a ViewResult with the correct Model (the current user's name, to make things interesing).

Here's the entire test. It may look more complicated than it is – it's really only 10 lines of code, but I had to break them up to prevent unpleasant wrapping if your screen is narrow.

[TestMethod]

public void ProfileWillReturnResultWithCorrectUserName()

{

    // Fixture setup

    var fixture = new Fixture();

    fixture.Customize<ControllerContext>(ob => ob

        .OmitAutoProperties()

        .With(cc => cc.HttpContext));

    var expectedUserName = 

        fixture.CreateAnonymous("UserName");

    var httpCtxStub = new Mock<HttpContextBase>();

    httpCtxStub.SetupGet(x => x.User).Returns(

        new GenericPrincipal(

            new GenericIdentity(expectedUserName), null));

    fixture.Register(httpCtxStub.Object);

    var sut = fixture.Build<MyController>()

        .OmitAutoProperties()

        .With(c => c.ControllerContext)

        .CreateAnonymous();

    // Exercise system

    ViewResult result = sut.Profile();

    // Verify outcome

    var actual = result.ViewData.Model;

    Assert.AreEqual(expectedUserName, actual, "User");

    // Teardown

}

Apart from AutoFixture, I'm also making use of Moq to stub out HttpContextBase.

You can see the Anonymous With method in two different places: in the call to Customize and when the SUT is being built. In both cases you can see that the call to With follows a call to OmitAutoProperties. In other words: we are telling AutoFixture that we don't want any of the writable properties to be assigned a value except the one we identify.

Let me highlight some parts of the test.

fixture.Customize<ControllerContext>(ob => ob

    .OmitAutoProperties()

    .With(cc => cc.HttpContext));

This line of code instructs AutoFixture to always create a ControllerContext in a particular way: I don't want to use AutoProperties here, because ControllerContext has a lot of writable properties of abstract types, and that would require me to set up a lot of Test Doubles if I had to assign values to all of those. It's much easier to simply opt out of this mechanism. However, I would like to have the HttpContext property assigned, but I don't care about the value in this statement, so the With method simply states that AutoFixture should assign a value according to whatever rule it has for creating instances of HttpContextBase.

I can now set up a Stub that populates the User property of HttpContextBase:

var httpCtxStub = new Mock<HttpContextBase>();

httpCtxStub.SetupGet(x => x.User).Returns(

    new GenericPrincipal(

        new GenericIdentity(expectedUserName), null));

fixture.Register(httpCtxStub.Object);

This is registered with the fixture instance which closes the loop to the previous customization.

I can now create an instance of my SUT. Once more, I don't want to have to set up a lot of irrelevant properties on MyController, so I opt out of AutoProperties and then explicitly opt in on the ControllerContext. This will cause AutoFixture to automatically populate the ControllerContext with the HttpContext Stub:

var sut = fixture.Build<MyController>()

    .OmitAutoProperties()

    .With(c => c.ControllerContext)

    .CreateAnonymous();

For completeness' sake, here's the MyController class that I am testing:

public class MyController : Controller

{

    public ViewResult Profile()

    {

        object userName = this.User.Identity.Name;

        return this.View(userName);

    }

}

This test may seem complex, but it really accomplishes a lot in only 10 lines of code, considering that ASP.NET MVC Controllers with a working HttpContext are not particularly trivial to set up.

In summary, this With method overload lets you opt in on one or more explicitly identified properties when you have otherwise decided to omit AutoProperties. As all the other Builder methods, this method can also be chained.

In the previous post on AutoFixture, I demonstrated how it's possible to use a customized Builder to perform complex initialization when requesting an instance of a particular type. To recap, this was the solution I described:

var mc = fixture.CreateAnonymous<MyClass>();

var mvm = fixture.Build<MyViewModel>()

    .Do(x => x.AvailableItems.Add(mc))

    .With(x => x.SelectedItem, mc)

    .CreateAnonymous();

This code first creates an anonymous instance of MyClass that can be added to MyViewModel. It then initializes a Builder for a specific instance of MyViewModel, instructing it to

1. add the anonymous MyClass instance to the list of AvailableItems
2. assign the same instance to the SelectedItem property

While this works splendidly, it can get tiresome to write the same customization over and over again if you need to create multiple instances of the same type. It also violate the DRY principle.

When this is the case, you can alternatively register a customized Builder pipeline for the type in question (in this case MyViewModel). This is done with the Customize method:

var mc = fixture.CreateAnonymous<MyClass>();

fixture.Customize<MyViewModel>(ob => ob

    .Do(x => x.AvailableItems.Add(mc))

    .With(x => x.SelectedItem, mc));

The Customize method takes as input a function that provides an initial ObjectBuilder as input, and returns a new, customized ObjectBuilder as output. This function is registered with the type, so that each time an anonymous instance of the type is requested, the customized ObjectBuilder will be used to create the instance.

In the example, I customize the supplied ObjectBuilder (ob) in exactly the same way as before, but instead of invoking CreateAnonymous, I simply return the customized ObjectBuilder to the Fixture instance. It then saves this customized ObjectBuilder for later use.

With this customization, what before failed now succeeds:

var mvm = fixture.CreateAnonymous<MyViewModel>();

The Customize method is the core method for customizing AutoFixture. Most other customization methods (like Register) are simply convenience methods that wraps Customize. It is a very powerful method that can be used to define some very specific Builder algorithms for particular types.

Yesterday I released version .8.6 of AutoFixture. It is a minor release that simply adds some new features.

There are some minor breaking changes (documented on the release page), but they only affect supporting classes and don't touch on any of the code examples I have so far published. In other words, if you are using AutoFixture's fluent interface, your code should still compile.

Please go ahead and download it and use it. As always, comments and questions are welcome, either here or in the forum.

It gives me great pleasure to announce that I have just release version .8.5 of AutoFixture. It is a minor release (hence the numbering) that mainly contains a lot of convenience overloads to already existing methods. There is also a single bug fix.

There are two breaking changes (documented on the release page), but they are minor and I do not expect them to cause problems. Only one of these even remotely affects any part of the API I have already discussed here, and that relates to what kind of exception is being thrown when AutoFixture is unable to create an instance of the requested type.

Please go ahead and download it and use it heavily :) As always, comments and questions are welcome.

Soon after I posted my post on the AutoFixture Custom Builder's Do method, a much better example occurred to me, so let's revisit this feature in light of a more reasonable context.

When I write WPF code, I always use the MVVM pattern. When I need to create a Master/Detail View, I usually model it so that my View Model has a list of available items, and a property that returns the currently selected item. In this way, I can bind the current Detail View to the currently selected item purely through the View Model.

Such a View Model might look like this:

public class MyViewModel

{

    private readonly List<MyClass> availableItems;

    private MyClass selectedItem;

    public MyViewModel()

    {

        this.availableItems = new List<MyClass>();

    }

    public ICollection<MyClass> AvailableItems

    {

        get { return this.availableItems; }

    }

    public MyClass SelectedItem

    {

        get { return this.selectedItem; }

        set 

        {

            if (!this.availableItems.Contains(value))

            {

                throw new ArgumentException("...");

            }

            this.selectedItem = value;

        }

    }

}

The main point of interest is that if you attempt to set SelectedItem to an instance that's not contained in the list of available items, an exception will be thrown. That's reasonable behavior, since we want the user to select only from the available items.

By default, AutoFixture works by assigning an Anonymous Value to all writable properties. Since these values are auto-generated, the value AutoFixture is going to assign to SelectedItem will be a new instance of MyClass, and thus not one of the available items. In other words, this will throw an exception:

var mvm = fixture.CreateAnonymous<MyViewModel>();

There are several solutions to this situation, depending on the scenario. If you need an instance with SelectedItem correctly set to a non-null value, you can use the Do method like this:

var mc = fixture.CreateAnonymous<MyClass>();

var mvm = fixture.Build<MyViewModel>()

    .Do(x => x.AvailableItems.Add(mc))

    .With(x => x.SelectedItem, mc)

    .CreateAnonymous();

This first creates an anonymous instance of MyClass, adds it to AvailableItems as part of a customized Builder pipeline and subsequently assigns it to SelectedItem.

Another option is to skip assigning only the SelectedItem property. This is a good option if you don't need that value in a particular test. You can use the Without method to do that:

var mvm = fixture.Build<MyViewModel>()

    .Without(s => s.SelectedItem)

    .CreateAnonymous();

This will assign a value to all other writable properties of MyViewModel (if it had had any), except the SelectedItem property. In this case, the value of SelectedItem will be null, since it is being ignored.

Finally you can simply choose to omit all AutoProperties using the OmitAutoProperties method:

var mvm = fixture.Build<MyViewModel>()

    .OmitAutoProperties()

    .CreateAnonymous();

In this scenario, only MyViewModel's constructor is being executed, while all writable properties are being ignored.

As you can see, AutoFixture offers great flexibility in providing specialized custom Builders that fit almost any situation.

The default behavior of AutoFixture is to create an Anonymous Variable by assigning a value to all writable properties of the created instance. This is great in many scenarios, but not so much in others. You can disable this behavior by using the OmitAutoProperties method, but sometimes, you would like most of the writable properties set, except one or two.

Consider this simple Person class:

public class Person

{

    private Person spouse;

    public DateTime BirthDay { get; set; }

    public string Name { get; set; }

    public Person Spouse 

    {

        get { return this.spouse; }

        set

        {

            this.spouse = value;

            if (value != null)

            {

                value.spouse = this;

            }

        }

    }

}

The main trouble with this class, seen from AutoFixture's perspective, is the circular reference exposed by the Spouse property. When AutoFixture attempts to create an anonymous instance of Person, it will create anonymous values for all writable properties, and that includes the Spouse property, so it attempts to create a new instance of the Person class and assign values to all public properties, including the Spouse property, etc.

In other words, this line of code throws a StackOverflowException:

var person = fixture.CreateAnonymous<Person>();

If you would still like to have anonymous values assigned to Name and BirthDay, you can use the Without method:

var person = fixture.Build<Person>()

    .Without(p => p.Spouse)

    .CreateAnonymous();

This will give you an anonymous instance of the Person class, but with the Spouse property still with its default value of null.

Several calls to Without can be chained if you want to skip more than one property.

Since AutoFixture is a Test Data Builder, one of its most important tasks is to build up graphs of fully populated, yet semantically correct, strongly typed objects. As such, its default behavior is to assign a value to every writable property in the object graph.

While this is sometimes the desired behavior, at other times it is not.

This is particularly the case when you want to test that a newly created object has a property of a particular value. When you want to test the default value of a writable property, AutoFixture's AutoProperty feature is very much in the way.

Let's consider as an example a piece of software that deals with vehicle registration. By default, a vehicle should have four wheels, since this is the most common occurrence. Although I always practice TDD, I'll start by showing you the Vehicle class to illustrate what I mean.

public class Vehicle

{

    public Vehicle()

    {

        this.Wheels = 4;

    }

    public int Wheels { get; set; }

}

Here's a test that ensures that the default number of wheels is 4 – or does it?

In fact the assertion fails because the actual value is 1, not 4.

[TestMethod]

public void AnonymousVehicleHasWheelsAssignedByFixture()

{

    // Fixture setup

    var fixture = new Fixture();

    var sut = fixture.CreateAnonymous<Vehicle>();

    // Exercise system

    var result = sut.Wheels;

    // Verify outcome

    Assert.AreEqual<int>(4, result, "Wheels");

    // Teardown

}

Why does the test fail when the value of Wheels is set to 4 in the constructor? It fails because AutoFixture is designed to create populated test data, so it assigns a value to every writable property. Wheels is a writable property, so AutoFixture assigns an integer value to it using its default algorithm for creating anonymous numbers. Since no other numbers are being created during this test, the number assigned to Wheels is 1. This is AutoFixture's AutoProperties feature in effect.

When you want to test constructor logic, or otherwise wish to disable the AutoProperties feature, you can use a customized Builder with the OmitAutoProperties method:

[TestMethod]

public void VehicleWithoutAutoPropertiesWillHaveFourWheels()

{

    // Fixture setup

    var fixture = new Fixture();

    var sut = fixture.Build<Vehicle>()

        .OmitAutoProperties()

        .CreateAnonymous();

    // Exercise system

    var result = sut.Wheels;

    // Verify outcome

    Assert.AreEqual<int>(4, result, "Wheels");

    // Teardown

}

The OmitAutoProperties method instructs AutoFixture to skip assigning automatic Anonymous Values to all writable properties in the object graph. Any properties specifically assigned by the With method will still be assigned.

The test using OmitAutoProperties succeeds.

A couple of days ago I released AutoFixture .8.4. It contains a few small feature additions and a bug fix. You can get it at the AutoFixture CodePlex site as usual.

You may have noticed that I'm frequently releasing incremental versions these days. This is because we have begun using AutoFixture for writing production software at Safewhere. So far, it has been a pleasure to use AutoFixture in my daily work, and watch colleagues pick it up and run with it.

Such intensive usage obviously uncovers missing features as well as a few bugs, which is the driving force behind the frequent releases. I've been happy to observe that so far, there have been only a few bugs, and the general API is very expressive and useful.

After we ship the first product written with AutoFixture, I plan to upgrade it to version .9 (beta). That should hopefully happen in the autumn of 2009.

Some time ago, my good friend Martin Gildenpfennig from Ative made me aware that AutoFixture (among other things) is an generic implementation of the Test Data Builder pattern, and indeed it is.

In the original Gang of Four definition of a Design Pattern, several people must independently have arrived at the same general solution to a given problem before we can call a coding idiom a true Pattern. In this spirit, the Test Data Builder pattern is on the verge of becoming a true Design Pattern, since I came up with AutoFixture without having heard about Test Data Builder :)

The problem is the same: How do we create semantically correct test objects in a manner that is flexible and yet hides away irrelevant complexity?

Like others before me, I tried the Object Mother (anti?)pattern and found it lacking. To me the answer was AutoFixture, a library that heuristically builds object graphs using Reflection and built-in rules for specific types.

Although my original approach was different, you can certainly use AutoFixture as a generic Test Data Builder.

To demonstrate this, let's work with this (oversimplified) Order object model:

Assuming that we have an instance of the Fixture class (called fixture), we can create a new instance of the Order class with a ShippingAddress in Denmark:

var order = fixture.Build<Order>()

    .With(o => o.ShippingAddress, 

        fixture.Build<Address>()

        .With(a => a.Country, "Denmark")

        .CreateAnonymous())

    .CreateAnonymous();

While this works and follows the Test Data Builder pattern, I find this more concise and readable:

var order = fixture.CreateAnonymous<Order>();

order.ShippingAddress.Country = "Denmark";

The result is the same.

We can also add anonymous order lines to the order using this fluent interface:

var order = fixture.Build<Order>()

    .Do(o => fixture.AddManyTo(o.OrderLines))

    .CreateAnonymous();

but again, I find it easier to simply let AutoFixture create a fully anonymous Order instance, and then afterwards modify the relevant parts:

var order = fixture.CreateAnonymous<Order>();

fixture.AddManyTo(order.OrderLines);

Whether you prefer one style over the other, AutoFixture supports them both.

It was only earlier this week that I released AutoFixture .8.2, but now I'm releasing version .8.3 – not that there was anything wrong with .8.2 (that I know of), but I had some time to implement new features, and I wanted to properly release those.

In the future I will blog about these new features (along with all the other AutoFixture features I haven't introduced yet).

Get it at the AutoFixture CodePlex site as usual.

Yesterday I created a new release (.8.2) of AutoFixture; this time with a new feature that I recently discovered that I needed, and about which I will blog later.

There are no breaking changes and no known bugs.

Previously, we saw how you can set property values while building anonymous variables with AutoFixture. While I insinuated that I consider this a somewhat atypical scenario, we can now safely venture forth to the truly exotic :)

Imagine that you want to build an anonymous instance of a type that requires you to call a certain method before you can start assigning properties. It's difficult to come up with a reasonable example of this, but although I consider it quite bad design, I've seen interfaces that include an Initialize method that must be called before any other member. In our example, let's call this interface IBadDesign.

Let's say that we have a class called SomeImp that implements IBadDesign. Here's the relevant part of the class:

#region IBadDesign Members

public string Message

{

    get { return this.message; }

    set

    {

        if (this.mc == null)

        {

            throw new InvalidOperationException("...");

        }

        this.message = value;

        this.transformedMessage = this.mc.DoStuff(value);

    }

}

public void Initialize(MyClass mc)

{

    this.mc = mc;

}

#endregion

This is a rather ridiculous example, but I couldn't think of a better one. The main point here is that given a brand-new instance of SomeImp, this usage is invalid:

something.Message = "Ploeh";

While the above code snippet will throw an InvalidOperationException, this will work:

something.Initialize(new MyClass());

something.Message = "Ploeh";

The problem is that by default, AutoFixture ignores methods and only assigns properties, which means that this is also going to throw:

var imp = fixture.CreateAnonymous<SomeImp>();

As we saw with properties, we can use the Build method to customize how the type is being created. Properties can be set with the With method, while methods can be invoked with the Do method, so this is all it takes:

var imp = fixture.Build<SomeImp>()

    .Do(s => s.Initialize(new MyClass()))

    .CreateAnonymous();    

We don't have to explicitly set the Message property, as AutoFixture is going to do this automatically, and all implicit assignments happen after explicit actions defined by With or Do (and in case you were wondering, you can mix With and Do, and ObjectBuilder<T> will preserve the ordering).

In most cases, having to use the Do method probably constitutes a design smell of the SUT, but the method is there if you need it.

To make it a bit easier to get started with AutoFixture without having to trawl through all my blog posts, I've added a Cheat Sheet over at the AutoFixture CodePlex site.

As I add more posts on AutoFixture, I'll update the Cheat Sheet with the essentials. Please let me know if you think something's missing.

In my previous post I described how the Build method can be used to customize how a single anonymous variable is created.

A common customization is to set a property value during creation. In most cases, this can simply be done after the anonymous variable has been created (so the following is not an AutoFixture customization):

var mc = fixture.CreateAnonymous<MyClass>();

mc.MyText = "Ploeh";

By default, AutoFixture assigns anonymous values to all writable properties, but since they are writable, you can always explicitly give them different values if you care.

However, there are situations when a property is writable, but can't take just any value of its type. Sometimes this is a sign that you should reconsider your API, as I've previously described, but it may also be a legitimate situation.

Consider a Filter class that has Min and Max properties. To be semantically correct, the Min property must be less than or equal to the Max property. Each property is implemented like this:

public int Min

{

    get { return this.min; }

    set

    {

        if (value > this.Max)

        {

            throw new ArgumentOutOfRangeException("value");

        }

        this.min = value;

    }

}

When you ask AutoFixture to create an instance of the Filter class, it will throw an exception because it's attempting to set the Min property after the Max property, and the default algorithm for numbers is to return numbers in an increasing sequence. (In this example, the Min property is being assigned a value after the Max property, but AutoFixture has no contract that states that the order in which properties are assigned is guaranteed.) In other words, this throws an exception:

var f = fixture.CreateAnonymous<Filter>();

To solve this problem, we will have to customize the assignment of the Min and Max properties, before we ask AutoFixture to create an instance of the Filter class. Here's how to do that:

int min = fixture.CreateAnonymous<int>();

int max = min + 1;

var f = fixture.Build<Filter>()

    .With(s => s.Max, max)

    .With(s => s.Min, min)

    .CreateAnonymous();

The With method lets you specify an expression that identifies a property, as well as the value that should be assigned to that property. When you do that, AutoFixture will never attempt to assign an anonymous value to that property, but will instead use the value you specified.

In most cases, just creating a truly anonymous instance and subsequently explicitly assigning any significant values is easier, but using the Build method with one or more calls to the With method gives you the power to override any property assignments before the instance is created.

Until now, I've shown you how you can make wholesale adjustments or customizations to an entire Fixture instance, effectively changing the way it creates all instances of a particular type.

In some scenarios, you'd rather want to customize how a single instance is created without influencing other instances of the same type. For this purpose, AutoFixture includes a class called ObjectBuilder<T> that can be used to do exactly that.

The easiest way to get an instance of this class is by calling Build on a Fixture instance. This will give you an instance of ObjectBuilder<T> that you can use to customize the build steps. When you are done, CreateAnonymous returns the built instance.

var mc = fixture.Build<MyClass>().CreateAnonymous();

This particular example doesn't define any customizations, so it's equivalent to

var mc = fixture.CreateAnonymous<MyClass>();

In fact, Fixture.CreateAnonymous is little more than a convenience method wrapping an ObjectBuilder (there's a few extra differences, but that's a topic for another post).

It's worth noting that the object specified by the type parameter to the Build method is first created when you call CreateAnonymous.

In future posts I'll demonstrate how to use the Build method to customize individual anonymous variables.

Today I've created a new release (.8.1 for lack of a better version number) of AutoFixture. While it contains some breaking changes, they all relate to features that I have yet to cover here on the blog – in other words: All the examples that I've posted so far are still valid.

Dear reader, I hope you are still with me!

After eight posts of AutoFixture feature walkthroughs, I can't blame you for wondering why this tool might even be relevant to you. In this post, we'll finally begin to look at how AutoFixture can help you towards Zero-Friction TDD!

In an earlier post, I described how the Fixture Object pattern can help you greatly reduce the amount of test code that you have to write. Since AutoFixture was designed to act as a general-purpose Fixture Object, it can help you reduce the amount of test code even further, letting you focus on specifying the behavior of your SUT.

In that former post, the original example was this complex test that I will repeat in it's entirety for your benefit (or horror):

[TestMethod]

public void NumberSumIsCorrect_Naïve()

{

    // Fixture setup

    Thing thing1 = new Thing()

    {

        Number = 3,

        Text = "Anonymous text 1"

    };

    Thing thing2 = new Thing()

    {

        Number = 6,

        Text = "Anonymous text 2"

    };

    Thing thing3 = new Thing()

    {

        Number = 1,

        Text = "Anonymous text 3"

    };

    int expectedSum = new[] { thing1, thing2, thing3 }.

        Select(t => t.Number).Sum();

    IMyInterface fake = new FakeMyInterface();

    fake.AddThing(thing1);

    fake.AddThing(thing2);

    fake.AddThing(thing3);

    MyClass sut = new MyClass(fake);

    // Exercise system

    int result = sut.CalculateSumOfThings();

    // Verify outcome

    Assert.AreEqual<int>(expectedSum, result,

        "Sum of things");

    // Teardown

}

This test consists of 18 lines of code.

Using the Fixture Object pattern, I was able to cut that down to 7 lines of code, which is a 61% improvement (however, the downside was an additional 19 lines of (reusable) code for MyClassFixture, so the benefit can only be reaped when you have multiple tests leveraged by the same Fixture Object. This was all covered in the former post, to which I will refer you).

With AutoFixture, we can do much better. Here's a one-off rewrite of the unit test using AutoFixture:

[TestMethod]

public void NumberSumIsCorrect_AutoFixture()

{

    // Fixture setup

    Fixture fixture = new Fixture();

    IMyInterface fake = new FakeMyInterface();

    fixture.Register<IMyInterface>(() => fake);

    var things = fixture.CreateMany<Thing>().ToList();

    things.ForEach(t => fake.AddThing(t));

    int expectedSum = things.Select(t => t.Number).Sum();

    MyClass sut = fixture.CreateAnonymous<MyClass>();

    // Exercise system

    int result = sut.CalculateSumOfThings();

    // Verify outcome

    Assert.AreEqual<int>(expectedSum, result,

        "Sum of things");

    // Teardown

}

In this test, I map the concrete fake instance to the IMyInterface type in the fixture object, and then use its ability to create many anonymous instances with one method call. Before exercising the SUT, I also use the fixture instance as a SUT Factory.

Apart from AutoFixture (and FakeMyInterface, which is invariant for all variations, and thus kept out of the comparison), this test stands alone, but still manages to reduce the number of code lines to 10 lines – a 44% improvement! In my book, that's already a significant gain in productivity and maintainability, but we can do better!

If we need to test MyClass repeatedly in similar ways, we can move the common code to a Fixture Object based on AutoFixture, and the test can be refactored to this:

[TestMethod]

public void NumberSumIsCorrect_DerivedFixture()

{

    // Fixture setup

    MyClassFixture fixture = new MyClassFixture();

    fixture.AddManyTo(fixture.Things);

    int expectedSum = 

        fixture.Things.Select(t => t.Number).Sum();

    MyClass sut = fixture.CreateAnonymous<MyClass>();

    // Exercise system

    int result = sut.CalculateSumOfThings();

    // Verify outcome

    Assert.AreEqual<int>(expectedSum, result,

        "Sum of things");

    // Teardown

}

Now we are back at 7 lines of code, which is on par with the original Fixture Object-based test, but now MyClassFixture is reduced to 8 lines of code:

internal class MyClassFixture : Fixture

{

    internal MyClassFixture()

    {

        this.Things = new List<Thing>();

        this.Register<IMyInterface>(() =>

            {

                var fake = new FakeMyInterface();

                this.Things.ToList().ForEach(t =>

                    fake.AddThing(t));

                return fake;

            });

    }

    internal IList<Thing> Things { get; private set; }

}

Notice how I've moved the IMyInterface-to-FakeMyInterface mapping to MyClassFixture. Whenever it's asked to create a new instance of IMyInterface, MyClassFixture makes sure to add all the Thing instances to the fake before returning it.

Compared to the former Fixture Object of 19 lines, that's another 58% improvement. Considering some of the APIs I encounter in my daily work, the above example is even rather simple. The more complex and demanding your SUT's API is, the greater the gain from using AutoFixture will be, since it's going to figure out much of the routine stuff for you.

With this post, I hope I have given you a taste of the power that AutoFixture provides. It allows you to focus on specifying the behavior of your SUT, while taking care of all the infrastructure tedium that tends to get in the way.

When writing unit tests you often need to deal with sequences and collections, populating lists with anonymous data as part of setting up a Fixture.

This is easy to do with AutoFixture. While you can obviously create a simple loop and call CreateAnonymous from within the loop, AutoFixture provides some convenient methods for working with sequences.

Equivalent to the CreateAnonymous method, the Fixture class also includes the CreateMany method that creates a sequence of anonymous variables. CreateManyAnonymous might have been a more concise and consistent name for the method, but I felt that this was a bit too verbose.

This will create an IEnumerable<string>:

Fixture fixture = new Fixture();

var strings = fixture.CreateMany<string>();

Obvously, you can create sequences of whatever type you want, as long as AutoFixture can figure out how to create instances of the type:

var myInstances = fixture.CreateMany<MyClass>();

Being able to create sequences of anonymous data is nice, but sometimes you need to add multiple anonymous items to an existing list (particularly if that list is a read-only property of your SUT).

To support that scenario, the Fixture class also has the AddManyTo method that can be used like this:

var list = new List<MyClass>();

fixture.AddManyTo(list);

This simply creates many anonymous MyClass instances and adds them all to the list. Once more, AddManyAnonymousTo might have been a more precise name, but again I chose a less verbose alternative.

If you want more control over how the instances are created, a more explicit overload of AddManyTo gives you that.

var list = new List<int>();

var r = new Random();

fixture.AddManyTo(list, () => r.Next());

The above examples adds many random numbers to the list of integers, since the second parameters is a Func<T> used to create the instances.

By default, these methods all create 3 anonymous variables when called, since 3 is a good equivalent for many. If you want a different number of instances to be created, you can modify the RepeatCount property.

fixture.RepeatCount = 10;

var sequence = fixture.CreateMany<MyClass>();

The above example will create an IEnumerable<MyClass> with 10 anonymous MyClass instances, while this will add 7 anonymous instances to the list variable:

var list = new List<MyClass>();

fixture.RepeatCount = 7;

fixture.AddManyTo(list);

AutoFixture provides some convenient methods for creating and managing collections of anonymous data. While it may seem simple (and it is), in a future post I will demonstrate how it can save you quit a bit of infrastructure code, and enable you to write unit tests that are shorter, more concise and more maintainable.

As a response to my description of how AutoFixture creates objects, Klaus asked:

“[What] if the constructor of ComplexChild imposes some kind of restriction on its parameter? If, for example, instead of the "name" parameter, it would take a "phoneNumber" parameter (as a string), and do some format checking?”

Now that we have covered some of the basic features of AutoFixture, it’s time to properly answer this excellent question.

For simplicity’s sake, let’s assume that the phone number in question is a Danish phone number: This is pretty good for example code, since a Danish phone number is essentially just an 8-digit number. It can have white space and an optional country code (+45), but strip that away, and it’s just an 8-digit number. However, there are exceptions, since the emergency number is 112 (equivalent to the American 911), and other 3-digit special numbers exist as well.

With that in mind, let’s look at a simple Contact class that contains a contact’s name and Danish phone number. The constructor might look like this:

public Contact(string name, string phoneNumber)

{

    this.Name = name;

    this.PhoneNumber = 

        Contact.ParsePhoneNumber(phoneNumber);

}

The static ParsePhoneNumber method strips away white space and optional country code and parses the normalized string to a number. This fits the scenario laid out in Klaus’ question.

So what happens when we ask AutoFixture to create an instance of Contact? It will Reflect over Contact’s constructor and create two new anonymous string instances – one for name, and one for phoneNumber. As previously described, each string will be created as a Guid prepended with a named hint – in this case the argument name. Thus, the phoneNumber argument will get a value like "phoneNumberfa432351-1563-4769-842c-7588af32a056", which will cause the ParsePhoneNumber method to throw an exception.

How do we deal with that?

The most obvious fix is to modify AutoFixture’s algorithm for generating strings. Here an initial attempt:

fixture.Register<string>(() => "112");

This will simply cause all generated strings to be "112", including the Contact instance's Name property. In unit testing, this may not be a problem in itself, since, from an API perspective, the name could in principle be any string.

However, if the Contact class also had an Email property that was parsed and verified from a string argument, we'd be in trouble, since "112" is not a valid email address.

We can't easily modify the string generation algorithm to fit the requirements for both a Danish telephone number and an email address.

Should we then conclude that AutoFixture isn't really useful after all?

On the contrary, this is a hint to us that the Contact class' API could be better. If an automated tool can't figure out how to generate correct input, how can we expect other developers to do it?

Although humans can make leaps of intuition, an API should still go to great lengths to protect its users from making mistakes. Asking for an unbounded string and then expecting it to be in a particular format may not always be the best option available.

In our particular case, the Value Object pattern offers a better alternative. Our first version of the DanishPhoneNumber class simply takes an integer as a constructor argument:

public DanishPhoneNumber(int number)

{

    this.number = number;

}

If we still need to parse strings (e.g. from user input), we could add a static Parse, or even a TryParse, method and test that method in isolation without involving the Contact class.

This neatly solves our original issue with AutoFixture, since it will now create a new instance of DanishPhoneNumber as part of the creation process when we ask for an anonymous Contact instance.

The only remaining issue is that by default, the number fed into the DanishPhoneNumber instance is likely to be considerably less than 112 – actually, if no other Int32 instances are created, it will be 1.

This will be a problem if we modify the DanishPhoneNumber constructor to look like this:

public DanishPhoneNumber(int number)

{

    if ((number < 112) ||

        (number > 99999999))

    {

        throw new ArgumentOutOfRangeException("number");

    }

    this.number = number;

}

Unless a unit test has already caused AutFixture to previously create 111 other integers (highly unlikely), CreateAnonymous<Contact> is going to throw an exception.

This is easy to fix. Once again, the most obvious fix is to modify the creation algorithm for integers.

fixture.Register<int>(() => 12345678);

However, this will cause that particular instance of Fixture to return 12345678 every time you ask it to create an anonymous integer. Depending on the scenario, this may or may not be a problem.

A more targeted solution is to specifically address the algorithm for generating DanishPhoneNumber instances:

fixture.Register<int, DanishPhoneNumber>(i => 

    new DanishPhoneNumber(i + 112));

Here, I've even used the Register overload that automatically provides an anonymous integer to feed into the DanishPhoneNumber constructor, so all I have to do is ensure that the number falls into the proper range. Adding 112 (the minimum) neatly does the trick.

If you don't like the hard-coded value of 112 in the test, you can use that to further drive the design. In this case, we can add a MinValue to DanishPhoneNumber:

fixture.Register<int, DanishPhoneNumber>(i =>

    new DanishPhoneNumber(i + 

        DanishPhoneNumber.MinValue));

Obvously, MinValue will also be used in DanishPhoneNumber's constructor to define the lower limit of the Guard Clause.

In my opinion, a good API should guide the user and make it difficult to make mistakes. In many ways, you can view AutoFixture as an exceptionally dim user of your API. This is the reason I really enjoyed receiving Klaus' original question: Like other TDD practices, AutoFixture drives better design.

Several times in my previous AutoFixture posts, I’ve insinuated that you can change the algorithms used for creating strings, numbers and so on, if you don’t like the defaults.

One way you can do this is by simply using the Register method that I introduced in my previous post. Let’s say that you want to replace the string algorithm to simply return a specific string:

fixture.Register<string>(() => "ploeh");

No matter how many times you’ll call CreateAnonymous<string> on that particular fixture object, it will always return ploeh.

The Register method is really only a type-safe convenience method that wraps access to the TypeMappings property. TypeMappings is just a Dictionary of types mapped to functions. By default, the Fixture class has a set of pre-defined TypeMappings for primitive types such as strings, numbers and booleans, so you could access the function used to generate strings by indexing into this Dictionary with the System.String type.

Equivalent to the above example, you could alternatively replace the string algorithm like this:

fixture.TypeMappings[typeof(string)] = s => "fnaah";

Instead of using the Register method, I here assign a lambda expression directly to the key identified by the System.String type. This is what the Register method does, so the result is exactly the same.

However, you may have noticed that by accessing TypeMappings directly, the signature of the function is different. The Register method takes a Func<T>, whereas the TypeMappings Dictionary expects a Func<object, object>. As you can see, the Register method is more type-safe, but the TypeMappings Dictionary gives you a chance to utilize the optional seed that one of the CreateAnonymous overloads takes.

You could, for example, do this:

fixture.TypeMappings[typeof(string)] = s =>

    string.Format((string)s, new Random().Next(100));

Although this particular algorithm has a built-in weakness (can you spot it?), we can now use the seed to provide a format string, like this:

string result = fixture.CreateAnonymous("Risk: {0}%");

which will yield a result like Risk: 32%.

When I designed the extensibility mechanism for AutoFixture, I seriously considered defining an interface that all TypeMappings had to implement, but I ended up preferring a Func<object, object> instead, since this allows you to redefine a particular algorithm inline in a test by using an anonymous delegate or lambda expression, and you can also reuse an existing algorithm, as long as it fits the signature.

Now that I’ve described how AutoFixture creates objects, it’s time to look at a bit more advanced scenario. As you may recall, AutoFixture creates an object graph based on the public constructors of the types contained in that object graph.

That’s all well and good when all involved types have public constructors, but what happens when this is not the case?

Imagine that the MyClass constructor has this signature:

public MyClass(IMyInterface mi)

Since IMyInterface is an interface it has no public constructors, so this will not work:

Fixture fixture = new Fixture();

MyClass sut = fixture.CreateAnonymous<MyClass>();

The second line of code will throw an ArgumentException ObjectCreationException* stating that “AutoFixture was unable to create an instance of type Ploeh.QualityTools.AutoFixtureDocumentationTest.Intermediate.IMyInterface, since it has no public constructor.” Not terribly surprising, actually.

To resolve this issue, the Register method allows you to specify a custom function that creates an object of the requested type. In the case of IMyInterface, that would be a Func<IMyInterface>:

Fixture fixture = new Fixture();

fixture.Register<IMyInterface>(() => 

    new FakeMyInterface());

MyClass sut = fixture.CreateAnonymous<MyClass>();

Here, I use a lambda expression to register the FakeMyInterface type, so that every time that particular Fixture instance is asked to create an instance of IMyInterface, it will invoke the lambda expression, and thus return an instance of FakeMyInterface (which obviously implements IMyInterface).

The Register method simply lets you map types without public constructors to concrete types created by a function you specify.

A more advanced scenario arises if you wish to use a specific text with this FakeMyInterface constructor overload:

public FakeMyInterface(int number, string text)

Obviously, you can do it manually like this:

Fixture fixture = new Fixture();

int anonymousNumber = fixture.CreateAnonymous<int>();

string knownText = "This text is not anonymous";

fixture.Register<IMyInterface>(() => 

    new FakeMyInterface(anonymousNumber, knownText));

Here, I simply use the fixture object to create an anonymous number, while the knownText variable is explicitly assigned a value, and then both are used as outer variables in the Register function.

This is, however, a common scenario, so the Register method has some convenience overloads that will supply anonymous input parameters for you to use or throw away as you like. This means that I can rewrite the above example to this:

Fixture fixture = new Fixture();

string knownText = "This text is not anonymous";

fixture.Register<int, string, IMyInterface>((i, s) => 

    new FakeMyInterface(i, knownText));

Compared to the previous example, I save a line of code. The drawback is that I have to explicitly specify the type parameters to the Register method. In my book, that’s a pretty good tradeoff, as it removes a line of irrelevant code, and allows the test to focus on the relevant parts.

Notice that this Register overload creates both an anonymous integer and an anonymous string, but since I don’t want to use the anonymous string (s), I just ignore it and use the knownText variable instead.

*Edit (2009-09-02): Changed the name of the Exception type to correctly reflect a breaking change introduced in AutoFixture .8.5.

(Just back after 14 days in Morocco, I'll pick up where I left…)

The last group of built-in special creation algorithms for AutoFixture, besides strings and numbers, concerns Booleans.

The default algorithm is to alternate between true and false, starting with true; i.e. the first time you invoke

fixture.CreateAnonymous<bool>();

it will return true, the next time false, then true again, etc.

The reason I chose this algorithm was because I wanted to ensure that the first time AutoFixture creates an anonymous Boolean, it will return true, which is different than the default (false, in case you were in doubt). This gives us better assurance that a given constructor argument or property is being assigned a real value instead of the default.

Like with numbers, using the overload that takes a seed has no effect, and the seed is simply ignored.

fixture.CreateAnonymous(true);

In other words, the above method is still going to return false every second time, so it doesn’t really make sense to use this overload at all for Booleans (or numbers).

Previously, we saw how AutoFixture creates strings. In this post, I’ll explain how it creates numbers. Once again, the algorithm that I’ll explain here is the default algorithm, but if you don’t like it, you can replace it with something else.

It’s very simple: Numbers are returned in the ordered sequence of natural numbers (1, 2, 3, 4, 5, …). The first time you call

fixture.CreateAnonymous<int>();

the returned number will be 1, the second time 2, etc.

The reason I chose that particular algorithm is because it creates numbers that we, as humans, find… well… natural!

A lot of the domains we model work with natural numbers, and even if you write an API where negative numbers are allowed, it’s fairly unlikely that positive numbers will not be allowed. Thus, in most cases, small positive integers tend to be ‘nice’ values in most APIs – and recall that when we do TDD, we focus on the Happy Path, so it’s important to pick values that take us down that path.

Using the overload that takes a seed, like this:

fixture.CreateAnonymous(42);

has no effect – the seed (in this case 42) is simply ignored, so if you call this after first calling the parameterless overload twice, the return number is going to be 3.

Each number type, however, has its own sequence, so even if you’ve been creating a few Int32 instances like above,

fixture.CreateAnonymous<decimal>();

will return 1.

The following number types all work that way:

• Byte
• Decimal
• Double
• Int16
• Int32
• Int64
• SByte
• Single
• UInt16
• UInt32
• UInt64

As previously hinted, AutoFixture creates primitive types like strings, numbers, etc. using special algorithms.

In this post, I’ll describe the default algorithm for strings. If you don’t like this particular algorithm, you can replace it with your own.

If you don’t care about the created string at all, you can just create it like this:

string anonymousText = 

    fixture.CreateAnonymous<string>();

The algorithm is simply to create a new Guid and convert it to a string, so that anonymousText will have a value like “f5cdf6b1-a473-410f-95f3-f427f7abb0c7”. Obviously, you don’t know exactly which value will be returned, but that’s the whole point of Constrained Non-Determinism.

When I create string values as Explicit Expectations, I prefer that the Assert failure message contains some sort of hint for me, so I can instead provide a hint to the CreateAnonymous method:

string anonymousName = fixture.CreateAnonymous("Name");

This overload is still generic, but since I provide a string as input, type inferencing takes care of the rest.

This is still going to create a Guid, but will now prepend the hint, giving a string like “Name30a35da1-d681-441b-9db3-77ff51728b58”.

Now, when my test fails, I’ll get an error message equivalent to

“Assert.AreEqual failed. Expected:<Namef2b1f55b-e9dc-4aac-a1ab-128dc80d3b71>. Actual:<ploeh>. Boo hiss”

which I find marginally more informative than if the hint hadn’t been there.

In a future post, I’ll explain how you can replace this algorithm with something else.

AutoFixture creates Anonymous Variables, but you’d probably like to know how it does it. This post explains how.

As we previously saw, the CreateAnonymous method can create a new instance of a type known to it only from its type parameter:

MyClass sut = fixture.CreateAnonymous<MyClass>();

AutoFixture was never compiled with any knowledge of the MyClass type, so it obviously uses Reflection to create the instance. That’s hardly surprising in itself.

In the case of MyClass, it has a default constructor, so creating an instance is as simple as it can be, but what happens if we instead ask for a more complex instance?

As an example, the ComplexParent type has this constructor:

public ComplexParent(ComplexChild child)

ComplexChild, however, has two constructors:

public ComplexChild(string name)

and

public ComplexChild(string name, int number)

So what happens when we ask AutoFixture to create an instance of ComplexParent?

ComplexParent only has a single public constructor, so AutoFixture doesn’t have any other choice than picking that. This means that it must now create an anonymous instance of ComplexChild.

Fortunately, AutoFixture’s raison d’être is creating objects, so creating an instance of ComplexChild isn’t a big deal; the only thing it needs to figure out is which constructor to pick. When multiple public constructors are available, it always picks the one with the fewest number of arguments – in this case ComplexChild(string).

Obviously, it then needs to create an anonymous string value. For primitive types like strings, numbers and booleans, AutoFixture has custom algorithms for value creation. Since I’ll cover those mechanisms later, suffice it to say that Constrained Non-Determinism is used to create an anonymous string.

At this point, AutoFixture has all the information it needs, and it can now return a properly initialized instance of ComplexParent.

This ability to create instances of almost arbitrarily complex types is a real time-saver: That, more than the ability to create single strings or numbers, was the reason I originally created AutoFixture, since I got tired of initializing complex object graphs just to satisfy some API that the Test Fixture requires.

It also has the additional advantage that it hides all the irrelevant object creation code that the Test Fixture needs, but which isn’t relevant for the test at hand.

It gives me great pleasure to announce my latest project: AutoFixture!

What is AutoFixture?

In essence, AutoFixture is a library that creates Anonymous Variables for you when you write unit tests. The intention is that it should enhance your productivity when you do Test-Driven Development – as it has done mine.

Instead of using mental resources on creating Anonymous Variables, AutoFixture can do it for you. By default, it uses Constrained Non-Determinism, but you can configure it to behave differently if you wish.

Here’s a very basic example:

[TestMethod]

public void IntroductoryTest()

{

    // Fixture setup

    Fixture fixture = new Fixture();

    int expectedNumber = fixture.CreateAnonymous<int>();

    MyClass sut = fixture.CreateAnonymous<MyClass>();

    // Exercise system

    int result = sut.Echo(expectedNumber);

    // Verify outcome

    Assert.AreEqual<int>(expectedNumber, result, "Echo");

    // Teardown

}

The Fixture class is your main entry point to AutoFixture. You can use it as is, customize it, or derive from it as you please; it makes a great base class for a Fixture Object.

The expectedNumber variable may be an Explicit Expectation, but its value is Anonymous, so instead of coming up with a number ourselves, we can let the CreateAnonymous<T> method do it for us.

This method can create instances of most CLR types as long as they have a public constructor (it uses Reflection), but for many primitive types (like Int32), it has specific, customizable algorithms for creating values using Constrained Non-Determinism.

When creating the SUT, we can also use Fixture as an excellent SUT Factory. Since it will do whatever it can to create an instance of the type you ask for, it is pretty robust if you decide to refactor the SUT’s constructor.

The above example only hints at what AutoFixture can do. Since the example is very simple, it may be hard to immediately understand its value, so in future posts I will expand on specific AutoFixture features and principles.

Getting started with AutoFixture is as simple as downloading it from CodePlex and referencing the assembly in Visual Studio.