Microsoft Fakes is a full featured mocking framework built into Visual Studio 11. Currently, the available documentation is limited and marked as “preview only”, however it does provide us with some very good descriptions.

Microsoft Fakes is an isolation framework for creating delegate-based test stubs and shims in .NET Framework applications. The Fakes framework can be used to shim any .NET method, including non-virtual and static methods in sealed types.

Additionally here is Wikipedia’s definition of Mock Object for reference

In object-oriented programming, mock objects are simulated objects that mimic the behavior of real objects in controlled ways. A programmer typically creates a mock object to test the behavior of some other object, in much the same way that a car designer uses a crash test dummy to simulate the dynamic behavior of a human in vehicle impacts.

Shim any .NET Method

The real interesting part here is that Microsoft Fakes can shim “any .NET method, including non-virtual and static methods in sealed types”.  Existing mocking frameworks work by providing “on the fly” implementations to preexisting interfaces with a bit of Dependency Injection to get them situated in the class/method under test.

Microsoft Fakes is going a level deeper by mocking objects with no preexisting interfaces and allowing statics to be mocked in the process. This type of mocking is quite complex to pull off.  So much so, that there are only a handful of products out there that do this.  TypeMock’s Isolator, Telerik’s JustMock and the Microsoft Research project Moles that ultimately lead to Microsoft Fakes. 

TypeMock’s Isolator has been a regular so to speak in unit testing circles for a while now and I’ve actively considered it before, but the starting price of $799 has always been a little steep for my tastes. Telerik’s JustMock is the new kid on the block (past 2-3 years). JustMock has freemium edition supporting general mocking features and a pay version which has support for static, sealed & non virtual mocking with a base price of $299.

The biggest surprise is the Microsoft Research project Moles, which seems to have about the same set of features as Microsoft Fakes, has apparently been available since 11/1/2010 and is compatible with both Visual Studio 2010 & 2008 (based on the Visual Studio 2010 Moles x86 - Isolation Framework for .NET download page).  Perhaps this is the internet’s best kept secret… well, maybe not.  Regardless, I’ll be creating a future blog post going over using Moles in Visual Studio 2010.

Architectural Implications

Without a commercial mocking framework or Microsoft Fakes, if you’re going to do unit testing and you want to do it right as in truly isolate the code under test then you’re going to need to mock dependent objects.  However, just mocking the objects isn’t enough, you also need to instruct the code under test to use the mocks as opposed to its normal implementation.  Typically this requires some form of Dependency Injection. 

For reference here is Wikipedia's definition of Dependency Injection:

Dependency injection (DI) is a design pattern in object-oriented computer programming whose purpose is to reduce the coupling between software components. It is similar to the factory method pattern. Frequently an object uses (depends on) work produced by another part of the system. With DI, the object does not need to know in advance about how the other part of the system works. Instead, the programmer provides (injects) the relevant system component in advance along with a contract that it will behave in a certain way.

To truly isolate code in unit tests you’re typically bound to the following practices as part of Dependency Injection:

• Any object that needs to be mocked needs to be non static and have an interface
• You’ll either need to have a Dependency Injection framework as part of the architecture or the right patterns in place to manually resolve and inject as needed
• Constructors will have to be modified to take in interface types for the dependent objects

That’s a lot of Architectural commitment.  As with any design pattern there are “trade offs” involved in usage.  With Dependency Injection you get reduced coupling and the ability to unit test thoroughly, increasing complexity and reducing maintainability by some level in the process.  The question with any design pattern’s usage is: are the trade offs worth it based on the functionality provided for the problem domain in question? 

Microsoft Fakes changes the trade off evaluation for Dependency Injection.  Currently you trade increased complexity and reduced maintainability for increased code quality brought about by unit testing. 

Microsoft Fakes decouples Dependency Injection from unit testing, therefore changing the value proposition for Dependency Injection to instead be weighed on its own merits of whether or not it adds value to the problem domain in question.

Proper unit testing can now be integrated into any codebase, legacy or new, small or large, and using Dependency Injection or not.  With this in mind Microsoft Fakes is a game changer.  Why a game changer now, presumably years after these features have been available in the wild? 

The answer is widespread availability and acceptance.  Anyone running Visual Studio will be able to run this (hopefully this will be part of the bare SDK as well).  Additionally examples, documentation, blogs and training will be much more readily available.  Faking may very well become a recommended practice along with unit testing at which point it could become as pervasive as general unit testing in .NET solutions.  It’s a lot easier to justify its usage when everyone has access to it, not just those willing to shell out $299 to $799 a seat.

