Akka.NET: Delegating work to child actors

akkadotnet-logoToday I will continue to present my work on AkkaOfEmpires, in this project I implement some of the rules from the game Age Of Empires II using the actor model with Akka.NET. You can have a look at the first step here.

In this last entry I introduced the concept of behavior switching using Akka.NET while providing an implementation for a villager (unit in the game) gathering various types of resources. In this article I will continue to work on the VillagerActor and I will mostly do refactoring.

280px-Age_of_Empires_2_The_Age_of_Kings_LogoFor the moment the villager has a dedicated method for all the professions he can have when gathering resource, see the class below.

public class VillagerActor : ReceiveActor
{
    private readonly IActorRef _resourcesSupervisor;
 
    public VillagerActor(IActorRef resourcesSupervisor)
    {
        _resourcesSupervisor = resourcesSupervisor;
        Profession = Profession.Idle;
    }
 
    public Profession Profession { get; private set; }
    public Resource ResourceToRecolt { get; private set; }
 
    protected override void PreStart()
    {
        base.PreStart();
        Become(Idle);
    }
 
    private void Idle()
    {
        CommandsHandler();
    }
 
    private void Gatherer()
    {
        Profession = Profession.Gatherer;
        ResourceToRecolt = Resource.Food;
        // repeat until new order or lack of bushes
        _resourcesSupervisor.Tell(new ResourceRecolted { ResourceType = ResourceToRecolt, Quantity = 10 });
 
        CommandsHandler();
    }
 
    private void Shepherd()
    {
        Profession = Profession.Shepherd;
        ResourceToRecolt = Resource.Food;
        // repeat until new order or lack of sheeps
        _resourcesSupervisor.Tell(new ResourceRecolted { ResourceType = ResourceToRecolt, Quantity = 10 });
 
        CommandsHandler();
    }
 
    private void Hunter()
    {
        Profession = Profession.Hunter;
        ResourceToRecolt = Resource.Food;
 
        _resourcesSupervisor.Tell(new ResourceRecolted{ResourceType = ResourceToRecolt, Quantity = 10});
 
        CommandsHandler();
    }
 
    private void Farmer()
    {
        Profession = Profession.Farmer;
        ResourceToRecolt = Resource.Food;
 
        _resourcesSupervisor.Tell(new ResourceRecolted { ResourceType = ResourceToRecolt, Quantity = 10 });
 
        CommandsHandler();
    }
 
    private void Fisherman()
    {
        Profession = Profession.Fisherman;
        ResourceToRecolt = Resource.Food;
 
        _resourcesSupervisor.Tell(new ResourceRecolted { ResourceType = ResourceToRecolt, Quantity = 10 });
 
        CommandsHandler();
    }
 
    private void Lumberjack()
    {
        Profession = Profession.Lumberjack;
        ResourceToRecolt = Resource.Wood;
 
        _resourcesSupervisor.Tell(new ResourceRecolted {ResourceType = ResourceToRecolt, Quantity = 10});
        CommandsHandler();
    }
 
    private void StoneMiner()
    {
        Profession = Profession.StoneMiner;
        ResourceToRecolt = Resource.Stone;
 
        _resourcesSupervisor.Tell(new ResourceRecolted { ResourceType = ResourceToRecolt, Quantity = 10 });
        CommandsHandler();
    }
 
    private void GoldMiner()
    {
        Profession = Profession.GoldMiner;
        ResourceToRecolt = Resource.Gold;
 
        _resourcesSupervisor.Tell(new ResourceRecolted { ResourceType = ResourceToRecolt, Quantity = 10 });
        CommandsHandler();
    }
 
    private void CommandsHandler()
    {
        Receive<GatherFruits>(m => Become(Gatherer));
        Receive<ShepherdFlock>(m => Become(Shepherd));
        Receive<HuntPrey>(m => Become(Hunter));
        Receive<FarmCrops>(m => Become(Farmer));
        Receive<CatchFish>(m => Become(Fisherman));
        Receive<CutTrees>(m => Become(Lumberjack));
        Receive<MineStone>(m => Become(StoneMiner));
        Receive<MineGold>(m => Become(GoldMiner));
    }
}

As you can see the code is quite redundant and there is already a lot of methods for the class. Yet a villager can do a lot more than simply gathering resource and I fear that my class will become too big. When working with Object Oriented Programming (OOP) I try to follow the SOLID principles and I feel like I’m starting to break the Single Responsibility Principle.

My goal is to create a child actor for the VillagerActor to deal with all the resource gathering to avoid having too much logic inside this class. But first I will do some refactoring.

Refactoring phase

You may have noticed that all the commands related to the resource gathering are similar, they are associated to a type of resource and to a profession, it looks like a good opportunity to introduce an interface for all of these commands.

public interface IHarvestResourceCommand
{
    Resource ResourceToRecolt { get; }
    Profession AssociatedProfession { get; }
}
 
public abstract class HarvestFood : IHarvestResourceCommand
{
    public Resource ResourceToRecolt
    {
        get { return Resource.Food; }
    }
 
    public abstract Profession AssociatedProfession { get; }
}
 
public abstract class HarvestWood : IHarvestResourceCommand
{
    public Resource ResourceToRecolt
    {
        get { return Resource.Wood; }
    }
 
    public abstract Profession AssociatedProfession { get; }
}
 
public abstract class HarvestGold : IHarvestResourceCommand
{
    public Resource ResourceToRecolt
    {
        get { return Resource.Gold; }
    }
 
    public abstract Profession AssociatedProfession { get; }
}
 
public abstract class HarvestStone : IHarvestResourceCommand
{
    public Resource ResourceToRecolt
    {
        get { return Resource.Stone; }
    }
 
