The typical example:

public class Contact : INotifyPropertyChanged {
    private string _firstName;

    public string FirstName {
        get { return _firstName; }
        set {
            if (!Equals(_firstName, value)) {
                _firstName = value;
                OnPropertyChanged("FirstName");
            }
        }
    }

    public event PropertyChangedEventHandler PropertyChanged;

    protected virtual void OnPropertyChanged(string propertyName) {
        PropertyChangedEventHandler handler = PropertyChanged;
        if (handler != null) {
            handler(this, new PropertyChangedEventArgs(propertyName));
        }
    }
}

As you can see, it is quite verbose. The event and OnPropertyChanged() method need to be implemented for each class and it’s easy to get the implementation of OnPropertyChanged() wrong (typically introducing a race condition). Moreover, it’s 10 lines of code for each property. I hate that. The more you have to write, the bigger a surface for bugs to appear. A property should just boil down to  

public string FirstName { get; set; }

That won’t be possible of course. The default setters and getters just handle the assignment and loading of a compiler-generated backing field. So we somehow need to add the code for each property.

Enter Bindable objects

Similar to class NotificationObject, Bindable is here to help implementing INotifyPropertyChanged. The NotificationObject class only implements RaisePropertyChanged() but does not help with the implementation of the properties. Here is what you can do with Bindable:

public class Contact : Bindable {
    public string FirstName {
        get { return Get<string>(); }
        set { Set(value); }
    }
}

Noticeably shorter, isn’t it ?

Behind the scene, Bindable uses a dictionary to store the property values. You probably have noticed that the property name is not given to Bindable.Get() or Bindable.Set(). Bindable leverages the compiler to provide the value automatically:

protected T Get<T>([CallerMemberName] string name = null) { }
protected void Set<T>(T value, [CallerMemberName] string name = null) { }

CallerMemberNameAttribute

Get<string>()

Get<string>("FirstName")

Here is the actual code for class Bindable:

using System.Collections.Generic;
using System.ComponentModel;
using System.Diagnostics;
using System.Runtime.CompilerServices;

namespace TiMoch.Framework {
    /// <summary>
    /// Base class to implement object that can be bound to
    /// </summary>
    public class Bindable : INotifyPropertyChanged {
        private Dictionary<string, object> _properties = new Dictionary<string, object>();

        /// <summary>
        /// Gets the value of a property
        /// </summary>
        /// <typeparam name="T"></typeparam>
        /// <param name="name"></param>
        /// <returns></returns>
        protected T Get<T>([CallerMemberName] string name = null) {
            Debug.Assert(name != null, "name != null");
            object value = null;
            if (_properties.TryGetValue(name, out value))
                return value == null ? default(T) : (T)value;
            return default(T);
        }

        /// <summary>
        /// Sets the value of a property
        /// </summary>
        /// <typeparam name="T"></typeparam>
        /// <param name="value"></param>
        /// <param name="name"></param>
        protected void Set<T>(T value, [CallerMemberName] string name = null) {
            Debug.Assert(name != null, "name != null");
            if (Equals(value, Get<T>(name)))
                return;
            _properties[name] = value;
            OnPropertyChanged(name);
        }

        public event PropertyChangedEventHandler PropertyChanged;

        protected virtual void OnPropertyChanged([CallerMemberName] string propertyName = null) {
            PropertyChangedEventHandler handler = PropertyChanged;
            if (handler != null) {
                handler(this, new PropertyChangedEventArgs(propertyName));
            }
        }
    }
}

Some aspects can be improved. For example, enabling subclasses to provide their own backing field. This is left as an exercise to the reader

I use this class a lot when implementing MVVM either in Wpf or Winforms.

What do you think ?

Edit: fixed code snippets as per Krumelur’s comments. Thanks Krumelur.

It is actually quire easy to unit test model validation. Models are inherently easy to test separately due to their POD (Plain Old Data) nature. We can instantiate them directly. Moreover, DataAnnotations provides us with the necessary interface to run the validation against a model object completely separately from the rest of the application.

A first model validation test class

Here is a basic model that we will unit test for the demonstration:

using System;
using System.ComponentModel.DataAnnotations;

namespace DataAnnotationsUnitTesting
{
    public class CreatePersonModel
    {
        [Required]
        public string FirstName { get; set; }
        [Required]
        public string LastName { get; set; }
        [Range(typeof (DateTime), "1900/01/01", "2000/01/01")]
        public DateTime BirthDate { get; set; }
        [RegularExpression(@"\+?\d+")]
        public string PhoneNumber { get; set; }
    }
}

As you can see, it is quite simple. We’ll go directly to the unit test implementation.

The strategy we are going to use consists in basing each test case on a valid model instance, then modifying it in such a way that it triggers one single validation error. We end up with a skeleton unit test class like this:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.Linq;
using NUnit.Framework;

namespace DataAnnotationsUnitTesting {
    [TestFixture]
    public class CreatePersonModelValidationTests : AssertionHelper {
        private CreatePersonModel CreateValidPersonModel() {
            return new CreatePersonModel() {
                FirstName = "Some Name",
                LastName = "Some Last Name",
                BirthDate = new DateTime(1982, 07, 28),
                PhoneNumber = "+112233445566"
            };
        }

        public IEnumerable<ValidateRuleSpec> ValidationRule_Source() {
            yield break;
        }

        [Test]
        [TestCaseSource("ValidationRule_Source")]
        public void ValidationRule(ValidateRuleSpec spec) {
            // Arrange
            var model = CreateValidPersonModel();
            // Apply bad valud
            model.GetType().GetProperty(spec.MemberName).SetValue(model, spec.BadValue);

            // Act
            var validationResults = new List<ValidationResult>();
            var success = Validator.TryValidateObject(model, new ValidationContext(model), validationResults, true);

            // Assert
            Expect(success, False);
            Expect(validationResults.Count, EqualTo(1));
            Expect(validationResults.SingleOrDefault(r => r.MemberNames.Contains(spec.MemberName)), Not.Null);
        }

        public class ValidateRuleSpec {
            public object BadValue;
            public string MemberName;

            public override string ToString() {
                return MemberName + " - " + (BadValue ?? "<null>");
            }
        }
    }
}

Some explanation:

• ValidateRule() implements the test itself. However, it gets the specifications for each test via an argument. 
• ValidateRule_Source() provides the specs for our test.
• class ValidateRuleSpec holds the specifications. Its ToString() uses the spec values to render a distinct string per test. This makes unit test reports easy to read. In case of failure, you know exactly which spec failed.

And now the implementation of our ValidateRule_Source():

