When I see the MSpec code, I think about it being an internal DSL for doing the testing, and I start to think that perhaps it should just go ahead and be it’s own language instead of trying to live inside of C#. On the other hand, I wonder about the value of using another language to unit test C# code…

I think John was spot-on with his instinct – in my opinion, MSpec is an internal DSL.  I also think that is the beauty of the framework.  Domain-specific languages are meant to solve a target problem in a particular domain.  MSpec’s problem domain is testing .NET code.  By convention, it constrains you to its limited language to help you test your code in a meaningful yet powerful manner.

What is an Internal DSL?

According to Martin Fowler:

“Internal DSLs are particular ways of using a host language to give the host language the feel of a particular language…Internal DSLs are also referred to as embedded DSLs or FluentInterfaces”  (from Bliki article: Domain Specific Language)

“Internal DSLs use the same general purpose programming language that the wider application uses, but uses that language in a particular and limited style.”
(from DSL-WIP section: Using Domain Specific Languages)

But, as John wondered, is there value in using another language (external DSL) to test C# code?

Perhaps.  Yet, I believe there is more value in using external DSLs to test user interfaces (e.g., WatiR, WatiN, and Selenium), or for build scripting (e.g.,Rake, psake).

Let’s look at that question a little differently: Is there value in using an internal DSL (like MSpec) to test C# code?

To that I give a resounding YES! MSpec’s host language is C#…which provides great value to me.  I get all the benefits of intellisense, refactoring, and (R#) navigation in my IDE.  I don’t have to worry about the impedance mismatch between my code and an external DSL.

You Probably Use DSLs All the Time

In fact, I use several DSLs every day when I code.

Consider the following table of frameworks. You may not have thought any of these in the context of a domain-specific language, but each has a specific purpose with its own limited language constructs. Some are internal, some external.

When considering a framework within your host language: If the framework has a fluent interface with language devoted to a specific problem domain, it is probably an internal DSL.

So is MSpec an internal DSL? Yes.

And is that okay? Definitely.

Further Reading

Check out Martin Fowler’s articles on domain-specific languages:

http://www.martinfowler.com/bliki/DomainSpecificLanguage.html
http://martinfowler.com/dslwip/UsingDsls.html
http://martinfowler.com/dslwip/InternalOverview.html

From my unscientific observation, developers either love or hate MSpec.  For those that hate MSpec, I wonder if it is the grammatical syntax or the lambda-expression style creating the aversion.  Some even expound MSpec as cryptic and cumbersome.  This seems to be a common complaint – one I hope to address in this post.

I find that those drawn to MSpec have experienced an evolution of testing/specification styles, influenced partially by the community and partially by frameworks they have used.  At the very least, this has been my experience as I have transitioned from xUnit frameworks.

Conventions of MSpec

I particularly like the conventions MSpec encourages using its four delegate types:

Establish:

• Provides setup (context) for the specification
• One per class (but not required)
• “Unlimited” per specification or inheritance chain
• Runs down the inheritance chain prior to the Because delegate

Because:

• The action/event being tested
• One per specification

It:

• An assertion (usually extension methods/fluent interfaces based on NUnit/xUnit Assert classes)
• “Unlimited” per specification/class
• Can be “hosted” in a Behavior class
• Runs after the Because
• Can be reused when placed in a Behavior class
• If body of delegate is missing, will mark as “Ignored” or “Not Implemented” in a test runner

Cleanup:

• Provides teardown for the specification
• One per class (but not required)
• “Unlimited” per specification or inheritance chain
• Runs up the inheritance chain after the It delegates are completed

MSpec also has one other delegate type (Behaves_like<T>) and several optional attributes available (Subject, Tag, Ignore, Behavior).  [Subject] provides additional information about the specification. [Tag] is similar to the [Category] attribute in NUnit.  [Ignore] is self-explanatory. [Behavior] marks a class made up entirely of assertions (It delegates).  Behaves_like<T> is a delegate type that can be included in a specification block taking the place of a set of assertions (It delegates).

NUnit – TestFixture-Per-Class

I have gone from using a TestFixture-Per-Class style to a behavior-driven/context-specification style.  I would like to use the standard HomeController, created in an ASP.NET MVC 1.0 project, as an example class to explore this evolution. 

In my TestFixture-Per-Class days, I may have tested the Index action as follows:

[TestFixture]
public class HomeControllerTests
{
    [Test]
    public void IndexActionTest()
    {
        var controller = new HomeController();
        var result = (ViewResult) controller.Index();
        Assert.AreEqual("Welcome to ASP.NET MVC!", result.ViewData["Message"]);
    }
}

I do like the simplicity of the code.  One line to set up the test, one to execute, and one to assert.  There is a little ceremony involved with marking the class and methods with the NUnit attributes.  With this simple test, it is easy to distinguish the setup code from the assertion; yet, a more complex test would make scanning the test more difficult.  Comments can help, but tend to just add noise.

NUnit – Arrange/Act/Assert

With the advent of BDD, I started naming my classes and expectations as inspired by BDD syntax.  I might have used the [SetUp] attribute or a base class to organize my test code in a style similar to the following:

[TestFixture]
public class when_I_go_to_the_home_page: AAA
{
    private HomeController _controller;
    private ViewResult _result;