    public abstract Profession AssociatedProfession { get; }
}

And now each command can inherit from the correct abstract class and just have to provide the profession associated to it (see some examples below).

public class FarmCrops : HarvestFood
{
    public override Profession AssociatedProfession
    {
        get { return Profession.Farmer; }
    }
}
 
public class CatchFish : HarvestFood
{
    public override Profession AssociatedProfession
    {
        get { return Profession.Fisherman; }
    }
}
 
public class CutTrees : HarvestWood
{
    public override Profession AssociatedProfession
    {
        get { return Profession.Lumberjack; }
    }
}
 
public class MineStone : HarvestStone
{
    public override Profession AssociatedProfession
    {
        get { return Profession.Miner; }
    }
}
 
public class MineGold : HarvestGold
{
    public override Profession AssociatedProfession
    {
        get { return Profession.Miner; }
    }
}

I can now update the implementation of the VillagerActor to use the properties available in the classes I just refactored to simplify it and to remove all the code duplication.

private void ResourceHarvester(IHarvestResourceCommand command)
{
    Profession = command.AssociatedProfession;
    ResourceToRecolt = command.ResourceToRecolt;
 
    _resourcesSupervisor.Tell(new ResourceRecolted { ResourceType = ResourceToRecolt, Quantity = 10 });
 
    ListenForCommands();
}
 
private void ListenForCommands()    // previously CommandsHandler()
{
    Receive<IHarvestResourceCommand>(m => Become(() => ResourceHarvester(m)));
}

In my opinion this is way cleaner than before even if the notion of one method by profession has been removed, we still have a property for this.

Now I think that I have a good base to add the child actor which will have a bit more logic than this current implementation.

The child actor

In Age Of Empires II, gathering resource takes time, a villager harvests resource one by one and brings them back to the a resource depot when his capacity is full. I will implement this logic in the new child actor called ResourceHarvesterActor. This actor is not a unit on its own, it will represent a subroutine of the villager.

public class ResourceHarvesterActor : TypedActor,
    IHandle<IHarvestResourceCommand>,
    IHandle<ResourceHarvesterActor.ResourceHarvested>
{
    private readonly ITellScheduler _messageScheduler;
    private readonly IActorRef _resourcesSupervisor;
 
    public const uint MAX_CAPACITY = 10;
    public uint CurrentlyCarrying { get; private set; }
 
    public Resource ResourceToHarvest { get; private set; }
 
    public ResourceHarvesterActor(ITellScheduler messageScheduler, IActorRef resourcesSupervisor)
    {
        _messageScheduler = messageScheduler;
        _resourcesSupervisor = resourcesSupervisor;
        CurrentlyCarrying = 0;
    }
 
    public void Handle(IHarvestResourceCommand message)
    {
        if (message.ResourceToRecolt != ResourceToHarvest)
        {
            ResourceToHarvest = message.ResourceToRecolt;
            CurrentlyCarrying = 0;
        }
        _messageScheduler.ScheduleTellOnce(TimeSpan.FromSeconds(1), Self, new ResourceHarvested(), Self);
    }
 
    public void Handle(ResourceHarvested message)
    {
        CurrentlyCarrying++;
        if (CurrentlyCarrying == MAX_CAPACITY)
            _resourcesSupervisor.Tell(new ResourceGathered { Quantity = CurrentlyCarrying, ResourceType = ResourceToHarvest });
        else
            _messageScheduler.ScheduleTellOnce(TimeSpan.FromSeconds(1), Self, new ResourceHarvested(), Self);
    }
 
    public class ResourceHarvested { }
}

To simulate the game logic, this actor will send a message to itself every second to increment the amount of resource the villager is carrying. To do so I use the ITellScheduler interface which is available in Akka.NET. This allows to set a delay before sending a message to an actor, in this case the actor is itself so I use the Self property. I chose to use this interface instead of an implementation to be able to inject the dependency to ease the testability of the class.

I also added a condition to detect when the villager is at full capacity, when it occurs then the ResourceSupervisorActor is used to increment the global counter for the resource being harvested (in the game the villager goes to the depot for this).

There is another game rule I implemented in this actor, the fact that a villager cannot gather several types a resource at the same time. For example if a lumberjack is ordered to go fishing, then the wood he is carrying is lost. I made a unit test to cover this case:

[Fact(DisplayName = "ResourceHarvesterActor Should Empty CurrentlyCarrying If Different Resource To Harvest")]
public void Empty_CurrentlyCarrying_If_Different_Resource_To_Harvest()
{
    _harvester.Tell(VillagerOrders.CutTrees);
    _harvester.Tell(new ResourceHarvesterActor.ResourceHarvested());
    _harvester.UnderlyingActor.CurrentlyCarrying.ShouldBe<uint>(1);
    _harvester.Tell(VillagerOrders.CatchFish);
    _harvester.UnderlyingActor.CurrentlyCarrying.ShouldBe<uint>(0);
}

Now I will use this new actor inside the VillagerActor.

public class VillagerActor : ReceiveActor
{
    private readonly IActorRef _resourcesSupervisor;
 
    public VillagerActor(IActorRef resourcesSupervisor)
    {
        _resourcesSupervisor = resourcesSupervisor;
        Profession = Profession.Idle;
 
        var props = Props.Create<ResourceHarvesterActor>(Context.System.Scheduler, _resourcesSupervisor);
        _resourceHarvesterRoutine = Context.ActorOf(props);
    }
 
    public Profession Profession { get; private set; }
    public Resource ResourceToRecolt { get; private set; }
 
    private readonly IActorRef _resourceHarvesterRoutine;
 