public IEnumerable<ValidateRuleSpec> ValidationRule_Source() {
    yield return new ValidateRuleSpec() {
        BadValue = null,
        MemberName = "FirstName"
    };
    yield return new ValidateRuleSpec() {
        BadValue = string.Empty,
        MemberName = "FirstName"
    };
    yield return new ValidateRuleSpec() {
        BadValue = null,
        MemberName = "LastName"
    };
    yield return new ValidateRuleSpec() {
        BadValue = string.Empty,
        MemberName = "LastName"
    };
    yield return new ValidateRuleSpec() {
        BadValue = new DateTime(),
        MemberName = "BirthDate"
    };
    yield return new ValidateRuleSpec() {
        BadValue = DateTime.Today,
        MemberName = "BirthDate"
    };
    yield return new ValidateRuleSpec() {
        BadValue = "-65623",
        MemberName = "PhoneNumber"
    };
    yield return new ValidateRuleSpec() {
        BadValue = "abc",
        MemberName = "PhoneNumber"
    };
}

Refining the solution

This works but can be improved. Most of the functionality can be abstracted. The actual test need only provide the valid model object and the specifications. A bit of refactoring yields a nicer design for our test:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.Linq;
using NUnit.Framework;

namespace DataAnnotationsUnitTesting {
    [TestFixture]
    public abstract class ModelValidationTestsBase : AssertionHelper {
        protected abstract CreatePersonModel CreateValidModel();

        public abstract IEnumerable<ValidateRuleSpec> ValidationRule_Source();

        [Test]
        [TestCaseSource("ValidationRule_Source")]
        public void ValidationRule(ValidateRuleSpec spec) {
            // Arrange
            var model = CreateValidModel();
            // Apply bad valud
            model.GetType().GetProperty(spec.MemberName).SetValue(model, spec.BadValue);

            // Act
            var validationResults = new List<ValidationResult>();
            var success = Validator.TryValidateObject(model, new ValidationContext(model), validationResults, true);

            // Assert
            Expect(success, False);
            Expect(validationResults.Count, EqualTo(1));
            Expect(validationResults.SingleOrDefault(r => r.MemberNames.Contains(spec.MemberName)), Not.Null);
        }

        protected ValidateRuleSpec Spec(string memberName, object badValue) {
            return new ValidateRuleSpec() {MemberName = memberName, BadValue = badValue};
        }

        public class ValidateRuleSpec {
            public object BadValue;
            public string MemberName;

            public override string ToString() {
                return MemberName + " - " + (BadValue ?? "<null>");
            }
        }
    }

    public class CreatePersonModelValidationTests : ModelValidationTestsBase {
        protected override CreatePersonModel CreateValidModel() {
            return new CreatePersonModel() {
                FirstName = "Some Name",
                LastName = "Some Last Name",
                BirthDate = new DateTime(1982, 07, 28),
                PhoneNumber = "+112233445566"
            };
        }

        public override IEnumerable<ValidateRuleSpec> ValidationRule_Source() {
            yield return Spec("FirstName", null);
            yield return Spec("FirstName", string.Empty);
            yield return Spec("LastName", null);
            yield return Spec("LastName", string.Empty);
            yield return Spec("BirthDate", new DateTime());
            yield return Spec("BirthDate", DateTime.Today);
            yield return Spec("PhoneNumber", "-65623");
            yield return Spec("PhoneNumber", "abc");
        }
    }
}

Notice how we trimmed CreatePersonModelValidationTests to a minimum. The class ModelValidationTestsBase can now be used for most of our model validation unit tests.

What do you think?

Assert.AreEqual(LeftObject.Property1, RightObject.Property1);
Assert.AreEqual(LeftObject.Property2, RightObject.Property2);
Assert.AreEqual(LeftObject.Property3, RightObject.Property3);
...
Assert.AreEqual(LeftObject.PropertyN, RightObject.PropertyN);

I agree, this is ugly. The more so if you have multiple tests that assert on the equality of these properties. You can always factor it out into a helper function but you still end up actually writing the comparisons yourself.

The selected answer doesn’t feel right. The proposal is to implement Equals() in the class for your tested object. This is not always desirable or even possible. Consider the case where your use case actually makes use of Equals() in its logic. There may already exist an implementation of Equals() that satisfies different needs than those of your test. Moreover, when overriding Equals(), there is more to it than just this single function. GetHashCode() must be implemented too … and correctly ! If you don’t implement GetHashCode(), you may end up with subtle or not-so-subtle bugs if your object gets stored as a dictionary key. In most cases, it will not be an issue because only a very few classes are actually used a dictionary keys. However, if you get into the habit of overriding Equals() without GetHashCode(), you can be bitten hard !!

One of the most favored answer is to use reflection to discover the distinct properties. This is the way to go. Code that solely exists for testing purposes should be kept away from the classes you test. However, I find the proposed solution sub-optimal. For one thing, the method is solely dedicated to testing and directly calls Assert.AreEqual(). For another, I don’t like that it automatically recurse into IList properties, but this is a question of style.

I would propose a general purpose utility method like this.

/// <summary>
/// Returns the names of the properties that are not equal on a and b.
/// </summary>
/// <param name="a"></param>
/// <param name="b"></param>
/// <returns>An array of names of properties with distinct values or null if a and b are null or not of the same type</returns>
public static string[] GetDistinctProperties(object a, object b) {
    if (object.ReferenceEquals(a, b))
        return null;
    if (a == null)
        return null;
    if (b == null)
        return null;

    var aType = a.GetType();
    var bType = b.GetType();

    if (aType != bType)
        return null;

    var props = aType.GetProperties();

    if (props.Any(prop => prop.GetIndexParameters().Length != 0))
        throw new ArgumentException("Types with index properties not supported");

    return props
        .Where(prop => !Equals(prop.GetValue(a, null), prop.GetValue(b, null)))
        .Select(prop => prop.Name).ToArray();
}

and of course, the unit test that goes along with it:

[Test]
public void GetDistinctProperties() {
    Expect(ReflectionUtils.GetDistinctProperties(null, null), Null);
    Expect(ReflectionUtils.GetDistinctProperties(new TestClass1(), null), Null);
    Expect(ReflectionUtils.GetDistinctProperties(null, new TestClass1()), Null);
    Expect(ReflectionUtils.GetDistinctProperties(new TestClass1(), new TestClass2()), Null);
    Expect(ReflectionUtils.GetDistinctProperties(new TestClass1(), new TestClass1()),
            EquivalentTo(new string[] {}));
    Expect(ReflectionUtils.GetDistinctProperties(new TestClass1() {Foo = "haha"}, new TestClass1()),
            EquivalentTo(new string[] {"Foo"}));
    Expect(ReflectionUtils.GetDistinctProperties(new TestClass1(), new TestClass1() {Bar = 10}),
            EquivalentTo(new string[] {"Bar"}));
}

