Isolate code under test with Microsoft Fakes

Applies to: yesVisual Studio noVisual Studio for Mac noVisual Studio Code

Microsoft Fakes helps you isolate the code you're testing by replacing other parts of the application with stubs or shims. The stubs and shims are small pieces of code that are under the control of your tests. By isolating your code for testing, you know that if the test fails, the cause is there and not somewhere else. Stubs and shims also let you test your code even if other parts of your application aren't working yet.

Fakes come in two flavors:

  • A stub replaces a class with a small substitute that implements the same interface. To use stubs, you have to design your application so that each component depends only on interfaces, and not on other components. (By "component" we mean a class or group of classes that are designed and updated together and typically contained in an assembly.)

  • A shim modifies the compiled code of your application at runtime so that instead of making a specified method call, it runs the shim code that your test provides. Shims can be used to replace calls to assemblies that you can't modify, such as .NET assemblies.

    Fakes replace other components


  • Visual Studio Enterprise
  • A .NET Framework project
  • .NET Core, .NET 5.0 or later, and SDK-style project support previewed in Visual Studio 2019 Update 6, and is enabled by default in Update 8. For more information, see Microsoft Fakes for .NET Core and SDK-style projects.


Profiling with Visual Studio isn't available for tests that use Microsoft Fakes.

Choose between stub and shim types

Typically, you would consider a Visual Studio project to be a component, because you develop and update those classes at the same time. You would consider using stubs and shims for calls that the project makes to other projects in your solution, or to other assemblies that the project references.

You can use stubs for calls within your Visual Studio solution, and shims for calls to other referenced assemblies. This is because within your own solution it's good practice to decouple the components by defining interfaces in the way that stubbing requires. But external assemblies such as System.dll typically aren't provided with separate interface definitions, so you must use shims instead.

Other considerations are:

Performance. Shims run slower because they rewrite your code at runtime. Stubs don't have this performance overhead and are as fast as virtual methods can go.

Static methods, sealed types. You can only use stubs to implement interfaces. Therefore, stub types can't be used for static methods, non-virtual methods, sealed virtual methods, methods in sealed types, and so on.

Internal types. Both stubs and shims can be used with internal types that are made accessible by using the assembly attribute InternalsVisibleToAttribute.

Private methods. Shims can replace calls to private methods if all the types on the method signature are visible. Stubs can only replace visible methods.

Interfaces and abstract methods. Stubs provide implementations of interfaces and abstract methods that can be used in testing. Shims can't instrument interfaces and abstract methods, because they don't have method bodies.

We recommend you use stub types to isolate from dependencies within your codebase. You can do this by hiding the components behind interfaces. You can use shim types to isolate from third-party components that don't provide a testable API.

Get started with stubs

For a more detailed description, see Use stubs to isolate parts of your application from each other for unit testing.

  1. Inject interfaces

    To use stubs, you have to write the code you want to test in such a way that it doesn’t explicitly mention classes in another component of your application. By "component" we mean a class or classes that are developed and updated together, and typically contained in one Visual Studio project. Variables and parameters should be declared by using interfaces, and instances of other components should be passed in or created by using a factory. For example, if StockFeed is a class in another component of the application, then this is considered bad:

    return (new StockFeed()).GetSharePrice("COOO"); // Bad

    Instead, you can define an interface that can be implemented by the other component, and can also be implemented by a stub for test purposes:

    public int GetContosoPrice(IStockFeed feed) => feed.GetSharePrice("COOO");
  2. Add Fakes Assembly

    1. In Solution Explorer,

      • For an older .NET Framework Project (non-SDK style), expand your unit test project's References node.

      • For an SDK-style project targeting .NET Framework, .NET Core, or .NET 5.0 or later, expand the Dependencies node to find the assembly you would like to fake under Assemblies, Projects, or Packages.

      • If you're working in Visual Basic, select Show All Files in the Solution Explorer toolbar to see the References node.

    2. Select the assembly that contains the class definitions for which you want to create stubs. For example, if you want to shim DateTime, select System.dll.

    3. On the shortcut menu, select Add Fakes Assembly.

  3. In your tests, construct instances of the stub and provide code for its methods:

    class TestStockAnalyzer
        public void TestContosoStockPrice()
          // Arrange:
            // Create the fake stockFeed:
            IStockFeed stockFeed =
                 new StockAnalysis.Fakes.StubIStockFeed() // Generated by Fakes.
                         // Define each method:
                         // Name is original name + parameter types:
                         GetSharePriceString = (company) => { return 1234; }
            // In the completed application, stockFeed would be a real one:
            var componentUnderTest = new StockAnalyzer(stockFeed);
          // Act:
            int actualValue = componentUnderTest.GetContosoPrice();
          // Assert:
            Assert.AreEqual(1234, actualValue);

    The special piece of magic here is the class StubIStockFeed. For every interface in the referenced assembly, the Microsoft Fakes mechanism generates a stub class. The name of the stub class is derived from the name of the interface, with "Fakes.Stub" as a prefix, and the parameter type names appended.

    Stubs are also generated for the getters and setters of properties, for events, and for generic methods. For more information, see Use stubs to isolate parts of your application from each other for unit testing.

Get started with shims

(For a more detailed description, see Use shims to isolate your application from other assemblies for unit testing.)

Suppose your component contains calls to DateTime.Now:

// Code under test:
    public int GetTheCurrentYear()
       return DateTime.Now.Year;

During testing, you would like to shim the Now property, because the real version inconveniently returns a different value at every call.