    protected override void PreStart()
    {
        base.PreStart();
        Become(Idle);
    }
 
    private void Idle()
    {
        ListenForCommands();
    }
 
    private void ResourceHarvester(IHarvestResourceCommand command)
    {
        Profession = command.AssociatedProfession;
        ResourceToRecolt = command.ResourceToRecolt;
 
        _resourceHarvesterRoutine.Tell(command);
 
        ListenForCommands();
    }
 
    private void ListenForCommands()
    {
        Receive<IHarvestResourceCommand>(m => Become(() => ResourceHarvester(m)));
    }
}

There is nothing particular in here except the fact that I used the Scheduler from the System (available through the Context) for the child actor. With the refactoring and the adding of a child actor, the VillagerActor has more the role of a coordinator than an actor since I remove all the logic from it. But this is a temporary situation, since I still have a lot of rules to implement, with time it will become a high level actor delegating work to child actors.

The code for the entire solution is available on my GitHub repository, it will allow you to see the entire project. Since I write the blog posts in parallel of the development of the solution itself it is likely that the code will change a lot with time due to constant refactoring. So it is possible that the code shown in the articles is not up-to-date when you read it, therefore do not hesitate the browse the changes in the repository’s history and to have a look at the different branches.

See you next time!

Switching the behavior of an Akka.NET actor

akkadotnet-logoI am quite interested by the actor model pattern and especially by using Akka.NET. So I wondered how I could learn it by practicing, the Petabridge’s boot camp is a very good start but I want to learn more by myself.

When I was a kid, I used to play a lot at Age Of Empires II: The Age of Kings, I played this game for hours and I still know a lot about the rules. This is a strategy game in real-time, where the player manage units to gather resources, expand on a map, build armies to defeat some opponents.

280px-Age_of_Empires_2_The_Age_of_Kings_Logo

When thinking about it I think it could provide a good and fun example to try Akka.NET in depth. There are a lot of different rules in the game and some of them are quite specific, and a unit in the game could be implemented by an actor, imagine all the interactions that can happened between all of these actors.

When writing these lines I am only at the start of this journey and I don’t know if it is a good idea, but still I want to try. I don’t think I will handle the movement of the units and the graphic interface, I will focus on the interactions between the different units, buildings and technologies.

The setup

For this demo I will show you how to switch the behavior of a villager depending on the message (command) he receives. In the game a villager can do a lot of things: gathering resources, constructing buildings, repairing them, even fighting. For the moment I will focus on the resources gathering part.

In order to see the different amounts of resource available to the player, I created an actor which will store them:

public class ResourcesSupervisorActor : TypedActor, IHandle<ResourceRecolted>
{
    public Dictionary<Resource, uint> ResourcesAmounts { get; private set; }
 
    public ResourcesSupervisorActor()
    {
        ResourcesAmounts = new Dictionary<Resource, uint>
        {
            {Resource.Food, 0},
            {Resource.Wood, 0},
            {Resource.Stone, 0},
            {Resource.Gold, 0}
        };
    }
 
    public void Handle(ResourceRecolted message)
    {
        ResourcesAmounts[message.ResourceType] += message.Quantity;
    }
}

You can notice that unlike in previous posts about Akka.NET, I used a new kind of actor: the TypedActor and I implemented an interface to specify the type of message this actor can handle. Now it is time to have a villager that will gather resources to increase these amounts.

The tests

I am using Specflow to write the acceptance tests I want to implement for the project and here are the firsts for the villager:

Feature: Villager Professions

Scenario: A villager recolts food when ordered to gather fruits
	Given I have a villager
	When he becomes a gatherer
	Then he recolts food

Scenario: A villager recolts food when ordered to becoma a shepherd
	Given I have a villager
	When he becomes a shepherd
	Then he recolts food

And below you will find the implementation of these steps.

[Binding]
public sealed class VillagerSteps : TestKit
{
    [AfterScenario]
    public void AfterScenario()
    {
        Shutdown();
    }
 
    [BeforeScenario]
    public void BeforeScenario()
    {
        _resourcesSupervisor = ActorOfAsTestActorRef<ResourcesSupervisorActor>();
    }
 
    private TestActorRef<VillagerActor> _villagerActor;
    private TestActorRef<ResourcesSupervisorActor> _resourcesSupervisor;
 
    [Given(@"I have a villager")]
    public void GivenIHaveAVillager()
    {
        var props = Props.Create<VillagerActor>();
        _villagerActor = ActorOfAsTestActorRef<VillagerActor>(props);
    }
 
    [When(@"he becomes a gatherer")]
    public void WhenHeBecomesAGatherer()
    {
        _villagerActor.Tell(new GatherFruits());
    }
 
    [When(@"he becomes a shepherd")]
    public void WhenHeBecomesAShepherd()
    {
        _villagerActor.Tell(new ShepherdFlock());
    }
 
    [Then(@"he recolts food")]
    public void ThenHeWillRecoltFood()
    {
        _villagerActor.UnderlyingActor.ResourceToRecolt.ShouldBe(Resource.Food);
    }
}

I am using Akka.TestKit and the shouldly library for the tests. With these scenarios we can understand that a villager can have several roles, even when gathering a single type of resource. I only put two professions in this example to shorten the code.

The villager implementation

Now I will show you the implementation of the villager actor to show how a behavior switching can be made when using Akka.NET.

public class VillagerActor : ReceiveActor
{
    private readonly IActorRef _resourcesSupervisor;
 
    public VillagerActor(IActorRef resourcesSupervisor)
    {
        _resourcesSupervisor = resourcesSupervisor;
        Profession = Profession.Idle;
    }
 
