Despite having been around for several years I hadn't heard about Microsoft's Moles framework until a few months ago when one of my teammates mentioned it during the 2011 Indy GiveCamp. I was interested in learning more about it at the time but given how we were running on caffeine I'm not surprised I forgot about it until he mentioned it again a few weeks ago. This time I was much more alert and started reading about it almost immediately. After seeing what Moles offered and not finding much in the way of resources for it on the Web I knew I needed to spread the word.
Note: For this article I used version 0.94 of the Moles Framework.
What is the Moles Framework?
Microsoft Moles is a project from Microsoft Research that came about because of work being done on Pex (another MS Research initiative). The Microsoft Moles Reference Manual describes Moles this way:
The Microsoft Moles 2010 add-in for Microsoft Visual Studio 2010 is a lightweight framework for creating delegate-based test stubs and detours in .NET Framework applications.
In other words, Moles is, in a sense, Microsofts answer to other mocking frameworks like Rhino Mocks or Moq but Moles differs from the other frameworks in a few ways. One important distinction is that the Moles Framework does not provide any validation mechanisms of its own. In that regard Moles is not so much a testing framework as it is an isolation framework intended for use in conjunction with other testing frameworks such as MSTest or NUnit.
Note: Although Moles started as part of Pex I'm not going to discuss Pex here.
Isolation Techniques
The Moles framework provides two isolation techniques:
Both types allow us to work around dependencies in different ways and have very different use cases.
Stub Types
Stub types are much like traditional stub or mock objects in that they allow us to test code that relies on some provided contract. Stubs are based on inheritance so they can only be used with interfaces or non-sealed classes with virtual members. Sometimes the code we want to test relies on static or non-overridable methods that cant be stubbed. In those scenarios we need to use mole types instead.
Mole Types
Mole types use a profiler to rewrite existing method bodies thereby allowing us to circumvent (or detour in Moles parlance) dependencies on static or non-overridable methods. Mole types are generally most useful for isolating dependencies in third-party libraries. Unfortunately, runtime rewriting does introduce some performance issues so moles should generally be used sparingly.
Note: At the time of this writing the Moles framework does not generate detour properties for auto-implemented properties although this could change in a future release (.
Choosing an Approach
With both stub types and mole types at our disposal it is important to understand when to use each. In general Microsoft recommends that we favor stubs over moles whenever possible. Stub types are much lighter than moles and operate over native language features. Some instances where mole types are required are:
- Private methods
- Static methods
- Sealed types
- Static constructors/finalizers
- 3rd party libraries without testable APIs
Getting Started
Installation
The Moles framework is available through the extension gallery as part of Pex (White box Unit Testing for .NET) or individually. It can also be downloaded directly from the Microsoft Research site. Regardless of which option you choose the functionality is made available to Visual Studio as an add-in.
Generating Stubs and Moles
As previously discussed, the Moles framework automatically generates the appropriate stub and mole types. In order for it to generate the types though we need to first tell it which assemblies to inspect via a .moles file.
The quickest way to get started is to expand the References node in the test project, select the assembly being tested, and choose Add Moles Assembly from the context menu. This will add a simple .moles file and automatically hook up the build action for the file. When the project is built (or the .moles file is saved) Moles will generate an assembly with the appropriate isolation types and automatically reference it along with any other necessary assemblies.
Note: The Microsoft Moles Reference Manual describes adding the .moles file through the Add New Item dialog. I couldn't find these templates but did find the Add Moles Assembly context menu item on individual references. It's also possible to manually add a .moles file and set the build action to Moles to achieve the same behavior.
Should it be necessary to generate isolation types for the types defined in mscorlib (i.e.: DateTime) we can add a moles assembly for it by right-clicking on the References folder in the test project and selecting the "Add Moles Assembly for mscorlib" option.
Basic Configuration
The .moles file is the heart of the Moles Framework configuration. In its simplest form the .moles file merely identifies an assembly that will be inspected for type generation.
In this example weve instructed the system to generate the isolation types for all types defined in the Examples assembly.
In addition to identifying the assembly the .moles file can also include additional configuration information for filtering which types will be stubbed and/or moled and strong name signing. Well take a closer look at these topics later on in the Advanced Configuration section.
Naming Conventions
Once the types have been generated they can be referenced in your tests. The Moles framework follows some basic naming conventions to make the types easier to find and identify in your code. The full list of conventions is available in Appendix B of the Microsoft Moles Reference Manual so Ill only note a few highlights here.
Great model and animation, but could have been better. I assume the maker is a starter. When you get better, make another one :)