[Test, ExpectedException(typeof(ArgumentException))]
public void GetDistinctProperties_ThrowsWithIndexedProperty() {
    ReflectionUtils.GetDistinctProperties("haha", "jeje");
}

It can then be used in a unit test like this:

[Test]
public void BasicOperations() {
    RegionParameters parameters = new RegionParameters(5, 5, 5, 5);
    var tilemap = new BasicTileMap(parameters);

    var tile = new Tile() {
        MagmaLevel = 0,
        WaterLevel = 0,
        RockType = 1,
        State = TileState.HasFloor
    };

    tilemap.Update(new Location(0, 0, 0), tile);

    var got = tilemap.Get(new Location(0, 0, 0));
    Expect(ReflectionUtils.GetDistinctProperties(tile, got), Empty);
}

You can wrap the method via a unit-test friendly static assert method or any way you like. The above test would fail in a quite explicit way. An error message looks like this:

Expected: <empty>
  But was:  < "MagmaLevel" >

   at NUnit.Framework.Assert.That(Object actual, IResolveConstraint expression, String message, Object[] args)
   at Undermine.Engine.Tests.TileMaps.BasicTileMapTests.BasicOperations() in BasicTileMapTests.cs: line 29

What do you think ?

ASP.Net MVC really pushes for loosely coupled components and as such, encourages unit testing. Your controllers are not much more than plain methods taking some input, executing some logic and returning an output. Your controller is not responsible for much in the end. Even though it is a central part of any functionality, its responsibility is reduced to implementing the logic for responding to a certain type of request. It relies on the framework configuration and conventions to call its methods in an appropriate way.

Understanding the extend of a controller’s responsibility is a key to writing good, concise unit tests. Sometimes, it’s easier to remember what it is not responsible for:

• Model binding: turning the encoded form data or routing information into .Net object. A controller action does not need to know and does not care that the id of the object your are updating is a part of your action’s path (eg.

  /admin/tags/edit/my-tag

   ) or if it is provided in the form of an encoded form field (eg.

  <input type="text" name="tagSlug" />

   )
• Model validation: it may seem surprising but in most cases, your controller should not implement the validation logic. From a controller’s action point of view, is there really a difference between a person’s last name missing or an unknown phone number format ? As far as your hypothetical EditPerson action is concerned, there is a validation error. Model validation should be tested separately.
• Pure business logic: a controller action is meant to handle requests. Even though it does not directly cope with http intricacies, it still very close to the http request/response life cycle. For example, an action ComputeLoanSchedule that needs to return a loan amortization schedule should probably delegate the actual computation to a business service class (ILoanService.GetAmortizationSchedule()) whose sole purpose is to handle such computation. In the future, if you need to expose the amortization schedule feature as a web api, you will only need to implement another controller and call the same business service.

In the end, your controller is only responsible for:

• Delegating work to domain services: as stated above, the domain logic of your application should be logically separated from your UI layer. It also gives you the flexibility to scale your web application and business domain services. 
• Returning an appropriate response: a controller’s action responds to a request by returning a response. The standard MVC Controller class expects your actions provide a result that will drive the way the response if created. eg. Returning a ViewResult will trigger view rendering and a RedirectToRouteResult may respond with an HTTP 302.

Unit testing a controller action

When it comes to unit testing, the less to test, the better. As such, the limited responsibility of controller actions is a boon when writing unit tests. As an example, I will be using a very simple controller

TagsController

TagsController

• Index: provides the user with a list of existing tags
• Create: enables the creation of new tags
• Edit: enables editing existing tags

The simple case

We will focus on the index functionality for now. It is implemented as a single action on our TagsController:

public class TagsController : Controller {
    private ITagService tagService;

    public TagsController(ITagService tagService) {
        this.tagService = tagService;
    }

    public ActionResult Index() {
        var tags = this.tagService.GetAll().OrderBy(tag => tag.Name);
        return View("Index", tags);
    }

    /* ... */
}

The TagsController constructor takes a ITagService. It provides our constructor access to the tags in our database. As you can see, the

Index()

With such a simple implementation, the unit test will be quite simple also. I’ll follow the usual AAA (Arrange-Act-Assert) pattern.

[Test]
public void Index_RetrievesAllTags() {
    // Arrange
    var mockService = new Mock<ITagService>();
    var controller = new TagsController(mockService.Object);
    mockService
        .Setup(s => s.GetAll())
        .Returns(new[] {
            new Tag {Slug = "tag1", Name = "Tag1"},
            new Tag {Slug = "tag7", Name = "Tag7"},
            new Tag {Slug = "tag4", Name = "Tag4"}
        });

    // Act
    var result = controller.Index() as ViewResult;

    // Assert
    Expect(result, Not.Null);
    Expect(result.ViewName, EqualTo("Index"));

    // ensure service was used
    mockService.Verify(s => s.GetAll(), Times.Once());

    // check view's model
    var tags = result.Model as IEnumerable<Tag>;
    Expect(tags, Not.Null);
    Expect(tags.Count(), EqualTo(3));
    // tags should be sorted
    Expect(tags.ToArray()[0].Slug, EqualTo("tag1"));
    Expect(tags.ToArray()[1].Slug, EqualTo("tag4"));
    Expect(tags.ToArray()[2].Slug, EqualTo("tag7"));
}

The first part sets up an ITagService mock for TagsController to consume. We then simply call method

Index()

The assertions start with making sure we got a non-null result of the ViewResult type.

Index()

mockService.Verify()

ITagService.GetAll()

I then proceed with checking the model provided to the view is consistent with the data from the mock service object. One of the requirements is that the tags are sorted by name.

As you can see in the Index unit test, there is a lot more code than the method being tested. This is also one of the reason why you should reduce the scope of your tests as much as you can.

A more complex test case

I’ll cover the “create a new tag” functionality. In this case, the functionality is implemented by a pair of actions. A parameter-less

Create()

Create()

SaveTagModel

public class TagsController : Controller
{
    /* ... */

    [HttpGet]
    public ActionResult Create() {
        return View("Save", new SaveTagModel() {IsNew = true});
    }