To use shims, you don't have to modify the application code or write it in a particular way.

  1. Add Fakes Assembly

    In Solution Explorer, open your unit test project's references and select the reference to the assembly that contains the method you want to fake. In this example, the DateTime class is in System.dll. To see the references in a Visual Basic project, select Show All Files.

    Select Add Fakes Assembly.

  2. Insert a shim in a ShimsContext

    public class TestClass1
            public void TestCurrentYear()
                int fixedYear = 2000;
                // Shims can be used only in a ShimsContext:
                using (ShimsContext.Create())
                  // Arrange:
                    // Shim DateTime.Now to return a fixed date:
                    System.Fakes.ShimDateTime.NowGet =
                    () =>
                    { return new DateTime(fixedYear, 1, 1); };
                    // Instantiate the component under test:
                    var componentUnderTest = new MyComponent();
                  // Act:
                    int year = componentUnderTest.GetTheCurrentYear();
                  // Assert:
                    // This will always be true if the component is working:
                    Assert.AreEqual(fixedYear, year);

    Shim class names are made up by prefixing Fakes.Shim to the original type name. Parameter names are appended to the method name. (You don't have to add any assembly reference to System.Fakes.)

The previous example uses a shim for a static method. To use a shim for an instance method, write AllInstances between the type name and the method name:

System.IO.Fakes.ShimFile.AllInstances.ReadToEnd = ...

(There's no 'System.IO.Fakes' assembly to reference. The namespace is generated by the shim creation process. But you can use 'using' or 'Import' in the usual way.)

You can also create shims for specific instances, for constructors, and for properties. For more information, see Use shims to isolate your application from other assemblies for unit testing.

Using Microsoft Fakes in the CI

Microsoft Fakes Assembly Generation

Since Microsoft Fakes requires Visual Studio Enterprise, the generation of Fakes Assemblies requires that you build your project using Visual Studio Build Task.


An alternative to this is to check your Fakes Assemblies into the CI and use the MSBuild Task. When you do this, you need to ensure that you've an assembly reference to the generated Fakes assembly in your test project, similar to the following code snippet :

<Project Sdk="Microsoft.NET.Sdk">
        <Reference Include="FakesAssemblies\System.Fakes.dll"/>

This reference is required to be added manually, specifically to SDK-style projects (.NET Core, .NET 5.0, and .NET Framework) because we've moved to implicitly adding assembly references to your test project. If you follow this method, you need to ensure the fakes assembly is updated when the parent assembly changes.

Running Microsoft Fakes tests

As long as Microsoft Fakes assemblies are present in the configured FakesAssemblies directory (The default being $(ProjectDir)FakesAssemblies), you can run tests using the vstest task.

Distributed testing with the vstest task .NET Core and .NET 5.0 or later projects using Microsoft Fakes requires Visual Studio 2019 Update 9 Preview 20201020-06 and higher.

Transitioning your .NET Framework test projects that use Microsoft Fakes to SDK-style .NET Framework, .NET Core, or .NET 5.0 projects or later projects

You'll need minimal changes in your .NET Framework set up for Microsoft Fakes to transition to .NET Core or .NET 5.0. The cases that you would have to consider are:

  • If you're using a custom project template, you need to ensure that it's SDK-style and builds for a compatible target framework.

  • Certain types exist in different assemblies in .NET Framework and .NET Core/.NET 5.0 (for example, System.DateTime exists in System/mscorlib in .NET Framework, and in System.Runtime in .NET Core and .NET 5.0), and in these scenarios you need to change the assembly being faked.

  • If you have an assembly reference to a fakes assembly and the test project, you might see a build warning about a missing reference similar to:

    (ResolveAssemblyReferences target) ->
    warning MSB3245: Could not resolve this reference. Could not locate the assembly "AssemblyName.Fakes". Check to make sure the assembly exists on disk.
    If this reference is required by your code, you may get compilation errors.

    This warning is because of necessary changes made in Fakes generation and can be ignored. It can be avoided by removing the assembly reference from the project file, because we now implicitly add them during the build.

Microsoft Fakes support

Microsoft Fakes in older projects targeting .NET Framework (non-SDK style).

  • Microsoft Fakes assembly generation is supported in Visual Studio Enterprise 2015 and higher.
  • Microsoft Fakes tests can run with all available Microsoft.TestPlatform NuGet packages.
  • Code coverage is supported for test projects using Microsoft Fakes in Visual Studio Enterprise 2015 and higher.

Microsoft Fakes in SDK-style .NET Framework, .NET Core, and .NET 5.0 or later projects

  • Microsoft Fakes assembly generation previewed in Visual Studio Enterprise 2019 Update 6 and is enabled by default in Update 8.
  • Microsoft Fakes tests for projects that target .NET Framework can run with all available Microsoft.TestPlatform NuGet packages.
  • Microsoft Fakes tests for projects that target .NET Core and .NET 5.0 or later can run with Microsoft.TestPlatform NuGet packages with versions 16.9.0-preview-20210106-01 and higher.
  • Code coverage is supported for test projects targeting .NET Framework using Microsoft Fakes in Visual Studio Enterprise version 2015 and higher.
  • Code coverage support for test projects targeting .NET Core and .NET 5.0 or later using Microsoft Fakes is available in Visual Studio 2019 update 9 and higher.

In this section

Use stubs to isolate parts of your application from each other for unit testing

Use shims to isolate your application from other assemblies for unit testing

Code generation, compilation, and naming conventions in Microsoft Fakes