Shims vs Stubs

Let’s take a look at the current MSDN definition for Shims and Stubs

Stub types Stub types make it easy to test code that consumes interfaces or non-sealed classes with overridable methods. A stub of the type T provides a default implementation of each virtual member of T, that is, any non-sealed virtual or abstract method, property, or event. The default behavior can be dynamically customized for each member by attaching a delegate to a corresponding property of the stub. A stub is realized by a distinct type which is generated by the Fakes Framework. As a result, all stubs are strongly typed.

Although stub types can be generated for interfaces and non-sealed classes with overridable methods, they cannot be used for static or non-overridable methods. To address these cases, the Fakes Framework also generates shim types.

Shim types Shim types allow detouring of hard-coded dependencies on static or non-overridable methods. A shim of type T can provide an alternative implementation for each non-abstract member of T. The Fakes Framework will redirect method calls to members of T to the alternative shim implementation. The shim types rely on runtime code rewriting that is provided by a custom profiler.

Delegates Both stub types and shim types allow you to use delegates to dynamically customize the behavior of individual stub members.

Stub types appear to be what most free and/or open source mocking frameworks already do for us today, so there’s really no surprises here.  Shim types on the other hand are where the action is at allowing us to detour static or non-overridable methods. 

MSDN mentions that the detouring in shims does degrade performance slightly.  In the brief amount of testing I’ve done there’s about a 20ms difference between shimmed vs stubbed implementation of the same code, which isn’t a deal breaker in terms of keeping tests fast.  It would make sense the cost could be additive based on the amount of detouring you end up doing.  So if you have the infrastructure to do either or, then pick stubbing over shimming. 

Getting Started with Shims

First off, you’ll need Visual Studio 11, fire it up and create a new C# Class Library project called FakingExample.  For this example I’ve put together a very trivial cart example to play with.

Rename the default class file to CartToShim and modify the code to be as follows:

using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;

namespace FakingExample
{
    public class CartToShim
    {
        public int CartId { get; private set; }
        public int UserId { get; private set; }
        private List<CartItem> _cartItems = new List<CartItem>();
        public ReadOnlyCollection<CartItem> CartItems { get; private set; }
        public DateTime CreateDateTime { get; private set; }

        public CartToShim(int cartId, int userId)
        {
            CartId = cartId;
            UserId = userId;
            CreateDateTime = DateTime.Now;
            CartItems = new ReadOnlyCollection<CartItem>(_cartItems);
        }

        public void AddCartItem(int productId)
        {
            var cartItemId = DataAccessLayer.SaveCartItem(CartId, productId);
            _cartItems.Add(new CartItem(cartItemId, productId));
        }
    }
}

Add the CartItem class.

namespace FakingExample
{
    public class CartItem
    {
        public int CartItemId { get; private set; }
        public int ProductId { get; private set; }

        public CartItem(int cartItemId, int productId)
        {
            CartItemId = cartItemId;
            ProductId = productId;
        }
    }
}

Add the DataAccessLayer class. Don’t worry about the connection string, we’ll never end up hitting it anyway.

using System.Data;
using System.Data.SqlClient;

namespace FakingExample
{
    public static class DataAccessLayer
    {
        public static int SaveCartItem(int cartId, int productId)
        {
            using (var conn = new SqlConnection("RandomSqlConnectionString"))
            {
                var cmd = new SqlCommand("InsCartItem", conn);
                cmd.CommandType = CommandType.StoredProcedure;
                cmd.Parameters.AddWithValue("@CartId", cartId);
                cmd.Parameters.AddWithValue("@ProductId", productId);

                conn.Open();
                return (int)cmd.ExecuteScalar();
            }
        }
    }
}

Next add a Unit Test Project called FakingExample.Tests and rename the default unit test class file to CartToShimTests.

In the FakingExample.Tests project add a reference to the FakingExample project.  You’re solution should look as follows:

Right click on the FakingExample reference in FakingExample.Tests references and select the “Add Fakes Assembly”.

This adds a couple of new items to the project.

The new references add the following types.

The .fakes file created under the Fakes folder turns out to be an xml file.  The file provides a configuration file for the generation of the fakes assembly. I’ll cover more about what can be done in this file later on in the post.  For now here’s a look at the default code generated output.