    [HttpPost]
    public ActionResult Create(SaveTagModel saveTagModel) {
        var existingTag = tagService.GetBySlug(saveTagModel.Slug);
        if (existingTag != null) {
            ModelState.AddModelError("TagExists", "A tag with that slug already exists");
        }

        if (!ModelState.IsValid) {
            saveTagModel.IsNew = true;
            return View("Save", saveTagModel);
        }

        tagService.Save(new Tag() { Name = saveTagModel.Name, Slug = saveTagModel.Slug });
        return RedirectToAction("Index");
    }

    /* ... */
}

I’ll show the tests I put together to cover the functionality of

TagsController.Create()

Create()

Edit()

SaveTagModel

[Test]
public void Create_ShowsEmptySaveEditor() {
    // Arrange
    var mockService = new Mock<ITagService>();
    var controller = new TagsController(mockService.Object);

    // Act
    var result = controller.Create() as ViewResult;

    //Assert
    Expect(result, Not.Null);
    Expect(result.ViewName, EqualTo("Save"));
    var saveTagModel = result.Model as SaveTagModel;
    Expect(saveTagModel, Not.Null);
    Expect(saveTagModel.IsNew, True);
    Expect(saveTagModel.Name, Null.Or.Empty);
    Expect(saveTagModel.Slug, Null.Or.Empty);
}

The next 2 tests cover the behavior of the

Create(SaveTagModel tag)

• What happens when invalid input is provided?
• What happens when a tag exists with the same ‘slug’?
• What happens upon success?

It will not come as a surprise that I wrote 3 tests, one for each of the points. The first test ensure

Create()

[Test]
public void Create_ShowsEditorAgainOnInvalidInput() {
    // Arrange
    var mockService = new Mock<ITagService>();
    var controller = new TagsController(mockService.Object);

    // Act
    var saveTagModelArg = new SaveTagModel() {Slug = string.Empty, Name = "somename"};
    controller.ModelState.AddModelError("testerror", "test message");
    var result = controller.Create(saveTagModelArg) as ViewResult;

    //Assert
    Expect(result, Not.Null);
    Expect(result.ViewName, EqualTo("Save"));
    var saveTagModel = result.Model as SaveTagModel;
    Expect(saveTagModel, Not.Null);
    Expect(saveTagModel.IsNew, True);
    Expect(saveTagModel.Name, EqualTo("somename"));
    Expect(saveTagModel.Slug, Null.Or.Empty);
    Expect(result.ViewData.ModelState.IsValid, False);
}

Considering what I have just said, there is an issue with the current implementation of

Create()

ITagService.Create()

Here is the test that covers that part.

[Test]
public void Create_ShowsEditorAgainOnDuplicateSlug() {
    // Arrange
    var mockService = new Mock<ITagService>();
    var controller = new TagsController(mockService.Object);
    mockService.Setup(s => s.GetBySlug("tag"))
        .Returns(new Tag("tag", "Tag"));

    // Act
    var saveTagModelArg = new SaveTagModel() {Slug = "tag", Name = "somename"};
    var result = controller.Create(saveTagModelArg) as ViewResult;

    //Assert
    Expect(result, Not.Null);
    Expect(result.ViewName, EqualTo("Save"));
    var saveTagModel = result.Model as SaveTagModel;
    Expect(saveTagModel, Not.Null);
    Expect(saveTagModel.IsNew, True);
    Expect(saveTagModel.Name, EqualTo("somename"));
    Expect(saveTagModel.Slug, EqualTo("tag"));
    Expect(result.ViewData.ModelState.IsValid, False);
}

Last but not least, here is the test that covers the success path. Out action should have called

ITagService.Save()

[Test]
public void Create_SavesTagAndRedirectsOnSuccess() {
    // Arrange
    var mockService = new Mock<ITagService>();
    var controller = new TagsController(mockService.Object);
    var saveTagModelArg = new SaveTagModel() {Slug = "tag", Name = "somename"};
    mockService.Setup(s => s.Save(It.Is<Tag>(tag => tag.Slug == "tag" && tag.Name == "somename")));

    // Act
    var result = controller.Create(saveTagModelArg) as RedirectToRouteResult;

    //Assert
    Expect(result, Not.Null);
    Expect(result.Permanent, False);
    Expect(result.RouteName, Null.Or.Empty);
    Expect(result.RouteValues["controller"], Null.Or.Empty.Or.EqualTo("Tags"));
    Expect(result.RouteValues["action"], EqualTo("Index"));
    mockService.VerifyAll();
}

Conclusion

As you can see, even though our controller is quite simple (3 methods only and simple at that), we had to write quite a few lines of unit test code to cover all the code paths. If you want to keep your unit tests to a minimum, make sure you respect the separation of concern principle. Test each of the involved components separately and reduce to a minimum the contract between them. The less they know about the other, the easier it is to change one component without your change to ripple through your whole application.

In the next few posts, I will cover testing model binding and validation as well as routes.

Don’t hesitate to hail me in the comments or on Twitter

Testing XPathNavigator

First things first, before attacking the new implementation proper, we want to make sure our implementation is compatible with the default implementation. To do so, we will write tests that will be run both against the Microsoft implementation as well as our implementation once it exists. Our goal here is really twofold. On the one hand, we want to ensure the existing implementation actually works as documented. On the other hand, we want to check our own implementation against the specification tests.

What should we test ?

XPathNavigator is a complex class. So we want to limit my tests to what actually matters for the new implementation. Otherwise, we may be writing literally hundreds of tests.

It is obviously not necessary to test methods that will not be re-implemented. In the previous post, we identified a subset of methods that we will need to re-implement. All other methods are somehow using this basic subset to implement their functionality. The subset is the list of abstract members:

public abstract string BaseURI { get; }
    public abstract bool IsEmptyElement { get; }
    public abstract string LocalName { get; }
    public abstract string Name { get; }
    public abstract string NamespaceURI { get; }
    public abstract XmlNameTable NameTable { get; }
    public abstract XPathNodeType NodeType { get; }
    public abstract string Prefix { get; }

    public abstract bool MoveTo(XPathNavigator other);
    public abstract bool MoveToFirstAttribute();
    public abstract bool MoveToFirstChild();
    public abstract bool MoveToFirstNamespace(XPathNamespaceScope namespaceScope);
    public abstract bool MoveToId(string id);
    public abstract bool MoveToNext();
    public abstract bool MoveToNextAttribute();
    public abstract bool MoveToNextNamespace(XPathNamespaceScope namespaceScope);
    public abstract bool MoveToParent();
    public abstract bool MoveToPrevious();

As you can see, we have two distinct groups:

• The abstract properties expose information about the current node. Our tests will ensure that we get consistent information for all types of node.
  