    protected override void Arrange()
    {
        _controller = new HomeController();
    }
    protected override void Act()
    {
        _result = (ViewResult)_controller.Index();
    }

    [Test]
    public void then_the_welcome_message_should_be_displayed()
    {
        _result.ViewData["Message"].ShouldEqual("Welcome to ASP.NET MVC!");
    }
}

This actively separates out the different responsibilities of the test.  You can see where the setup code is, as well as the action being tested.  The assertion is the only line of code in the test method.  There is still ceremony involved with the attributes.  Plus, we have added a little more ceremony and noise with the Arrange() and Act() overrides.  This simple test does not necessarily need the parts split in this manner, but it would help with more complex scenarios.  Additionally, the assertion is using extension methods based on the NUnit Assert classes which provides a little more clarity to the assertion.

MSpec

Once started down the path of a behavior-driven (or context/specification) style, I started looking at frameworks devoted to that style.  MSpec is one of those frameworks.  Here is the Index action specification in MSpec:

public class when_I_go_to_the_home_page
{
    Establish context = () =>  _controller = new HomeController();
    Because of = () => _result = (ViewResult)_controller.Index();
    It should_display_the_welcome_message = () => _result.ViewData["Message"].ShouldEqual("Welcome to ASP.NET MVC!"); 

    static HomeController _controller;
    static ViewResult _result;
}

If you look closely, this specification is very similar to the first NUnit test.  However, there are no attributes to specify and the specification has a distinct functional separation.  The Establish/Because/It syntax is analogous to the Given/When/Then language used in user stories or Arrange/Act/Assert syntaxes used in the previous example.  In my opinion, this has less noise than the test using NUnit with an AAA base class – even while using the lambda delegate syntax.

MSpec – SpecificationFor<ClassUnderTest>

I often use a base class to handle some of my setup code. Using StructureMap and RhinoMocks, it generates and injects proxied dependencies for the given class.  In this example, I have no dependencies to wire up, but I think you can still see the benefits.

public class when_I_go_to_the_home_page : SpecificationFor<HomeController>
{
    Because of = () => _result = (ViewResult)ClassUnderTest.Index();
    It should_display_the_welcome_message = () => _result.ViewData["Message"].ShouldEqual("Welcome to ASP.NET MVC!"); 

    static ViewResult _result;
}

The Establish delegate is not needed in this specification, because I have wired up the class via the base class.  I feel this version is most clear and concise of all the examples, and neither cryptic nor cumbersome  If you are interested in the SpecificationFor<T> base class and the supporting components, check out my previous post. 

Looking to the Future

I hope that this post has shown that MSpec does not have to be cryptic, nor cumbersome.  If you considered it as such before, please take another critical look.

Given the evolving state of the craft, I am sure that my test/specification style will continue to gradually change.  I am sure that my framework of choice will eventually change as well, especially as each framework is extended and challenged by others.  Hopefully, you can be open to evolving your style as well.

I have been using StructureMap.AutoMocking with MSpec (Machine.Specifications) and Rhino.Mocks for a few months now.  Although I am very comfortable with the patterns that emerge from using the frameworks together, introducing StructureMap.Automocking to other developers is sometimes challenging.

When viewing a specification or test set up with the Rhino.Mocks or Moq automocking container, what is being tested is not readily apparent.  Once the concept is explained and demonstrated, these same developers seem to have no issue with maintaining the specifications/tests.

I decided to wrap the details of the container to make the intention clearer and explanation easier.  I have started using this wrapper in my projects, and have found it makes building up specifications more efficient in my daily coding.

Let me know whether this is useful to you, or how it could be made more useful.

The Examples

Let’s contrive an example.  We’ll say we have a coffee machine that grinds its own beans before brewing. However, the hopper has to have beans before starting the grind.  Here is the basic specification:

We could start without a container, using Rhino.Mocks to build up the CoffeeMachine dependencies manually:

[Subject(typeof(CoffeeMachine),"using vanilla Rhino.Mocks")]
public class Example01_when_preparing_coffee_grounds
{
    Establish context = () =>
        {
            Grinder = MockRepository.GenerateMock<IGrinder>();
            Hopper = MockRepository.GenerateMock<IHopper>();
            Hopper.Expect(x => x.HasBeans()).Return(true);
            CoffeeMachine = new CoffeeMachine(Grinder, Hopper);
        };

    Because of = () => _coffeeMachine.PrepareCoffeeGrounds(12);

    It should_check_if_hopper_has_beans = () => Hopper.VerifyAllExpectations();
    It should_grind_coffee = () => Grinder.AssertWasCalled(x => x.Grind(12));

    static IGrinder Grinder;
    static IHopper Hopper;
    static CoffeeMachine CoffeeMachine;
}

For those of you not familiar with the MSpec style, please refer to the following posts:

• Make BDD Your BFF
• Step by Step to Using MSpec (Machine.Specifications) with ReSharper
• MSpec – Take 2
• MSpec BDD framework installer
• Updated! From the Morning Brew #487: BDD with MSpec and Rhino Auto Mocks, parts  1, 2, and 3
  Here is the same specification using the RhinoAutoMocker<T> class provided by StructureMap.AutoMocking:

[Subject(typeof(CoffeeMachine),"using RhinoAutoMocker<CoffeeMachine>")]
public class Example02_when_preparing_coffee_grounds
{
    Establish context = () =>
        {
            CoffeeMachine = new RhinoAutoMocker<CoffeeMachine>();
            Grinder = CoffeeMachine.Get<IGrinder>();
            Hopper = CoffeeMachine.Get<IHopper>();
            Hopper.Expect(x => x.HasBeans()).Return(true);
        };

    Because of = () => v.ClassUnderTest.PrepareCoffeeGrounds(12);

    It should_check_if_hopper_has_beans = () => Hopper.VerifyAllExpectations();
    It should_grind_coffee = () => Grinder.AssertWasCalled(x => x.Grind(12));

    static IGrinder Grinder;
    static IHopper Hopper;
    static RhinoAutoMocker<CoffeeMachine> CoffeeMachine;
}

Although I think this looks cleaner, the initialization of CoffeeMachine causes some confusion. Unfortunately, a common question would be, “Is RhinoAutoMocker<CoffeeMachine> creating a mocked version of CoffeeMachine?” Well, not exactly.

RhinoAutoMocker is an implementation of the AutoMocker base class which uses StructureMap to fill dependencies.  The RhinoAutoMocker implementation of the container uses Rhino.Mocks to generate all of dependencies of the target class, whereas the MoqAutoMocker implementation uses Moq.  (Optionally, the target class can be partially mocked in order to further isolate behavior.)  We then retrieve the class under test (in this case, CoffeeMachine) and its dependencies (IGrinder and IHopper) from the container for use.

If you do not need to setup any expectations in the specification, there is no need to retrieve the dependency from the container.  However, in this specification, we need both dependencies.

(Incidentally, I do not like the ClassUnderTest name.  I may end up changing this to Instance, ClassInstance, TargetClass, or something similar.  Suggestions?)

By moving the initialization of the RhinoAutoMocker to a base class, some of the chattiness of the context can be hidden.

[Subject(typeof(CoffeeMachine),"using RhinoAutoMocker base")]
public class Example03_when_preparing_coffee_grounds : with_rhinoautomocker
{
    Establish context = () => Hopper.Expect(x => x.HasBeans()).Return(true);

    Because of = () => CoffeeMachine.ClassUnderTest.PrepareCoffeeGrounds(12);

    It should_check_if_hopper_has_beans = () => Hopper.VerifyAllExpectations();
    It should_grind_coffee = () => Grinder.AssertWasCalled(x => x.Grind(12));

}

[Subject("using RhinoAutoMocker<T>")]
public class with_rhinoautomocker
{
    protected static IGrinder Grinder;
    protected static IHopper Hopper;
    protected static RhinoAutoMocker<CoffeeMachine> CoffeeMachine;

    Establish context = () =>
    {
        CoffeeMachine = new RhinoAutoMocker<CoffeeMachine>();
        Grinder = CoffeeMachine.Get<IGrinder>();
        Hopper = CoffeeMachine.Get<IHopper>();
    };
}

However, we are still initializing and accessing the class in a less than optimal manner.To make the usage of the container a little more seamless, I decided to create a wrapper and factory for the AutoMocker.  Setup of the dependencies and expectations are done through an AutoMocker wrapper object.  The instance of the class under test is accessed through a ClassUnderTest object.

The Result

The specification (and base class) now look like this:

[Subject(typeof(CoffeeMachine),"using coffee machine base")]
public class Example05_when_preparing_coffee_grounds : with_coffee_machine
{
    Establish context = () => Hopper.Expect(x => x.HasBeans()).Return(true);

    Because of = () => ClassUnderTest.PrepareCoffeeGrounds(12);

    It should_check_if_hopper_has_beans = () => Hopper.VerifyAllExpectations();
    It should_grind_coffee = () => Grinder.AssertWasCalled(x => x.Grind(12));
}

[Subject("using SpecificationFor<CoffeeMachine>")]
public class with_coffee_machine : SpecificationFor<CoffeeMachine>
{
    protected static IGrinder Grinder;
    protected static IHopper Hopper;

    public with_coffee_machine
    {
        Grinder = AutoMocker.Get<IGrinder>();
        Hopper = AutoMocker.Get<IHopper>();
    }
}

As you can see, the base class inherits from SpecificationFor<T>.  The default constructor uses Rhino.Mocks(MockMode.AAA) to generate the dependencies.  It then exposes a AutoMocker object, which is just the wrapper around the AutoMocker base class.  It also exposes a ClassUnderTest object.  If I didn’t need to use the dependencies, I could make the Example05_when_preparing_coffee_grounds class inherit from SpecificationFor<CoffeeMachine> instead of inheriting from the base class.

The Code

I have included the code for the wrapper below for your review.  The code and six examples are available on my Google code repository. The repository also includes an example using the MoqAutoMocker.  All the examples have the same assertions, but are built up using the different techniques.

namespace CodeProgression.Framework.Testing
{
    public abstract class SpecificationFor<T> where T: class
    {
        protected static ClassUnderTest<T> Factory;

        // UPDATE 2009-12-21:
        //   Moved initialization here
        protected static T ClassUnderTest {get {return AutoMocker.Instance;} }