<Fakes xmlns="http://schemas.microsoft.com/fakes/2011/">
  <Assembly Name="FakingExample"/>
</Fakes>

Now we’re ready to do some faking.  Let’s take a look at unit testing the AddCartItem method.  AddCartItem calls SaveCartItem on DataAccessLayer, which happens to be static.  We’re going to mock out that database call to isolate the logic in AddCartItem in our unit test. Add the code below to CartToShimTests.

using Microsoft.QualityTools.Testing.Fakes;
using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace FakingExample.Tests
{
    [TestClass]
    public class CartToShimTests
    {
        [TestMethod]
        public void AddCartItem_GivenCartAndProduct_ThenProductShouldBeAddedToCart()
        {
            //Create a context to scope and cleanup shims
            using (ShimsContext.Create())
            {
                int cartItemId = 42, cartId = 1, userId = 33, productId = 777;

                //Shim SaveCartItem rerouting it to a delegate which 
                //always returns cartItemId
                Fakes.ShimDataAccessLayer.SaveCartItemInt32Int32 = (c, p) => cartItemId;

                var cart = new CartToShim(cartId, userId);
                cart.AddCartItem(productId);

                Assert.AreEqual(cartId, cart.CartItems.Count);
                var cartItem = cart.CartItems[0];
                Assert.AreEqual(cartItemId, cartItem.CartItemId);
                Assert.AreEqual(productId, cartItem.ProductId);
            }
        }
    }
}

Line 13 creates a ShimsContext , which limits the scope of our shimming.  Line 19 defines our shim/detour for the SaveCartItem method.  Notice how we set the new behavior through a property named SaveCartItemInt32Int32. The Int32Int32 on the end is the type signature of parameters accepted by SaveCartItem. Microsoft Fakes has to keep the generated property names unique and predictable for methods, since they could have overloads or be refactored to have them someday.  Now let’s run it in Unit Test Explorer and see if it passes.

It does indeed pass.  Notice that our shim/detour completely skipped over the SaveCartItem method in DataAccessLayer, if it hadn’t then we would’ve received a nasty exception since “RandomSqlConnectionString” is clearly not a valid connection string . Start to finish, this ends up being pretty easy to setup and use for our simple cart example. 

Stubs Example

For the stubs example our code will be very similar to the shim example however we’ll need to create an ICartSaver interface and inject it into the CartToStub object.  At which point we can stub out ICartSaver and have it return 42 just as we did for shimming.  We’ll manually inject the dependency as opposed to pulling down a DI framework.

Add a new interface ICartSaver to the FakingExample project.

namespace FakingExample
{
    public interface ICartSaver
    {
        int SaveCartItem(int cartId, int productId);
    }
}

Next up add, for completeness (although not necessary) add a CartSaver class to the FakingExample project so we can replicate the implementation of DataAccessLayer.

using System.Data;
using System.Data.SqlClient;

namespace FakingExample
{
    public class CartSaver : ICartSaver
    {
        public int SaveCartItem(int cartId, int productId)
        {
            using (var conn = new SqlConnection("RandomSqlConnectionString"))
            {
                var cmd = new SqlCommand("InsCartItem", conn);
                cmd.CommandType = CommandType.StoredProcedure;
                cmd.Parameters.AddWithValue("@CartId", cartId);
                cmd.Parameters.AddWithValue("@ProductId", productId);

                conn.Open();
                return (int)cmd.ExecuteScalar();
            }
        }
    }
}

Create a new CartToStub class as follows similar to CartToShim but allowing for manual dependency injection of ICartSaver in the constructor:

using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;

namespace FakingExample
{
    public class CartToStub
    {
        public int CartId { get; private set; }
        public int UserId { get; private set; }
        private List<CartItem> _cartItems = new List<CartItem>();
        public ReadOnlyCollection<CartItem> CartItems { get; private set; }
        public DateTime CreateDateTime { get; private set; }
        private ICartSaver _cartSaver;

        public CartToStub(int cartId, int userId, ICartSaver cartSaver)
        {
            CartId = cartId;
            UserId = userId;
            CreateDateTime = DateTime.Now;
            _cartSaver = cartSaver;
            CartItems = new ReadOnlyCollection<CartItem>(_cartItems);
        }