• The abstract methods are all concerned about moving the navigator to another node. The tests need to check that the move operations result in the navigator pointing to the right node given a known starting position.

How should we test it ?

We will test the properties by setting up a XPathNavigator that points to specific nodes of an xml document. Once setup, we simply check the properties expose consistent values. We will test the Move() operations in a very similar way. We will setup the XPathNavigator instance on a specific node, execute the Move() operation we want to test and then check that the XPathNavigator yields values through its properties that are consistent with the navigator’s new position.

This is actually very similar. The only difference is the Move() operation. The similarity will let us factor our most of the test code into a few utility functions.

private void CanMoveImpl(MoveTestArgs args, Func<XPathNavigator, bool> moveOperation) {
    CheckInconclusive(args);

    // Arrange - get a navigator on requested node
    var nav = CreateNavigatorOnSelected(args.Xml, args.InitialPosition);

    // Act - move thenode
    var success = moveOperation(nav);

    // Assert -- check if success consistent with ShouldSucceed
    Expect(success, args.ShouldSucceed ? (Constraint)True : False, "inconsistent success state");
    // Assert -- check node properties 
    ExpectNodeProperties(nav, args);
}

CanMoveImpl() acts as a parametrized test. It takes 2 arguments:

• args: a MoveTestArgs instance. This argument describes the test’s original state and the resulting state we should test against.
• moveOperation: A delegate to the Move() operation to test. Passing the operation to test as a parameter let us also write non-Move() tests by simply passing a no-op callback.

NUnit: I am using NUnit to write the unit tests. It is only a matter of preference. You can adapt the tests to work against another testing framework such as Microsoft Unit Testing Framework. I find NUnit to be simple to use, non-obstrusive and very flexible. 

CanMoveImpl() is called by actual test methods like the following:

[TestCaseSource("CanMoveToNext_Source")]
public void CanMoveToNext(MoveTestArgs args) {
    CanMoveImpl(args, n => n.MoveToNext());
}

It is a parametrized test. The TestCaseSource attribute tells NUnit which method to call to get the MoveTestArgs instance for each test.

public IEnumerable<MoveTestArgs> CanMoveToNext_Source() {
    yield return new MoveTestArgs() {
        Xml = @"<root></root>",
        InitialPosition = "/", // selects root
        ShouldSucceed = false
    };

    yield return new MoveTestArgs() {
        Xml = @"<root><child/></root>",
        InitialPosition = "/root/child",
        ShouldSucceed = false
    };

    yield return new MoveTestArgs() {
        Xml = @"<root><child/><child2/></root>",
        InitialPosition = "/root/child",
        NodeType = XPathNodeType.Element,
        LocalName = "child2",
    };

    /* ... */
}

Method CanmoveToNext_Source() returns each test case for a given operation. In the above example, we have the test cases for “when position on document root, MoveToNext() should fail”, “When positioned on element whith no next sibling, MoveToNext() should fail” and “when positioned on an element with a next sibling, MoveToNext() should succeed and point to the specific node”.

Each test case is defined by specifying values for the fields of class CanMoveArgs.

public class MoveTestArgs {
    // Xml document
    public string Xml;
    // XPath to select starting first position
    public string InitialPosition;

    // value to test against - no assertion for a given property when not set
    public string BaseURI;
    public bool? IsEmptyElement;
    public string LocalName;
    public string Name;
    public string NamespaceURI;
    public string NameTable;
    public XPathNodeType? NodeType;
    public string Prefix;
    public string Value;

    // Indicates whether the move should succeed or not
    public bool ShouldSucceed = true;

    // indicates whether the test is inconclusive
    public string Inconclusive;

    // TestCaseSource calls ToString() on each test case argument to create the test case name.
    public override string ToString() {
        if (ShouldSucceed)
            return string.Format("{0} -- {1} -- {2} -- {3}", Xml, InitialPosition, NodeType, LocalName);
        else
            return string.Format("{0} -- {1} -- fails", Xml, InitialPosition);
    }
}

Method ExpectNodeProperties() implements the assertions depending on the configuration of its MoveTestArgs instance:

private void ExpectNodeProperties(XPathNavigator navigator, MoveTestArgs args) {
    if (args.LocalName != null) Expect(navigator.LocalName, EqualTo(args.LocalName), "bad localname");
    if (args.Name != null) Expect(navigator.Name, EqualTo(args.Name), "bad name");
    if (args.Prefix != null) Expect(navigator.Prefix, EqualTo(args.Prefix), "bad prefix");
    if (args.NamespaceURI != null) Expect(navigator.NamespaceURI, EqualTo(args.NamespaceURI), "bad namespace uri");
    if (args.NodeType != null) Expect(navigator.NodeType, EqualTo(args.NodeType), "bad node type");
    if (args.Value != null) Expect(navigator.Value, EqualTo(args.Value), "bad value");
}

Executing our tests

We want our tests to be executed against the Microsoft implementation as well as our own implementation. The most straight-forward way of achieving this is to implement our tests in an abstract test fixture. The abstract fixture has an factory method to create an instance of XPathNavigator to test against. For each implementation, we create a subclass of our fixture and override the factory method.

CreateNavigable returns an IXPathNavigable. In turn IXpathNavigable lets us create a navigator positioned on the document root thanks to its CreateNavigator() method.

[TestFixture]
public abstract class XPathDocumentTests : AssertionHelper {
    protected abstract IXPathNavigable CreateNavigable(string xml);
    /* tests implementations */
}

public class MsXPathDocumentTests : XPathDocumentTests {
    protected override IXPathNavigable CreateNavigable(string xml) {
        TextReader textReader = new StringReader(xml);
        XmlReaderSettings settings = new XmlReaderSettings();
        settings.IgnoreWhitespace = false;
        XmlReader reader = XmlReader.Create(textReader, settings);
        return new XPathDocument(reader, XmlSpace.Preserve);
    }
}

We’ll add the test fixture for our own implementation when we have the skeleton available. In the mean time, this lets us verify our expectations against the actual implementation of XPathNavigator.

The next post on the topic will tackle the new implementation’s design. I’ll make the implementation and test available as a source code download at the end of this series of articles.

I just had one of those moments…

And then, bang ! The solution jumps at me and it’s so obvious I almost felt shame

I was writing the unit tests in preparation for my next article on creating a XPathNavigator implementation. The code basically boils down to this:

TextReader textReader = new StringReader("<root>    </root>");
XmlReaderSettings settings = new XmlReaderSettings();
settings.IgnoreWhitespace = false;
XmlReader reader = XmlReader.Create(textReader, settings);
XPathDocument doc = new XPathDocument(reader);
var nav = doc.CreateNavigator().SelectSingleNode("/root/text()");
var success = nav.MoveToParent();