        protected SpecificationFor()
        {
            AutoMocker = AutoMockFactory.CreateTarget<T>();

            // UPDATE 2009-12-21:
            //    Initializing here prevented injected dependencies!
            // AutoMocker.PartialMockTheClassUnderTest();
            // ClassUnderTest = AutoMocker.Instance;
        }

        protected SpecificationFor(AutoMockType type)
        {
            AutoMocker = AutoMockFactory.CreateTarget<T>(type);

            // UPDATE 2009-12-21:
            // Initializing here prevented injected dependencies!
            // AutoMocker.PartialMockTheClassUnderTest();
            // ClassUnderTest = AutoMocker.Instance;
        }
    }

    public static class AutoMockFactory
    {
        public static ClassUnderTest<TARGETCLASS> CreateTarget<TARGETCLASS>() where TARGETCLASS : class
        {
            return CreateTarget<TARGETCLASS>(AutoMockType.RhinoMocksAAA);
        }

        public static ClassUnderTest<TARGETCLASS> CreateTarget<TARGETCLASS>(AutoMockType framework) where TARGETCLASS : class
        {
            AutoMocker<TARGETCLASS> mocker;
            ServiceLocator serviceLocator;
            switch (framework)
            {
                case AutoMockType.RhinoMocksAAA:
                    mocker = new RhinoAutoMocker<TARGETCLASS>(MockMode.AAA);
                    serviceLocator = new RhinoMocksAAAServiceLocator();
                    break;
                case AutoMockType.RhinoMocksClassic:
                    mocker = new RhinoAutoMocker<TARGETCLASS>(MockMode.RecordAndReplay);
                    serviceLocator = new RhinoMocksClassicServiceLocator();
                    break;
                case AutoMockType.Moq:
                    mocker = new MoqAutoMocker<TARGETCLASS>();
                    serviceLocator = new MoqServiceLocator();
                    break;
                default:
                    throw new ArgumentOutOfRangeException("framework");
            }
            return new ClassUnderTest<TARGETCLASS>(mocker, serviceLocator);
        }
    }

    public enum AutoMockType
    {
        Moq,
        RhinoMocksAAA,
        RhinoMocksClassic
    }

    public class ClassUnderTest<TARGETCLASS> where TARGETCLASS : class
    {
        readonly IAutoMocker<TARGETCLASS> _mocker;
        readonly ServiceLocator _serviceLocator;

        public ClassUnderTest(IAutoMocker<TARGETCLASS> mocker, ServiceLocator serviceLocator)
        {
            _mocker = mocker;
            _serviceLocator = serviceLocator;
        }

        public AutoMockedContainer Container
        {
            get { return _mocker.Container; }
        }

        public TARGETCLASS Instance
        {
            get { return _mocker.ClassUnderTest; }
        }

        public void MockObjectFactory()
        {
            _mocker.MockObjectFactory();
        }

        public void PartialMockTheClassUnderTest()
        {
            _mocker.PartialMockTheClassUnderTest();
        }

        public T Get<T>() where T : class
        {
            return _mocker.Get<T>();
        }

        public void Inject(Type pluginType, object stub)
        {
            _mocker.Inject(pluginType, stub);
        }

        public void Inject<T>(T target)
        {
            _mocker.Inject(target);
        }

        public T AddAdditionalMockFor<T>() where T : class
        {
            return _mocker.AddAdditionalMockFor<T>();
        }

        public void UseConcreteClassFor<T>()
        {
            _mocker.UseConcreteClassFor<T>();
        }

        public T[] CreateMockArrayFor<T>(int count) where T : class
        {
            return _mocker.CreateMockArrayFor<T>(count);
        }

        public void InjectArray<T>(T[] stubs)
        {
            _mocker.InjectArray(stubs);
        }

        public T Mock<T>() where T : class
        {
            return _serviceLocator.Service<T>();
        }
        public object Mock(Type serviceType)
        {
            return _serviceLocator.Service(serviceType);
        }
        public T PartialMock<T>() where T : class
        {
            return _serviceLocator.PartialMock<T>();
        }
    }
}

My original classes were similar to this:

public class MyProgress{
   public virtual Guid Id { get; set; }
   ...
   ...
   public virtual MyStatus Status { get; private set; }
}

public enum MyStatus{
   New,
   InProgress,
   Completed,
   Canceled,
   Failed
}

My new state pattern was similar to this:

public abstract class MyStatus
{
    public static readonly MyStatus New = new NewStatus();
    public static readonly MyStatus InProgress = new InProgressStatus();
    ...
}

public class NewStatus: MyStatus
{
    public override void Start(MyProgress progress)
    {
        progress.SetStatus(InProgress);
    }
    public override void Cancel(MyProgress progress)
    {
        progress.SetStatus(Cancelled);
    }
    public override void Fail(MyProgress progress)
    {
            progress.SetStatus(Failed);
    }
}
...

Here is the problem… My enumeration was persisted as an integer field on the record. Now that I had a state pattern, how should I save my state? I googled the problem and found Derick Bailey’s article on the state pattern and Fluent NHibernate. Derick’s pattern works well, but I felt that creating a lookup table in my database just so I can persist a value in another table was not the path I wanted to traverse – I wasn’t persisting an entity, I was persisting a state value on an entity. Not finding any more love from Google, I asked around and was advised to contact fellow Elegant Coder and Guild3 member, Jason Grundy. Here is Jason’s advice:

“I’ve recently changed from using Enums to an approach outlined by Jimmy Bogard here.  In the Entity I would do something like this:

protected int _orderStatusId;
public virtual OrderStatus OrderStatus
{
    get { return Enumeration.FromValue<OrderStatus>(_orderStatusId); }
    set { _orderStatusId = value.Value; }
}

Then in Fluent NH you can simply map to the protected member.”

I decided to pursue Jason’s advice.  The result is my database tables did not need to change at all. Here is some snippets of the updated classes:

public class MyProgress
{
     public virtual Guid Id {get;set;}
     ...
     protected int _status;
     public virtual MyStatus
     {
         get{ return Enumeration.FromValue<MyStatus>(_status); }
         set{ _status = value.Value; }
     }
     ...
}

public class MyStatus : Enumeration
{
     public static MyStatus New = new NewStatus();
     ...

     private class NewStatus : MyStatus
    {
         public NewStatus() : base (0,"New"){}

         public override void Start(MyProgress progress)
         {
             progress.SetStatus(InProgress);
         }
    }
     ...

Notice that the MyStatus class is no longer abstract.  However, the subclasses are all private nested classes, each with a value and a display name.  I set each subclass value to match the enumeration value it replaced.  I did not need to convert my existing data to a new schema.

And here is the Fluent NHibernate override:

public class MyProgressOverride : IAutoMappingOverride<MyProgress>
{
    public void Override(AutoMapping<MyProgress> mapping)
    {
        mapping.Map(x => x.Status)
            .CustomType(typeof(int))
            .Access.CamelCaseField(Prefix.Underscore);
    }
}

As you can see, we use convention-based automapping with overrides, but this same map could be used in a standard class map.

Thanks to Jimmy, Derick, and Jason for the inspiration and assistance!

At my company, we have embraced convention-over-configuration throughout our applications, from our data access framework (Fluent NHibernate) to our IoC container (StructureMap) to our build scripts to our…well, you get the picture.  However, we had been hitting a pain point in our application when trying to serialize our domain objects for transport across the WCF service layer.  We were also seeing some issues with using domain objects directly in our MVC views. The old way would have been to write that boring left-hand/right-hand code.  We all know that left-hand/right-hand code is ugly and pollutes the methods that should be doing real work with ceremonious busy work. 

Well, just as we were really getting stung by these pain points, Cory and I started talking about AutoMapper.  Now, for those who have no idea what AutoMapper is, check out the Getting Started page on CodePlex.  If you want to check out the source, go to the Google code site.  Jimmy Bogard, the AutoMapper author, describes the AutoMapper as a convention-based object-to-object mapper.

Different Means to an End

Here is the basic idea… In the past, I would write this classic chunk of code:

var meeting = _repository.GetMeetingById(meetingId);
var dto = new MeetingDto();
dto.Begins = meeting.Begins;
dto.End = meeting.End;
dto.Attendees = meeting.Attendees;
dto.AttendeesCount = meeting.Attendees.Count;
//do something meaningful

With AutoMapper, I can write this instead:

var meeting = _repository.GetMeetingById(meetingId);
var dto = Mapper.Map<Meeting, MeetingDto>(meeting);
//do something meaningful

Herein lies the beauty of AutoMapper.  When your classes align themselves conventionally, your mapping configuration can be as simple as:

CreateMap<Meeting,MeetingDto>();

This is a trivial example, but where AutoMapper shines is in the ability to map lists and nested properties by convention. Or constructing an object based on another object’s properties.  All without littering a method with ceremonial code.

Using an object-to-object mapper does have its drawbacks:

1. The classic left-hand/right-hand code performs faster than mapped code, although Jimmy has made great strides in increasing performance.
2. When defining unconventional mappings, you will still have left-hand/right-hand code
3. There will be a learning curve for you (and/or your team) if you have not had experience with convention-based frameworks or some of the .NET 3.5 features.

However, we have found these drawbacks to be trivial when compared to the benefits.

Mapping Toolset

In addition to providing the convention mappings, Jimmy has provided a toolset for enhancing the mappings. Listed here are several tools we either use or find compelling.

Custom Converters: Code to convert from source type to destination type. Defined once and implicitly used for all mappings. 

Custom Resolvers: Code to convert from source value to destination value.  Defined once for use by any mapping, but must be explicitly used by a mapping.

Custom Formatters: Code to reformat a type for presentation.  Like resolvers, formatters are defined once and explicitly used.

Before/After Map Functions: Provides the ability to run custom code before or after the mappings are performed.

Validation Assertion: Provides a method to short-circuit at runtime (or in tests) with an explanatory exception when a mapping may cause failures. 

Mapping Profiles: Profile is a base class that helps you organize your code.  If you are familiar with StructureMap’s Registry class, you will feel right at home with the Profile class.

Where We Use AutoMapper

We use AutoMapper to transform our object model to our presentation model.  This happens in two places – in our MVC controllers and at our WCF service layer.

In the controllers, we will map from a domain model or DTO into the view model.  We will also map from our view model into a message object for use by the service or domain.

At the service layer, we flatten our domain model into a DTO or map a message object to run a command against the domain.

Code Samples

I am including the sample code used at the NETDUG meeting.  The first sample shows different ways to setup mappings (inline vs. profiles).  The second sample shows some usages of custom resolvers, formatters, and before-maps.

Download the AutoMapper source.  Jimmy has provided many sample classes and unit tests showing off the usage of different conventions. 

Matt Hinze also posted a sample solution using AutoMapper with NerdDinner (of which I borrowed some custom formatter code – Thanks Matt!).

Download the CodeCampServer source.  It is full of examples and conventions, including using an IoC/DI implementation of the AutoMapper engine.

For more information on this series, please see the introductory post. In the previous post, I discussed build scripts as a way of extending the functionality of TeamCity.  If you downloaded the sample solution, you could see the tasks and structure of the NAnt and Rake scripts.  Since then, I have fully embraced Rake as my default build script engine; therefore, my script examples in this post are Rake scripts.

Don’t forget to listen to Elegant Code Cast #28 , where Chris Brandsma and I had the privilege of speaking with Jim Wierich, the father of Rake.

I have modeled the Rake scripts after the Fluent NHibernate and FubuMVC scripts.  I am also very interested in rake-dotnet from Pete Mounce.  Once rake-dotnet has support for NUnit and MSpec, I will be migrating my scripts to use it as a base library.  (Pete, I am actually planning on a patch for both – you know…in my spare time.)  Rake-dotnet is definitely worth checking out, especially if you use xUnit as your test library.

The Deployment Process

Here is a representation of my preferred folder structure for a solution:

The following tasks are completed on each check-in:

• MSBuild is called to clean and build both debug and release versions of the projects in the solution
• Tests are run
• An archive is created of each site and/or binaries (both debug and release versions), build scripts, and possibly SQL scripts

A post-build event is run on each web application project to pre-compile the site into a specific directory for each compilation type. My post build event looks like this:

%windir%\Microsoft.NET\Framework\v2.0.50727\aspnet_compiler.exe 
–nologo -errorstack -f -u -c -p $(ProjectDir) -v temp
$(SolutionDir)\Build\results\PrecompiledWeb\$(ConfigurationName)\$(TargetName)

The post-build event is also a good place to add any plug-in type binaries not directly depended on by your site, but included in your solution. Each site also has a set of configuration sources for each environment up the chain (nightly, test, staging, production)

After the build, I have added several folders and archive files to the build directory:

The archive files are stored in subsequent builds.  I never have to rebuild my solution for each platform.  Here is an example artifact path definition:

For the nightly build artifacts, I have the following definitions:

build/*=>Build
build/results/Debug.zip=>Sites
build/results/Release.zip=>Sites
build/results/DebugBinaries.zip=>Binaries
build/results/ReleaseBinaries.zip=>Binaries

For subsequent builds, the definitions change slightly:

build/**/*=>build
sites/**/*=>sites
binaries/**/*=>binaries

When the nightly build is run:

• The check-in build is run, if it has pending changes
• The desired (debug or release) site is unzipped and pushed to the nightly build site
• The configuration files for the site are overwritten with the nightly build environment files (See script below) You may update the configuration files before or after pushing your site, depending on your preference)
• Artifacts of the sites, binaries, and build scripts are stored with the build on TeamCity
• Smoke test the sites (see script below)