        public void AddCartItem(int productId)
        {
            var cartItemId = _cartSaver.SaveCartItem(CartId, productId);
            _cartItems.Add(new CartItem(cartItemId, productId));
        }
    }
}

Moving back over to the FakingExample.Tests project, add a new unit test file named CartToStubTests.  Create/Modify the AddCartItem_GivenCartAndProduct_ThenProductShouldBeAddedToCart method to take into account the new changes.

using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace FakingExample.Tests
{
    [TestClass]
    public class CartToStubTests
    {
        [TestMethod]
        public void AddCartItem_GivenCartAndProduct_ThenProductShouldBeAddedToCart()
        {
            int cartItemId = 42, cartId = 1, userId = 33, productId = 777;

            //Stub ICartSaver and customize the behavior via a 
            //delegate, ro return cartItemId
            var cartSaver = new Fakes.StubICartSaver();
            cartSaver.SaveCartItemInt32Int32 = (c, p) => cartItemId;

            var cart = new CartToStub(cartId, userId, cartSaver);
            cart.AddCartItem(productId);

            Assert.AreEqual(cartId, cart.CartItems.Count);
            var cartItem = cart.CartItems[0];
            Assert.AreEqual(cartItemId, cartItem.CartItemId);
            Assert.AreEqual(productId, cartItem.ProductId);
        }
    }
}

Run the unit tests once more to see that everything’s passing.

Just as with shims, start to finish, this ends up being pretty easy overall for our simple cart example.

The Fakes Xml File

The current MSDN library documentation details the nature of the .fakes xml file as follows:

The generation of stub types is configured in an XML file that has the .fakes file extension. The Fakes framework integrates in the build process through custom MSBuild tasks and detects those files at build time. The Fakes code generator compiles the stub types into an assembly and adds the reference to the project.

The .fakes file provides fine grained control of how stub and shim generation work for a particular assembly.  Luckily enough the file has intellisense and pretty good descriptions when hovering, so exploration of features is rather straight forward.  Expanding out all attributes and elements using intellisense provides us with the following structures.

<Fakes xmlns="http://schemas.microsoft.com/fakes/2011/">
  <Assembly Name="" Location="" Version="" x86=""/>

  <StubGeneration Disable="" SkipVirtualIndexers="" SkipVirtualMethods="">
    <Clear />
    <Add AbstractClasses="" FullName="" Interfaces="" Namespace="" TypeName=""/>
    <Remove AbstractClasses="" FullName="" Interfaces="" Namespace="" Obsolete="" TypeName=""/>
  </StubGeneration>

  <ShimGeneration Disable="">
    <Clear />
    <Add FullName="" Namespace="" TypeName=""/>
    <Remove FullName="" Namespace="" Obsolete="" TypeName=""/>
  </ShimGeneration>

  <Compilation Debug="" DisableCodeContracts="" KeyFile="" ProjectTemplate="">
    <COMReference Guid="" VersionMajor="" VersionMinor="" WrapperTool=""/>
    <Property Condition="" Name="" />
  </Compilation>
</Fakes>

Based on this we see the following features:

• Either shimming or stubbing can be completely turned off
• Shims and stubs can be filtered such that only specific items from an assembly are shimmed and/or stubbed
• Strong signing can be overridden via the KeyFile attribute, based on the MSDN docs the Fakes framework will automatically sign the .Fakes assembly with the same key the source assembly was signed with unless overridden here
• There’s a facility to reference/deal with a COM component with COMReference if necessary.  Hopefully it won’t be…

Aside from items within the compilation element everything is along the lines of what we’d expect to be available here.  I imagine in most circumstances this file won’t need to be touched, however if you’re faking a larger library like mscorlib, then it would seem almost mandatory to filter the types generated otherwise the compiler could be chewing on it for a while.  The classic DateTime.Now shimming examples should probably be doing this type of filtering.

Conclusion

All in all I’m really excited about Microsoft Fakes.  It has the capacity to drive change in the .NET testing landscape similarly to how adding unit testing to Visual Studio (back in the 2005 version I believe) did so.  Widespread inclusion, usage and education of faking/mocking will be very beneficial for the community and will help drive innovation of testing techniques. Projects which would’ve been considered difficult if not impossible to add some level of unit testing to, without large amounts of refactoring, can now be unit tested easily.  Microsoft Fakes is a definitive win in my book.

 

The code for this post is available on GitHub