    public Profession Profession { get; private set; }
    public Resource ResourceToRecolt { get; private set; }
 
    protected override void PreStart()
    {
        base.PreStart();
        Become(Idle);
    }
 
    private void Idle()
    {
        CommandsHandler();
    }
 
    private void Gatherer()
    {
        Profession = Profession.Gatherer;
        ResourceToRecolt = Resource.Food;
        // repeat until new order or lack of bushes
        _resourcesSupervisor.Tell(new ResourceRecolted { ResourceType = ResourceToRecolt, Quantity = 10 });
 
        CommandsHandler();
    }
 
    private void Shepherd()
    {
        Profession = Profession.Shepherd;
        ResourceToRecolt = Resource.Food;
        // repeat until new order or lack of sheeps
        _resourcesSupervisor.Tell(new ResourceRecolted { ResourceType = ResourceToRecolt, Quantity = 10 });
 
        CommandsHandler();
    }
 
    private void CommandsHandler()
    {
        Receive<GatherFruits>(m => Become(Gatherer));
        Receive<ShepherdFlock>(m => Become(Shepherd));
    }
}

Like in my introduction to Akka.NET I used the ReceiveActor which allows me to treat several types of message and to do different actions depending on the context.

At the first the villager is idle and just wait to receive an order to get to work (just like in the game). At the moment he can only be ordered to gather food from bushes or from sheep. When one of these two order arrives the “profession” of this villager change and he begins his work, gathering food in these cases (message sent to the supervisor actor to increment the food amount).

Yet a gatherer can at anytime receive the order to become a shepherd and this is done by using the Become method available for this type of actor (I extract this behavior in a separate method to avoid duplication).

I have written the following test to check that a villager can change its behavior:

[Fact(DisplayName = "VillagerActor Should Be Able To Change Profession")]
public void Be_Able_To_Change_Profession()
{
    var villager = ActorOfAsTestActorRef<VillagerActor>(Props.Create<VillagerActor>(TestActor));
    var shepherdCommand = new ShepherdFlock();
    villager.Tell(shepherdCommand);
 
    var gatherCommand = new GatherFruits();
 
    villager.Tell(gatherCommand);
 
    villager.UnderlyingActor.Profession.ShouldBe(Profession.Gatherer);
}

Using this Become method is very helpful when designing Finite-State-Machine with Akka.NET.

A final word

This example is just an introduction regarding the behavior switching with the actor model, the example is quite simple at the moment. But I intent to make updates on the project to implement the rest of the possible gathering methods for a villager. There are a lot more rules to implement even in the area I just showed you.

I put the code on my GitHub account to allow you to browse the whole code and to see the improvements I will add over time. If you would like to see a particular set of rules implemented, let me know, I will continue to post articles about this project and the use of Akka.NET for it. And do not hesitate to tell me if you think something should be made differently, I am open to feedback.

See you next time!

From web to mobile development

desktop-mobileI started my developer career as a web developer, using PHP. Soon after I switched to the .NET ecosystem to continue web development using C# and the ASP .NET MVC framework. I was creating web applications for my entire professional life until recently.

A few months ago I started working on mobile applications for Android and iOS, yet still with C# thanks to Xamarin. I am creating this blog post to share how I feel after this change.

Why this choice

You might wonder why I decided to switch from web development to mobile development. Because I wanted to work on something new in order to learn new skills, even if I still have a lot to learn regarding web programming.

I also think that mobile applications still have a bright future, sure there are already a lot of them on the existing stores. But new mobile devices are coming, like the smart-watches, and they will provide new opportunities for the developers. It is a good time, in my opinion, to learn how to create applications for mobile devices.