When a subsequent environment is run:
• Clean all files before build (checkmark on the VCS configuration page for the build)
• The artifacts from the dependent build are retrieved (configured from the dependencies page of the build configuration).
  
• The build tools are retrieved from source control using an edit checkout rule (+:lib)
  Whereas the compile-check and nightly build configurations get the entire folder structure from version control, the subsequent builds only retrieve the lib directory.
• The existing site is archived
• The new site is unzipped and pushed
• The configuration files for the site are overwritten with the specific environment files
• Artifacts of the sites, binaries, and build scripts are stored with the build on TeamCity
• Smoke test the sites

The idea is to feed up the chain of deployments the artifacts needed to complete the next deployment.  It takes a little trial and error to get it right, but the benefits are worth it.  Our current builds at Unity Media Group take 2 to 3 minutes for the compile check (including test runs and zipping files), then approximately 45 seconds to deploy the site on the internal network.

What I have not automated yet (but would like to):

• Reconfiguring the sites to point to a maintenance page while deploying
• Running the SQL schema compare and integration or run update scripts
  – I have run compare/integration scripts previously, but they tended to be more hassle than running them manually.  Still looking for better ways to do this, though.
• If building binaries for use by other projects, update those projects with the new binaries
• Run data scrubbing scripts (for creating known default environments for test or demonstration sites)

Rake File Snippets

To update the configuration files, I define the following method in my helper file:

 # UPDATING CONFIGURATION FILES  def copyToDirectory(zip_file, website_dir, config_type)  throw("ZipFile does not exist!", zip_file) unless File.exist?(zip_file)  seven_zip = SevenZip.new :ziparchive =>  zip_file, :directory=>website_dir  seven_zip.unzip

  # WEB_PROJECTS: list of web application projects with a Config directory  #     => WEB_PROJECTS = ['ElegantCode.Example.Administration',     #                            'ElegantCode.Example.Client',   #                            'ElegantCode.Example.Services']  WEB_PROJECTS.each do |site|  puts "##teamcity[progressMessage 'Updating application settings for #{site}']"    list=FileList.new("#{website_dir}/#{site}/Config/*-#{config_type}.config")    list.each do |file|      target = file.gsub("-#{config_type}",'')      puts "##teamcity[progressMessage 'Copying #{file.to_s} to #{target.to_s}']"      cp file,target    end  endend

