Extending AutoFixture

AutoFixture supports three main categories of extension points

• Specimen builders

• Behaviors

• Customizations

Specimen builders

Specimen builders are components that can be used to customize the creation of objects that AutoFixture can't handle with the default setup.

A specimen builder must implement the ISpecimenBuilder interface that looks like the following snippet

public interface ISpecimenBuilder
{
    object Create(object request, ISpecimenContext context);
}

A request can be virtually of any type but most commonly they are reflection types like Type, PropertyInfo, ParameterInfo and so on. The AutoFixture kernel uses a chain of responsibility to explore all the available builders and stop when a builder able to satisfy the request is met, directly or indirectly.

The context parameter represents the context in which the request is being handled. It's interface exposes only the Resolve method that is used to invoke AutoFixture's chain of responsibility to generate a value.

Here is an example of a specimen builder used to create instances of a specific type.

public class SampleValueObject
{
    public string StringValue { get; set; }

    public int IntValue { get; set; }
}

public class SampleValueObjectSpecimenBuilder : ISpecimenBuilder
{
    public object Create(object request, ISpecimenContext context)
    {
        if (request is Type type && type == typeof(SampleValueObject))
        {        
            return new SampleValueObject
            {
                StringValue = context.Resolve(typeof(string)) as string,
                IntValue = 42
            };
        }

        return new NoSpecimen();
    }
}

Specimen builder are added to a given fixture via its Customizations collection.

[Test]
public void Fixture_uses_specimen_builder_to_create_value()
{
    // ARRANGE
    var fixture = new Fixture();
    fixture.Customizations.Add(new SampleValueObjectSpecimenBuilder());

    // ACT
    var obj = fixture.Create<SampleValueObject>();

    // ASSERT
    Assert.That(obj.IntValue, Is.EqualTo(42));
}

Behaviors

Together with specimen builders, behaviors are part of the graph used to represent the chain of responsibility used to create values.

Unlike the specimen builders, that can be seen as the leaves of the graph and therefore can only respond to a request, behaviors have access to both the request and the response and can act or modify them.

For example, the TracingBehavior, which is included in the AutoFixture core package, can be used to track the chain of calls used to serve a certain request.

var fixture = new Fixture();
fixture.Behaviors.Add(new TracingBehavior());
var value = fixture.Create<SampleValueObject>();

When executing the snippet above, the following will be printed on the standard out

  Requested: AutoFixture.Kernel.SeededRequest
    Requested: SampleValueObject
      Requested: System.String StringValue
        Requested: AutoFixture.Kernel.SeededRequest
          Requested: System.String
          Created: d2f151c4-afa6-414c-8168-07b4de1ad5ae
        Created: StringValued2f151c4-afa6-414c-8168-07b4de1ad5ae
      Created: StringValued2f151c4-afa6-414c-8168-07b4de1ad5ae
      Requested: Int32 IntValue
        Requested: AutoFixture.Kernel.SeededRequest
          Requested: System.Int32
          Created: 195
        Created: 195
      Created: 195
    Created: SampleValueObject
  Created: SampleValueObject

Behaviors implement the ISpecimenBuilderTransformation interface. This is what the interface looks like

public interface ISpecimenBuilderTransformation
{
    ISpecimenBuilderNode Transform(ISpecimenBuilder builder);
}

Customizations

Finally, AutoFixture uses classes implementing the ICustomization interface to wrap in a single place multiple changes to the fixture configuration.

The ICustomization interface exposes a single method, Customize, that accepts a fixture and applies configuration changes to it.

public interface ICustomization
{
    void Customize(IFixture fixture);
}

For example, the customization below injects values for int and string.

public class TestCustomization : ICustomization
{
    public void Customize(IFixture fixture)
    {
        fixture.Customize<SampleValueObject>(o => o.With(p => p.StringValue, "FooBar"));

        fixture.Inject("Hello world");

        fixture.Inject(42);
    }
}

The customization can then be used as it follows.

[Test]
public void TestCustomization_injects_constant_values()
{
    // ARRANGE
    var fixture = new Fixture();
    fixture.Customize(new TestCustomization());

    // ACT
    var testValue = fixture.Create<(int value, string message)>();

    // ASSERT
    Assert.That(testValue.value, Is.EqualTo(42));
    Assert.That(testValue.message, Is.EqualTo("Hello world"));
}

[Test]
public void TestCustomization_mixes_values()
{
    // ARRANGE
    var fixture = new Fixture();
    fixture.Customize(new TestCustomization());

    // ACT
    var testValue = fixture.Create<SampleValueObject>();

    // ASSERT
    Assert.That(testValue.value, Is.EqualTo(42));
    Assert.That(testValue.message, Is.EqualTo("FooBar"));
}

In the snippet above you can see how AutoFixture uses the injected values together with the ones specified in the customization when constructing an instance of SampleValueObject.