At my current company there was an opportunity to work on the new Android and iOS applications using my favorite language (C#) so why not take this chance.

A new paradigm

I knew that the way of programming would change since I already experienced mobile applications development with a project on Windows Phone. But still I was not prepared for what I have to do and I don’t think I could have been prepared.

Unlike a website an application has a very specific life cycle, you don’t just answer a request with a response. Almost everything I learned building web applications does not help me, the paradigm is entirely new.

Asynchronous programming is mandatory in this world, if everything runs on the User Interface (UI) thread the application will freeze. I always wanted to improve my skills in this area, looks like I found a good opportunity for this goal.

The separation of concern is also different, no more Model View Controller (MVC), now it is time to use the Model View ViewModel (MVVM) pattern. Even if I already used it (WPF and Windows Phone), it was not at the same level and I still have a lot to learn.

And of course you have the emulators to test the application, each time you want to test you have to build and deploy it, you cannot just refresh the page to see the changes. The feedback loop is long, several minutes most of the time, therefore debugging feels slow and debugging is important when starting with this technology.

Outside the comfort zone

I started working on the applications about two months ago and I still have a lot to learn. I need to deal with two ecosystems I know nothing about (Android and iOS), two frameworks I know nothing about (Xamarin and MvvmCross) and the business requirements which are not the easiest to meet. But at least I know how to use C#.

At the moment I struggle everyday, I have a lot to take into consideration, mostly some “How?” questions related to my new development environment. and also a lot of “What if?”: “What if the network is not available?”, “What if this solution is too slow?”, “How to provide the best experience for our clients?”…

Sometimes I cannot manage to produce anything for an entire day, and to be honest I feel worthless, I feel like I am a fraud… How can I consider myself has a professional software developer if I am not able to produce anything of value with my work?

Well, I guess this how it feels to step outside my comfort zone and I think I am in a ravine of the learning phase.

Learning Rate With Ravines
Learning Rate With Ravines

I will not give up

The thing is, that I am not the only one in this situation, I am not the only one to struggle. In the team we all have to deal with the same amount of learning, senior developers and junior ones.

When I take a look at the journey I began two months ago I realize that the route is still long but I also learned a lot, I am more familiar with the concepts of asynchronous programming and those of the MVVM pattern.

If I want to consider myself as a professional I will complete my journey and I will learn the skills I lack in order to produce the value our clients expect. Even if my work is painful from time to time, I have no regret, this is a massive opportunity to learn. I will succeed no matter how much time I need. And I hope to be able to share some Xamarin tips and tricks on this blog in the future.

See you next time!

Software gardening

Butchart-Gardens-CanadaA few months ago I discovered a new manifesto related to software development: the Software Gardening Manifesto. Even if the manifesto has been initiated in 2015 (by Papapetrou Patroklos), the concept of software gardening exists for several years, Jeff Atwood wrote about this topic seven years ago.

If you work in software development like I do, you certainly know the struggle when it comes to explain your work to non-technical persons. Using the metaphor of a garden can be a helpful metaphor. But software gardening is not only that, it is also values and principles. I like what I read in this manifesto and this is why I am creating this blog post.

Deep dive into the manifesto

So, what is the definition of a software gardener when we take a look at the manifesto?

Software Gardeners are professionals who perceive software development in a different way. Our goal is to spread the word of our core values, be mentors for the new developers and create software that it is developed at the highest quality bar.

As someone who values the principles of the software craftsmanship movement, I share this definition since it looks similar as the definition of a software craftsman.

To find the analogy with a garden, let’s have a look at the “beliefs” present in the manifesto.

We treat software systems as gardens and code as flowers. Although we don’t disagree regarding software as a “craft”, we believe that software is a living and breathing “being”, not just an object, created using the best materials.

The fact that systems and code are considered as living entities implies that they need attention over time. Your code gets updated to add feature or to fix bugs, the system changes over time to be improved, refactoring phases occur. It is likely that the project you work on is updated everyday even if it is already in production, of course depending on the context, some features are removed to make room for new ones.

We constantly mentor young developers and we share our knowledge at every opportunity. Junior developers are like flowers that need to be irrigated to blossom. We are the water, the sun, the soil, the fertilizer for every (young) software professional.

Software gardening is not only about taking care of the code but also a community where the more experienced developers help the younger ones by sharing their knowledge and skills (water, sun, soil and fertilizer). It is about creating a community which is a value shared also by the software craftsmanship manifesto.

Software development is a lot more than slinging code. We know the practices and we apply them effectively. We make use of the most productive tools and our skill-set includes both soft and technical skills. We also understand that our overall attitude is what defines us as software gardeners.

Creating software and growing a garden both require tools and skills. And it is definitely better to have the right tools for the job and knowing how to use them effectively. Having values is also important in order to provide the best work as possible.

We care about our code and this care, we show it continuously, day by day, every moment in every single line of code we write.

Code is like a flower, it is delicate and needs proper attention in order to flourish. A mistake can have painful repercussions later, do not water your plants and they will die, do not refactor your code when needed and you will have to deal with technical debt.

We are not only able to respond to change but we are prepared about the endless – internal and external – environment reform.

I find this one very interesting because of the notion of “environment”. Growing a garden does not always require the same tools and techniques, it depends on the context. Is your garden in a forest, a plain, a jungle or maybe a desert? You definitely need to adapt to the constraints of the environment you work in. And it is the same for a software project, do you work for a small company or a big one? Is there a lot of processes or not at all? Is your team made of 4 developers or 20? Is the project new or an old legacy system from 10 years ago.

You need to adapt to all of these variables and they might change over time, nothing is finite, everything evolves, remember that: “The only constant in this world is change”.

We treat customers as the people who will walk in our garden and smell our fragrant flowers. Having said that we engage them from the first day, to make sure that all their needs, requirements and expectations will be met.

Collaboration is essential for a software gardener, working closely with the customers is mandatory in order to create the best possible result. Understanding them is important to be able to have a beautiful garden years after years, during all seasons.

Conclusion

Software gardening is about commitment, quality, pride and love for the code and systems we work on. In ways it is similar to the software craftsmanship with an emphasis on the “living” part of the code and the analogy of the garden environment with the software environment.

Remember also that it is just a manifesto so you have to read between the lines in order to fully understand the values and principles behind this approach.

To me it is refreshing to see a new metaphor for our profession/passion/craft/art that is not related to classical engineering work. Which is, in my opinion, not always a good comparison for software development. I recommend you to read Chris Aitchison‘s article on software gardener: You are NOT a Software Engineer!

See you next time!


Image credits:

http://positivegardening.com/top-10-most-beautiful-gardens-around-the-world/

Unit tests and protected methods

protected-padlockWhen working with Object Oriented Programming (OOP) languages we have the possibility to design our code and our classes using encapsulation. C# defines the “protected” accessibility level, which is accessible only from the containing class and from the types that inherits from this class. It is very helpful when you follow the Open-Closed Principle (OCP).

On the other side you might ask yourself how can we test the behavior of the methods if they are protected. And how to do so without breaking the encapsulation of the class.

Testing a protected method

I created a small custom class to expose my way of doing unit tests on protected methods, here is a class to test:

public class MyClass
{
    public int Counter { get; private set; }

    protected void IncrementCounter()
    {
        Counter++;
    }
}

The easiest thing I could do to be able to test my method is to replace the “protected” keyword by “public”. But I will not do that because, in my opinion when you write tests after the production code you should try to avoid updating the code as much as possible even to test it.

One other possibility is to make the method “internal”, this keyword specifies that the method can only be access from the current assembly. And then, for your tests project you can make them visible using the following attribute in the Properties/AssemblyInfo.cs file of your production project:

[assembly: InternalsVisibleTo("MyTestProject")]

This option is helpful when you want to limit the scope of an API defined in an assembly but without losing the ability to add unit tests on the entire project.

But again I will not use this trick to test my method, instead I will expose it using inheritance for my tests by creating a new class, only for testing purposes.

public class MyTestClass : MyClass
{
    public void ExposeIncrementCounter()
    {
         base.IncrementCounter();
    }
}

With this new class I can now test the behavior of the protected method without modifying it. And here is my test:

[TestMethod]
public void Test_MyClass()
{
    var myClass = new MyTestClass();
    myClass.ExposeIncrementCounter();
    myClass.Counter.ShouldBe(1);
}

Note that, once again, I use the Shouldly library to make my assertion.

Testing a call to a protected method

The other day one of my coworker was asking how can he test that a protected method is called when testing a public method. This is a tricky question and it depends on the context of your code. In his case the given method was not part of our project and therefore impossible to modify. He was still able to test the behavior of the method by mocking another class used by this protected method.

I think this experience is interesting because it shows that you can still write automated tests by going one level deeper. You might ask yourself if this is still a unit test. Maybe, maybe not but it is a test for your project.

And this story made me think: “How to test the call to a protected method?”. I created the following class to show you a way to be able to do so.

public class MySecondClass
{
    protected void InnerMethod()
    {
        //a lot of logic and dependencies
    }

    public void DoWork(bool doWork)
    {
        if (doWork)
        {
            InnerMethod();
        }
    }
}

In my case I want to test that, depending on the parameter’s value, the DoWork method calls the InnerMethod method. But without executing the code of the latter because it does too many things and therefore the test will be too long (if you have a similar situation you might have some code smells to fix).

To write my tests, this time I will slightly update the code to be able to do what I want. I am not a big fan of this but I don’t really see another option that will not imply more refactoring.

protected virtual void InnerMethod()
{
    //a lot of logic and dependencies
}

I simply made the method virtual in order to be able to override it. I did not really break the encapsulation, I just gave me more options. Now I can create a new class for testing purposes:

public class MySecondTestClass : MySecondClass
{
    public bool InnerMethodHasBeenCalled { get; private set; }

    protected override void InnerMethod()
    {
        InnerMethodHasBeenCalled = true;
    }
}

This class inherits from the class I want to test and does not modify its behavior regarding the DoWork method. It is a test double using the spy technique. I can now write the two following tests to check the behavior of the code.

[TestMethod]
public void Test_MySecondClass_False()
{
    var myClass = new MySecondTestClass();
    myClass.DoWork(false);
    myClass.IncrementCounterHasBeenCalled.ShouldBe(false);
}

[TestMethod]
public void Test_MySecondClass_True()
{
    var myClass = new MySecondTestClass();
    myClass.DoWork(true);
    myClass.IncrementCounterHasBeenCalled.ShouldBe(true);
}

If you write tests after writing the production code it is still possible to do so without changing too much of the code even with protected methods. If the code has been written using encapsulation there must be a reason for that and therefore the tests should not force you to break everything down.

What about private methods?

Now you might ask yourself, how to do this with private methods. With these kind of methods we cannot use inheritance for tests, so how?

Well you can use Microsoft Fakes to mock the calls to private methods, but in my opinion this is definitely overkill. Our projects should be testable without tools like this.

The other solution is to change the accessibility of the method to make it testable, because you believe that “Tests trump Encapsulation“.

But first, I think that when you want to test a private method, you should ask yourself some questions first. Why is this method private? Does it really needs to be private? Can I extract the logic inside into another class I will be able to test? Can I include its logic in the test of another method?

Using encapsulation should mean something from a design point of view. Writing tests after the code is better than writing no test at all. It also make you ask questions about the code you wrote: “What do I want to test?”.

And I think this is why we saw the arrival of practice such as Test Driven Development (TDD) to force us to ask these questions first in order to help us with the design and encapsulation of the production code. I will not enter in the debate of whether should you practice TDD or not. Or does TDD lead to good design or not. I don’t know enough to answer these questions and I especially think that it depends on the developer.

In this blog post I wanted to show you how to test protected methods without having too much impacts on the code, I hope it will help you. And always ask yourself about the Why when it comes to tests and only after the How.

See you next time!

Writing acceptance tests with Specflow

Specflow logo
Specflow logo

I already spoke about acceptance testing in older blog posts (here and here) but without showing any tool available to write them, until now! In this article I will show how it is possible to write acceptance tests using Specflow.

This framework allows you to write executable scenarios using the Gherkin syntax which is non technical and can be used by domain experts, business analysts, testers. And then the developers implement the tests details alongside the feature covered by these acceptance tests.

Setting up

Specflow can work easily with Visual Studio, do to so you have to install the extension available in the extensions manager (see screenshot below).

specflow-extension

This extension offers various file templates allowing to write test scenarios, I will come to this later. You will also need the nuget package for the test project where you will add the acceptance tests:

Install-Package Specflow

By default Specflow uses NUnit as unit test provider but you can change it through configuration if you want to, for example I will use MsTest for the demo, then I have to update the App.config file:

<configuration>
  <configSections>
    <section name="specFlow" type="TechTalk.SpecFlow.Configuration.ConfigurationSectionHandler, TechTalk.SpecFlow" />
  </configSections>
  <specFlow>
    <unitTestProvider name="MsTest"/>
  </specFlow>
</configuration>

You should now have everything needed to write your scenarios.

Adding a feature

It is time to create our first Feature file to define the behavior of our system. When adding a new file to the test project you should be able to choose the Feature File option (installed by Specflow):

adding-feature

This will create a .feature file containing scenarios definitions using the Gherkin syntax. For the example I have created a scenario testing the behavior of a simple calculator:

# Calculator.feature
Feature: Calculator
	I want to test the behavior of a Calculator

Scenario: Add two numbers
	Given I have a Calculator
	When I add 17 to 25
	Then the result should be 42

As you can see the syntax is very user-friendly and can be understood by everyone in the team (it’s just English!). Now if you try to run this test (the scenario) it will neither fail nor pass, it has no implementation therefore it will be skipped:

skipped-test

The test name has been generated from the scenario name, this allow you to make them clear. Scenarios can be written and committed/checked-in into the source control without adding failing tests which might break a build (depending on its configuration). Therefore they can be added early in the process and not at the end of the development cycle.

Creating the steps

In order to implement the scenarios of a feature, Specflow needs Step definitions to operate, you can use another file template to create a class defining the steps.

adding-steps

Or you can create the class yourself in order to obtain the following code.

[Binding]
public class CalculatorSteps
{
    [Given(@"I have a Calculator")]
    public void GivenIHaveACalculator()
    {
        ScenarioContext.Current.Pending();
    }
 
    [When(@"I add 17 to 25")]
    public void WhenIAddTo()
    {
        ScenarioContext.Current.Pending();
    }
 
    [Then(@"the result should be 42")]
    public void ThenTheResultShouldBe()
    {
        ScenarioContext.Current.Pending();
    }
}

The BindingAttribute allows Specflow to know that step definitions are present in the file, if you omit it there will be no binding between the feature and the steps, don’t forget it! It is also possible to generate the steps from the feature file using the right-click and the “Generate Step Definitions” option (very helpful).

With this implementation the scenario will still be skipped without failing, you now have a skeleton to work with. Now it is time for the developers to do their part of the work.

Implementing the code

I will now create a Calculator class with an Add method having two integer parameters and a Result property to expose the result.

public class Calculator
{
    public int Result { get; private set; }
 
    public void Add(int first, int second)
    {
        Result = first + second;
    }
}

I will also implement the steps to use my new Calculator class.

[Binding]
public class CalculatorSteps
{
    private Calculator _calculator;
 
    [Given(@"I have a Calculator")]
    public void GivenIHaveACalculator()
    {
        _calculator = new Calculator();
    }
 
    [When(@"I add 17 to 25")]
    public void WhenIAddTo()
    {
        _calculator.Add(17, 25);
    }
 
    [Then(@"the result should be 42")]
    public void ThenTheResultShouldBe()
    {
        _calculator.Result.ShouldBe(42);
    }
}

I used Shouldly to make my assertion in the last step. And now the test is green!

passing-test

We have implemented our first test using Specflow, congratulations! Yet this demo is not over, there are a few more functionalities I would like to show.

Using scenario parameters

Right now our scenario test only one combination for the Add method and I definitely don’t want to write a scenario for each combination I want to test. Of course Specflow can handle this, using a scenario outline.

# Calculator.feature
Feature: Calculator
	I want to test the behavior of a Calculator

Scenario Outline: Add two numbers
	Given I have a Calculator
	When I add <first> to <second>
	Then the result should be <result>
	
	Examples: 
	| first | second | result |
	| 17    | 25     | 42     |
	| 10    | 78     | 88     |
	| 2     | 25     | 27     |
	| 5     | -17    | -12    |

I will also need to update the step definitions to match the scenario outline, it is possible to add method parameters to steps and match them using regular expressions.

[Binding]
public class CalculatorSteps
{
    private Calculator _calculator;
 
    [Given(@"I have a Calculator")]
    public void GivenIHaveACalculator()
    {
        _calculator = new Calculator();
    }
 
    [When(@"I add (.*) to (.*)")]
    public void WhenIAddTo(int first, int second)
    {
        _calculator.Add(first, second);
    }
 
    [Then(@"the result should be (.*)")]
    public void ThenTheResultShouldBe(int result)
    {
        _calculator.Result.ShouldBe(result);
    }
}

My scenario can now take parameters and test several cases, I will have one test per example:

bad-test-naming

But as you can see the test names are not very relevant, Specflow use the first parameter value to generate these names and if you have several examples using the same example value it will be even less clear.

I know a trick to prevent that: adding a description parameter only for naming purposes.

| description | first | second | result |
| 17_25       | 17    | 25     | 42     |
| 10_78       | 10    | 78     | 88     |
| 2_25        | 2     | 25     | 27     |
| 5_minus12   | 5     | -17    | -12    |

good-test-naming

It is not perfect but it might help. If you know a better way, feel free to share it.

Using existing steps

Once a step is implementing you can use it again in another scenario, or even another feature so you will avoid a lot of duplication. In my example I will now add a scenario to test the subtraction of the Calculator class.

Scenario Outline: Sub two numbers
	Given I have a Calculator
	When I subtract <first> to <second>
	Then the result should be <result>

	Examples: 
	| description | first | second | result |
	| 17_59       | 17    | 59     | -42    |
	| 10_3        | 10    | 3      | 7      |

I will add the following method to the calculator class and the implementation of the new “when” step, the others already exist.

//Calculator.cs
public void Subtract(int first, int second)
{
    Result = first - second;
}
 
//CalculatorSteps.cs
[When(@"I subtract (.*) to (.*)")]
public void WhenISubtractTo(int first, int second)
{
    _calculator.Subtract(first, second);
}

And this is it, I now have two more tests without having to write a lot of testing logic.

sub-tests

It is essential to reuse existing steps when working with Specflow in order to avoid too much duplication.

Using the scenario context

Now I want to get rid of the Result property in my Calculator class because I think it does not “feel” right, I prefer having methods directly returning the result.

public class Calculator
{
    public int Add(int first, int second)
    {
        return first + second;
    }
 
    public int Subtract(int first, int second)
    {
        return first - second;
    }
}

But now I have a problem inside my steps, how can I test the result if it is returned in another step? I don’t want to refactor the entire feature. The good news is that I don’t need to, I will change the step definitions without touching the feature file.

I will use the ScenarioContext to pass data from one step to another, like this:

[Binding]
public class CalculatorSteps
{
    private Calculator _calculator;
 
    [Given(@"I have a Calculator")]
    public void GivenIHaveACalculator()
    {
        _calculator = new Calculator();
    }
 
    [When(@"I add (.*) to (.*)")]
    public void WhenIAddTo(int first, int second)
    {
        var result = _calculator.Add(first, second);
        ScenarioContext.Current.Add("result", result);
    }
 
    [When(@"I subtract (.*) to (.*)")]
    public void WhenISubtractTo(int first, int second)
    {
        var result = _calculator.Subtract(first, second);
        ScenarioContext.Current.Add("result", result);
    }
 
 
    [Then(@"the result should be (.*)")]
    public void ThenTheResultShouldBe(int result)
    {
        var actualResult = ScenarioContext.Current.Get<int>("result");
        actualResult.ShouldBe(result);
    }
}

The tests are passing again, I was able to refactor my production code (the Calculator class) without modifying the scenarios. Specflow creates a separation between the feature specification and its implementation.

Time to conclude

This is the end of my introduction to Specflow, which I believe is a great tool for writing acceptance tests. It is easy to write feature scenarios you can use as executable specifications. In my example I use English but it is also available in several languages, so your domain experts should have a very good excuse for not writing them.

Specflow is also simple to configure to be used inside Visual Studio to be coupled with your favorite automated testing framework and there is even auto completion in the feature file for the Gherkin syntax or to find existing steps.

It has a lot more functionalities I did not mention in this blog post. It can also work with Selenium in order to create end-to-end scenarios for web applications. You now have the tool to practice Behavior Driven Development (BDD) with your team.

Let me know if you would like to know more about Specflow.

See you next time!

Better testing experience with Shouldly

Shouldly Logo
Shouldly Logo

I am a strong believer in unit testing, I like to write lots of tests for my code in order to make sure I do not regress when implementing new features on my projects. I love having a safety net when working.

Then it is important to make sure that the tests are easy to write and that they give a good feedback when failing. When a test fails you should be able to know exactly where the code under test has an incorrect behavior to fix it as soon as possible.

Shouldly is a .NET assertion library very helpful for this matter, it provides a lot of extensions for various types making them easy to test. It is available on GitHub and as a Nuget package:

Install-Package Shouldly

Simple assertions

Let’s dive into the topic to see how it can be used, I’ll start with simple assertions on an integer value:

var value = 5;
value.ShouldBe(5);
value.ShouldBeGreaterThan(4);
value.ShouldBeGreaterThanOrEqualTo(5);
value.ShouldBeInRange(0, 10);
value.ShouldBeLessThan(6);
value.ShouldBeOneOf(2, 5, 7);

It is as simple as that, not need for any Assert method, Shouldly does it for you. And there are many more extensions to test about everything you want.

Now, we can have a look at the assertions available for the string type:

var myString = "foo";
myString.ShouldNotBeEmpty();
myString.ShouldNotBe(null);
myString.ShouldStartWith("f");
myString.ShouldEndWith("oo");
myString.ShouldNotContain("bar");
myString.ShouldBe("FOO", Case.Insensitive);

Likewise, Shouldly offers various methods in order to test a string value to make sure everything behaves as expected.

The library offers also some assertions to check the behavior of a method through actions:

Should.NotThrow(() => SuccessMethod());
Should.CompleteIn(() => SuccessMethod(), TimeSpan.FromMilliseconds(50));

As you can see you can write performances tests for your methods using the CompleteIn() method.

Specific error messages

Now that we have written some tests using Shouldly, let’s have a look at what happens when a test fails. As I said it is important to have comprehensive error messages when an error occurred in order to be able to debug quickly.

int value = 5;
value.ShouldBeGreaterThan(6);

Of course this test fails, and generates the following error message:

    value
        should be greater than
    6
        but was
    5

I find that this message is quite clear and gives us a good understanding of what went wrong, it even contains the name of the tested variable. Now let’s see how is the message with an enumerable.

var numbers = new[] { 1, 2, 4 };
numbers.ShouldBe(new []{1, 2, 3});
    numbers
        should be
    [1, 2, 3]
        but was
    [1, 2, 4]
        difference
    [1, 2, *4*]

The library highlights the difference for us, again I find the message pretty clean, especially when you compare it with the MSTest version:

var numbers = new[] { 1, 2, 4 };
CollectionAssert.AreEqual(new[] { 1, 2, 3 }, numbers);
CollectionAssert.AreEqual failed. (Element at index 2 do not match.)

Here are a few more examples.

Should.NotThrow(() => FailingMethod());
    Should
        not throw 
    System.ApplicationException
        but does
Should.CompleteIn(() => LongMethod(), TimeSpan.FromMilliseconds(50));
    Task
        should complete in
    00:00:00.0500000
        but did not

Shouldly is easy to install and easy to use and, in my opinion, makes testing code much clearer. It provides a lot of helpful extensions and if you find that one is missing you can contribute to the project to make it available to everyone.

I think that testing code should be treated with the same respect than production code and this is why it should me made as clean as possible and as understandable as possible, this way your tests are a part of the documentation of your code.

See you next time!