And this is how I use it in the rakefile:

# USAGE:zip_file = File.expand_path(File.join("..","Sites", 'Debug.zip'))website_dir = File.join('Z:', 'AdventureMVC')copyToDirectory zip_file, website_dir, 'sandbox'

Similarly, to smoke test the site, I have the following class in my helper file:

# SMOKE TEST class PreJIT    attr_reader :sites

    def self.compile(sites)        sites.each do |site|            puts "##teamcity[progressMessage 'Pre-jitting #{site}']"            open (site)        end    endend

And this is how I use it:

# USAGE:sites = ['http://test.example.com/admin', 'http://test.example.com']PreJIT.compile(sites)

If the site  has a 40x/50x error, the build will fail.

There is much more to the rake scripts; however, you should peruse the rake files from Fluent NHibernate or FubuMVC for more ideas on writing your own Rake scripts.  You can incorporate rake-dotnet into your rake environment, as well.  Finally, you can accomplish the same tasks using MSBuild or NAnt, if you feel more confident in those environments.

Until next time..

Fluent NHibernate

FubuMVC

rake-dotnet

TeamCity

Rake

For more advanced or complex build scenarios, the build it solution runners prove somewhat inflexible.  Once you have arrived at this conclusion, you will most likely start investigating some of the other build runner options.

For .NET projects, the two obvious choices are MSBuild and NAnt.  The new hotness for building .NET projects is Rake.  And, if you use a scripting language not built into TeamCity (such as FinalBuilder, Psake, or shell scripts), the command line runner is your friend.  TeamCity also has two .NET build runners specifically targeting code inspection: Duplicates finder and FxCop.

I have been using NAnt for several years to build both web and desktop applications.  NAnt has been fairly quiet for the last couple years.  The latest official release (0.86 Beta 1) is dated December 2007, but there has been sporadic 0.86 Beta 2 activity in the nightly releases.

I have just started working with Rake for build scripts. (A big thanks to the Fluent NHibernate and FubuMVC contributors for their pioneering efforts on this front.)  Rake, like Ruby itself, seems to be infinitely extensible.

What Should a Build Script Do?

My build scripts need to at least handle the following targets/tasks:

1. Compile the application
2. Run the tests
3. Provide a code coverage report
4. Zip up the compiled application for artifact retention
5. Update the configuration files
6. Publish the website to a folder or IIS virtual directory

TeamCity natively handles 1 and 2, but we will be duplicating that functionality with the build scripts.  TeamCity also allows you to download your artifacts as a zip file, but does not store it as one.  TeamCity does not provide code coverage for .NET projects.  However, it does for Java projects.)

Our NAnt and Rake scripts will handle the all the tasks.  I will cover the first four tasks in this post.  I will cover the other three in another post. 

Setting Up an NAnt Build Runner

We’ll start with an NAnt Build Runner.  In your TeamCity website:

• From the Projects page, click the drop arrow next to the existing project and click on Edit Settings
• On the right hand side of the screen, click on the Copy button to copy the configuration
• Name the new build configuration “Just Build It! (with NAnt)”
• Select the Runner link from the navigation bar on the right

Based on the sample solution, enter the following values and save your changes.  Leave all other values at their defaults. (If your solution is structured differently, adjust accordingly.)

Leaving the Targets text box blank will force the runner to use the default target.

The default targets in thee script files create a zipped file of the website and code coverage results from the free NCover Community edition.  I am using a couple custom tasks from kiwidude for integrating NCover with the NAnt script. 

In the General Settings page, add the following to the Artifacts text box to force both files to show up as artifacts:

results/Artifacts.zip
results/CoverageReport.html=>ncover

 
Creating custom tabs is fairly simple as well.  Add the following entry to the <TeamCity data directory>/config/main-config.xml (the default data directory is named .BuildServer to create a tab that shows the NCover results for each build:

<report-tab title="NCover"
basePath="ncover"
startPage="CoverageReport.html" />

(Thanks to Laurent Kempé for the instructions on integrating NCover with TeamCity)

Setting Up a Rake Build Runner

Make another copy of a configuration and name the new build configuration “Just Build It! (with Rake)”. This time select Rake as the build runner on the Build Runner page.  Leave all other values at their default.  (The Rakefile in the root directory will be used.  I modified the rake scripts from the FubuMVC project for this solution.)

You will need Ruby and a couple of Gems to get started.  Check the information in the Ruby_Not_Installed.txt file in the root directory of the sample solution. 

Setting Up an MSBuild Build Runner

I actually do not have an example of an MSBuild script (because I do not have enough experience with MSBuild).  Setting up the build runner is similar to the NAnt and Rake runners.  If you are interested in this build runner type, check out Ryan Anderson’s posts. He has done an excellent job detailing the process.

• Deployment: Using TeamCity and build scripts to update different deployment environments.
• Setting up notifications: We will look at the different options for notifications, such as email and the tray notifier.

See you in Portland!

With our basic solution build, we want to start running our unit tests on every check-in, create a nightly build (that runs both unit and integration tests), and generate some artifacts.

Running Tests

First things first, lets get the tests running.  Open the current build configuration and select the build runner navigation link (it should say Runner: sln2008).  On the build runner page, select NUnit 2.4.8 from the NUnit runner combo box.  Add the path to the unit test assembly in the assembly text box.  For our solution, the path is: **/bin/debug/AdventureMVC.Tests.dll .  As you can see, this is using an MSBuild wildcard format to find the correct assembly.  It is unnecessary to point to the full path.

Save your changes.

Now, when your builds run, you should get a new status indicator showing how many tests passed. 

If you click on the status, you will also see a new tab on the build results page showing the test information.

Nightly Builds (with integration tests)

Now that we have our unit tests running on every check-in, let’s create a nightly build.  Open the current build configuration.  Make a copy of the build by clicking on the Copy button on the right-hand side of the page. 

Rename the new configuration as you see fit.  I will use Nightly Build.

Select the build runner link.  Add the integration test assembly to the test assembly text box.

Save your changes.

Select the Build triggering link.  Deselect the check box.  On the Schedule tab, click on Add time trigger and configure your nightly build time. Save your changes.  (You can test the build at this point by clicking on the Run button.)

Creating Artifacts

We want to make the compiled website readily available, so we are going to create some artifacts.  Getting at the precompiled website through the file system is inconvenient.

If the example solution contained a website, compiling the solution would create a precompiled website.  Since the example solution contains a web application project (specifically an ASP.NET MVC application project), I had to add a post-build event to create the precompiled site.  Check the AdventureMVC project properties to see the syntax.

On the Nightly Build configuration page, select the General Settings link.  In the Artifacts text box, type: PrecompiledWeb\Web=>PrecompiledWeb.  Save your changes.

Now when you run your build, you should see an Artifacts dropdown link in the status line of the build. 

When you click on the build status, the status page now has an artifacts tab.  

Not only do you have the ability to download the individual files, you can now use these artifacts in other build configurations…but that is for another post.

Originally posted on CodeProgression.com on April 19, 2009

Upcoming posts:

• Build scripts: We need some additional functionality that the basic solution runner doesn’t provide, such as zipping up artifacts.

• Setting up notifications: We will look at the different options for notifications, such as email and the tray notifier.

• Deployment: Using TeamCity and build scripts to update different deployment environments.

Why Continuous Integration?

The benefit of continuous integration, according to Martin Fowler, is reduced risk.  Reduced risk is accomplished through a quick feedback cycle.  The longer you defer integration, the more difficult integration becomes.  If you integrate automated testing into your integration cycle, you can further reduce your risk.

Continuous Integration with TeamCity (VCS Triggers)

TeamCity has four build trigger options:

1. VCS Triggers: Triggers a build when files are checked into source control.
2. Schedule: Triggers a build on a predetermined schedule.
3. Dependencies: Triggers a build when another build completes successfully.
4. Other Triggers: Triggers a build if previous build fails.

VCS triggers are analogous to continuous integration.  Check in files to source control and a build is started.  Enabling continuous integration in TeamCity takes only a few clicks to configure.

Lets get started. Click the arrow next to the build configuration we completed in the last post. Select Edit Settings.

On the right side of the build configuration screen, you will see a list of Build Configuration Steps.  Select the Build Triggering step. 

Select the checkbox labeled Enable triggering when files are checked into VCS. 

At this point, you can save your changes and you will have enabled continuous integration.  The quiet period and trigger rules (explained below)  fine-tune the behavior of the build trigger.

Once checked, an option to set a quiet period is enabled.  A quiet period is the length of time after a check-in which TeamCity will wait before starting the build.  If check-ins tend to come in waves, this can help keep the build queue short.  (If you tend to forget to check in all your files or need to check in files from your IDE and file system, you may want to give yourself a short quiet period before triggering a build to allow for multiple check-ins.)

However, if you configure too long of a quiet period with a project with a large team, the build may take too long to start, negating the benefits of continuous integration.  I prefer to select Do not use or Use default value (60 seconds) for my projects.

Finally, you can exclude some check-ins from triggering the build by defining trigger patterns.  Exclusions can be based on file paths, users, or a combination.  For example, if your project team includes a technical writer who produces documentation, those check-ins probably do not affect build quality.  Or, when you update your build scripts, those changes may not need to trigger a build either (see example below).  For the purposes of the example solution, you may define the –:*.build pattern, even though we haven’t started using build scripts yet.

Defining a trigger pattern is fairly straightforward. The pattern is:
+|-:[user][VCS root][path]
Defining a +: rule removes the include all rule, allowing a very fine-grade include path. Defining a –: rule excludes the defined path from triggering a build.  For more information, see the documentation.

Finish by saving your changes and returning to the main page.  Update and check in a project file and you can watch TeamCity start a new build process.

 Congratulations! You have just enabled continuous integration with TeamCity!

Originally posted on CodeProgression.com on April 15, 2009

Upcoming posts: Creating artifacts and nightly builds