I am testing MoveToParent() from a whitespace node.

"/root/text()"

After some time, I decided to not put more effort into it and come back to it later, once I can take the necessary step back. I posted a question on stackoverflow.com and worked on something else.

I was busy on something completely different when it struck me. One of those “Haha” moments. XPathDocument has a constructor that takes a XmlSpace enum value. By default, if you don’t specify it, XPathDocument will simply skip all non-significant whitespace node.

// skips ignorable whitespaces
XPathDocument doc = new XPathDocument(reader);
// skips also
XPathDocument doc = new XPathDocument(reader, XmlSpace.Default);
// keeps non-significant whitespaces
XPathDocument doc = new XPathDocument(reader, XmlSpace.Preserve);

That’s it … annoying.

XPathDocument

XPathNavigator

First, what is an XPathDocument ?

An

XPathDocument

<order>
  <article id="1">
    <quantity>12</quantity>
  </article>
  <article id="5">
    <quantity>8</quantity>
  </article>
  <article id="6">
    <quantity>1</quantity>
  </article>
</order>

using the following code:

class Program {
    static void Main(string[] args) {
        XPathDocument doc = new XPathDocument(@"order.xml");

        XPathNavigator nav = doc.CreateNavigator();
        var articles = nav.Select("//article");
        foreach (XPathNavigator article in articles) {
            Console.WriteLine("{0}:{1}", 
                article.SelectSingleNode("@id").Value, 
                article.SelectSingleNode("quantity").Value);
        }
    }
}

XPath, once you get a hang of it, is very powerful and flexible for accessing Xml data. It allows for complex queries and computation.

Where’s the catch?

This is great but there is a drawback. As per the documentation,

XPathDocument

OutOfMemoryException

The good news is that we can do something about it.

How does XPath work in .Net?

In the above code snippet, you can see that the only reference to 

XPathDocument

XPathNavigator

XPathNavigator class

An

XPathNavigator

XPathNavigator

The data of the node pointed to by a navigator can be accessed using a set of properties. The most commonly used would be LocalName, NamespaceURI, Prefix but most importantly Value and its variants. NodeType is also important. The type of a node determines the allowed move operations supported.

public abstract string BaseURI { get; }
    public virtual bool HasAttributes { get; }
    public virtual bool HasChildren { get; }
    public virtual string InnerXml { get; set; }
    public abstract bool IsEmptyElement { get; }
    public abstract string LocalName { get; }
    public abstract string Name { get; }
    public abstract string NamespaceURI { get; }
    public abstract XmlNameTable NameTable { get; }
    public abstract XPathNodeType NodeType { get; }
    public virtual string OuterXml { get; set; }
    public abstract string Prefix { get; }
    public virtual IXmlSchemaInfo SchemaInfo { get; }
    public override object TypedValue { get; }
    public virtual object UnderlyingObject { get; }
    public override bool ValueAsBoolean { get; }
    public override DateTime ValueAsDateTime { get; }
    public override double ValueAsDouble { get; }
    public override int ValueAsInt { get; }
    public override long ValueAsLong { get; }
    public override Type ValueType { get; }
    public virtual string XmlLang { get; }
    public override XmlSchemaType XmlType { get; }

To move a validator around, the following methods can be used. Notice that all but one of them return a boolean. It indicates whether the move operation succeeded. True means the navigator now points to the new node, false, means it has not moved and still point to the original node. The only method that does not return a boolean is MoveToRoot() because it always succeeds.

An operation may fail for various reasons. For example, MoveToNext() will fail if the current node has no next sibling (eg. the last element of a sequence) or if the current node is an attribute. MoveToChild() will fail if there is no child of the current node that satisfies the conditions.

public abstract bool MoveTo(XPathNavigator other);
    public virtual bool MoveToAttribute(string localName, string namespaceURI);
    public virtual bool MoveToChild(XPathNodeType type);
    public virtual bool MoveToChild(string localName, string namespaceURI);
    public virtual bool MoveToFirst();
    public abstract bool MoveToFirstAttribute();
    public abstract bool MoveToFirstChild();
    public bool MoveToFirstNamespace();
    public abstract bool MoveToFirstNamespace(XPathNamespaceScope namespaceScope);
    public virtual bool MoveToFollowing(XPathNodeType type);
    public virtual bool MoveToFollowing(string localName, string namespaceURI);
    public virtual bool MoveToFollowing(XPathNodeType type, XPathNavigator end);
    public virtual bool MoveToFollowing(string localName, string namespaceURI, XPathNavigator end);
    public abstract bool MoveToId(string id);
    public virtual bool MoveToNamespace(string name);
    public abstract bool MoveToNext();
    public virtual bool MoveToNext(XPathNodeType type);
    public virtual bool MoveToNext(string localName, string namespaceURI);
    public abstract bool MoveToNextAttribute();
    public bool MoveToNextNamespace();
    public abstract bool MoveToNextNamespace(XPathNamespaceScope namespaceScope);
    internal bool MoveToNonDescendant();
    public abstract bool MoveToParent();
    public abstract bool MoveToPrevious();
    public virtual void MoveToRoot();

XPath queries?

That’s all very good but you might ask ‘what about XPath queries?’. XPath queries can be executed using the following functions:

public virtual object Evaluate(string xpath);
    public virtual object Evaluate(XPathExpression expr);
    public virtual object Evaluate(string xpath, IXmlNamespaceResolver resolver);
    public virtual object Evaluate(XPathExpression expr, XPathNodeIterator context);
    public virtual bool Matches(string xpath);
    public virtual bool Matches(XPathExpression expr);
    public virtual XPathNodeIterator Select(string xpath);
    public virtual XPathNodeIterator Select(XPathExpression expr);
    public virtual XPathNodeIterator Select(string xpath, IXmlNamespaceResolver resolver);
    public virtual XPathNodeIterator SelectAncestors(XPathNodeType type, bool matchSelf);
    public virtual XPathNodeIterator SelectAncestors(string name, string namespaceURI, bool matchSelf);
    public virtual XPathNodeIterator SelectChildren(XPathNodeType type);
    public virtual XPathNodeIterator SelectChildren(string name, string namespaceURI);
    public virtual XPathNodeIterator SelectDescendants(XPathNodeType type, bool matchSelf);
    public virtual XPathNodeIterator SelectDescendants(string name, string namespaceURI, bool matchSelf);
    public virtual XPathNavigator SelectSingleNode(string xpath);
    public virtual XPathNavigator SelectSingleNode(XPathExpression expression);
    public virtual XPathNavigator SelectSingleNode(string xpath, IXmlNamespaceResolver resolver);

Evaluate() returns a value dependent on the XPath query. The result can be an integer, a string or a node set etc. Matches() tells you whether the current satisfies conditions expressed as an XPath expression. The Select() functions return a node iterator over their result. That is a set of XPathNavigators each pointing to a node in the XPath expression result set.

So how do we solve our problem?

The key element that will help us solve our scaling issue lies in the implementation of the XPath querying methods (Evaluate, Match and Select). Their implementation is actually expressed in terms of Move() operations and property checks on XPathNavigators.

The following example uses on one hand Select() to find the <article> nodes of root element <order>, on the other hand, it uses a series of Move() operations to do the same.

private static void Example2Select() {
            XPathDocument doc = new XPathDocument(@"order.xml");

            XPathNavigator nav = doc.CreateNavigator();
            var articles = nav.Select("/order/article");
            foreach (XPathNavigator article in articles) {
                Console.WriteLine("node inner xml : {0}", article.OuterXml);
            }
        }

        private static void Example2Move() {
            XPathDocument doc = new XPathDocument(@"order.xml");

            XPathNavigator nav = doc.CreateNavigator();
            nav.MoveToChild("order", ""); // move to element order
            nav.MoveToChild("article", ""); // move to first element article

            do {
                Console.WriteLine("node inner xml : {0}", nav.OuterXml);
            } while (nav.MoveToNext("article", ""));

        }

All XPath queries can be expressed as a series of Move() and Clone() operations. This is exactly what Select() does behind the scene. This is where the design of the

XPathNavigator

XPathNavigator

Did you notice earlier that some of the Move() operations are virtual, others abstract ? In the same manner that XPath queries can be expressed as a series of Move() operations, most Move() operations can be expressed as a series of some of the most basic move operations. For example, the default implementation of MoveToRoot() is simply 

while (this.MoveToParent()) {}

XPathNavigator

This design hepls a lot in our case. We can get rid of the default .Net-provided

XPathNavigator

Below are the limited list of methods and properties that must be implemented in order to support XPath querying.

public abstract string BaseURI { get; }
    public abstract bool IsEmptyElement { get; }
    public abstract string LocalName { get; }
    public abstract string Name { get; }
    public abstract string NamespaceURI { get; }
    public abstract XmlNameTable NameTable { get; }
    public abstract XPathNodeType NodeType { get; }
    public abstract string Prefix { get; }

    public abstract bool MoveTo(XPathNavigator other);
    public abstract bool MoveToFirstAttribute();
    public abstract bool MoveToFirstChild();
    public abstract bool MoveToFirstNamespace(XPathNamespaceScope namespaceScope);
    public abstract bool MoveToId(string id);
    public abstract bool MoveToNext();
    public abstract bool MoveToNextAttribute();
    public abstract bool MoveToNextNamespace(XPathNamespaceScope namespaceScope);
    public abstract bool MoveToParent();
    public abstract bool MoveToPrevious();

As you can see, the minimum interface we need to support is not as big as we could have thought. We still have a lot to do though. We have to design our solution and implement it but more importantly, we need to write tests for it.

Conclusion

In a next post, we will setup a series of unit tests. These tests will be run against both the standard implementation (to ensure we understand the requirements correctly) and our new implementation (to make sure we stick to the requirements).

The design of

XPathNavigator

What the heck ! What for ?
Well, this cracked version is the same as the original game except the players are screwed, they cannot expand their in-game company above some limit due to …

Hum, well … Yes, piracy … Ironic, isn’t it ?

This really made my day I haven’t tested the game itself yet but it sure looks like fun.

In previous versions of C++, you needed to rely exclusively on documentation and conventions to ensure dynamically allocated memory was handled properly. With C++11, you can ask the compiler to help you out and enforce ownership semantics. Take the following code for example, you need to ensure you call delete when you are done with the object created by function factory(). The compiler will not complain if you forget and you end up with a memory leak.

struct A { int field; };
A* factory() { return new A(); }
void useFactory() {
    A* ptr = factory();
    std::cout << ptr->field << std::endl;
    // you must remember to call delete
    delete ptr;
}

What can std::unique_ptr do for you ?

With std::unique_ptr, you cannot casually forget to delete the pointer. std::unique_ptr owns the allocated object unless this ownership is explicitly transferred to another entity (eg. another unique_ptr, a std::shared_ptr). When a std::unique_ptr goes out of scope, it will delete any object it owns.

struct A { int field; };
std::unique_ptr<A> factory() { return std::unique_ptr<A>(new A()); }
void useFactory() {
    std::unique_ptr<A> ptr = factory();
    std::cout << ptr->field << std::endl;
    // ptr will delete allocated A automatically 
}

The most explicit way of transferring ownership is via function std::move(). Using the same above example, we can see how it works.

struct A { int field; };
std::unique_ptr<A> factory() { return std::unique_ptr<A>(new A()); }
void useFactory() {
    std::unique_ptr<A> ptr1 = factory(); 
    std::unique_ptr<A> ptr2 = std::move(ptr1);
    // now ptr2 owns the instance of A 
    // and ptr1 is holding a null pointer
}

You cannot directly assign an instance of std::unique_ptr to another. This rule ensures that no two unique_ptr can claim ownership of the same dynamically allocated object. It prevents deleting an object multiple times.
This is the magic of std::unique_ptr, you always know who owns the pointed value. By consistently using unique_ptr, you know at a glance when you own a heap object and when you yield ownership to another. Moreover, this rule is enforced by the compiler — the less you need to worry about, the better.

How do you use std::unique_ptr ?

std::unique_ptr helps you express your intent with regards to ownership transfer. Transfer of ownership occurs in the following general cases :

• Returning a dynamically allocated object from a function
• Passing a such an object to a function

Returning a std::unique_ptr

Returning a heap-allocated object from a function requires that the caller delete it when it is done with.

By returning a unique_ptr, you ensure the caller takes ownership of the pointed object. In the example below, the signature of createVector() ensures the caller takes the responsibility for releasing the created vector. Normal flow of execution guarantees memory will be released whenever the returned unique_ptr is destroyed.

typedef std::vector<int> Vector;
std::unique_ptr<Vector> createVector() { 
    return std::unique_ptr<Vector>(new Vector()); 
}

void caller() {
    std::unique_ptr<Vector> ptr = factory();
    // use the returned vector

    // nothing needs to be done here
    // the Vector will be deleted
}

Passing a std::unique_ptr to a function

A function taking a unique_ptr takes definitive ownership of the pointed object. The caller will not even have the ability to access the pointed object after the function call.
Notice the call to function std::move(), it is required and helps you actually see that ownership is transferred to the function.

void takePtr(std::unique_ptr<int> ptr) { /* ... */ }

void caller() {
    std::unique_ptr<int> ptr = new int(5);
    // explicitly transfer ownership with std::move
    takePtr(std::move(ptr));
    // now ptr holds a null pointer. takePtr() has effectively taken ownership.

    // a temporary (rvalue reference) is implicitly moved 
    takePtr(std::unique_ptr<int>(new int(6)));
}

Passing a const reference to a unique_ptr

The called function can use the pointed object but may not interfere with its lifetime. The caller function keeps ownership of the pointed object.

In my opinion, there is no real benefit to using a const reference to a unique_ptr from simply using a raw pointer to the object. On the contrary, it introduces a constraint on the caller that it must manage the pointed object through a unique_ptr. But what if your caller context requires you have shared ownership (std::shared_ptr)? Since we mostly care about whether ownership is transfered (not how ownership is cared for), a raw pointer is perfect.

void useUniquePtr(const std::unique_ptr<int> & ptr) { /* ... */ }
void useRawPtr(int * ptr) { /* ... */ }

void caller() {
    std::unique_ptr<int> ptr = new int(5);
    // useUniquePtr() can use but does not own the pointed object
    useUniquePtr(ptr);
    // same semantics
    useRawPtr(ptr.get());
}

Passing a non-const reference to a unique_ptr

This is, in my opinion, the most complex situation. The called function may or may not take ownership of the passed pointer. “may or may not” is really part of the functions contract. If the called function uses std::move() on the passed unique_ptr, it effectively takes onwnership and once it gives control back to the caller, the caller does not own the pointer anymore, it doesn’t even know the value of the pointer anymore. On the other hand, if the callee merely uses the provided pointer without moving it, the caller still owns the pointed object.

void useUniquePtr(std::unique_ptr<int> & ptr) { /* ... */ }

void caller() {
    std::unique_ptr<int> ptr = new int(5);
    useUniquePtr(ptr);
    // if useUniquePtr() used std::move() on ptr, it took ownership 
    // of the pointed int, so ptr is now holding a nullptr
    // otherwise it still owns the int and will delete it when the 
    // current scope ends
    if (ptr.get() == nullptr)
        std::cout << "ptr has been moved away" << std::endl;
    else
        std::cout << "ptr is still ours" << std::endl;
}

Conclusion

C++11 provides us with a great tool for managing the lifetime of dynamically allocated object. When used consistently, std::unique_ptr lets your code really express when ownership of a dynamic object is transferred and in which direction directly. The compiler will even see that the semantics are respected at compile-time.

However, they are of no use when you don’t intend to express ownership semantics. Pass raw pointers whenever you can but make sure that you use std::unique_ptr or another similar smart pointer when you mean to transfer ownership.

An interesting point is this :

8. Orthogonal specification of class serialization and archive format. That is, any file format should be able to store serialization of any arbitrary set of C++ data structures without having to alter the serialization of any class.

At first, I interpreted it as an intent to decouple the serialization code (that knows about the object’s internals) and the archive format.
Consider this:

struct ClassA {
    ...
    template <typename Archive>
    void serialize(Archive ar, unsigned int version) {
        ar & member1_;
        ar & member2_;
        ...
        ar & membern_;
    }
    ...
}

All is fine, ClassA does not know the specifics of type Archive. Any object implementing the Archive concept will do just fine.

Yet, I have a problem with this. Inline code in headers has a tendency to irritate me. It hides the structure of the classes you implement so I often use the PImpl idiom.
I want to (or must in the case of PImpl) move the implementation to ClassA.cpp.
But … can I ?

serialize() is a template method. Can I forward declare a template method ? Well, yes.

In ClassA.hpp :

struct ClassA {
    ...
    template <typename Archive>
    void serialize(Archive & ar, unsigned int version);
    ...
}

In ClassA.cpp:

template <typename Archive>
void serialize(Archive & ar, unsigned int version) {
    ar & member1_;
    ar & member2_;
    ...
    ar & membern_;
}

In main.cpp, try to serialize an instance of ClassA :

#include "ClassA.hpp"
#include <boost/archive/text_oarchive.hpp>
#include <boost/archive/text_iarchive.hpp>
#include <fstream>

int main(int argc, char ** argv) {
  ClassA a;

  std::ofstream ofs("output.txt");
  boost::archive::text_oarchive oa(ofs);
  oa << a;

  return 0;
}

Compile and link :

void ClassA::serialize<boost::archive::text_oarchive>(boost::archive::text_oarchive&, unsigned int)’
collect2: error: ld returned 1 exit status
make: *** [program] Error 1
Does this compile ? Yes. Does this link ? … No!

What’s the compiler trying to tell me ? Undefined reference to ClassA::serialize(…). But I defined it, no ?
Well, yes and no. You wrote the code but it is a template function. So it needs to be instantiated at compile-time. When main.cpp is compiled, it sees the forward-declaration of ClassA::serialize() and assumes that the linker will find the implementation of void ClassA::serialize<boost::archive::text_oarchive>(boost::archive::text_oarchive&, unsigned int) somewhere.
But it does not because, ClassA.cpp while implementing the template function does not instantiate it. ClassA::serialize() is parsed but never compiled into actual machine code.

You can check for yourself. Look at the file size :

940 bytes ? That’s not a lot.

You can force the instantiation of ClassA::serialize() in ClassA.cpp. Add the following at the end:

#include
template void ClassA::serialize(boost::archive::text_oarchive &, unsigned int);

It works, but is it good ? Not to me.

I need to include a header defining the implementation of the specific format I serialize to. I also need to include text_iarchive.hpp for the loading process to work. Tomorrow, when my object needs to be serialized to another format as part as another use case, I will need to modify its implementation file to include the specifics of that other format. I will need to do this for each and every class to be serialized … not something I would enjoy.

Conclusion

Templates provide a huge flexibility. Here it is used to enable the & operator to serve as both an extract and inject operator. However, it is at the expense of forcing the client application to put the saving/loading implementation in the same compile unit as the definitions of your target format. It completely voids the efforts put toward decoupling the serialized objects and the format they serialize to.

There are ways to achieve the same flexibility of ‘same operator’ saving and loading while preserving decoupling with the serialization format. I will come back to that in a later post.