What is Xamarin ?

xamagonSeveral months ago I wrote an article to share my experience of a web developer moving to the world of mobile applications development. I am working in this field using the Xamarin technology. And you might have heard that Microsoft just acquired Xamarin, but I will not speak about this topic in this blog post, I do not have any opinion at the moment regarding this news.

When I introduce myself as a Xamarin developer, I often have to explain what it means even to other developers. And this is why I am creating this blog post, to introduce not only the technology but also the entire platform.

The technology

“Oh, I see, it’s like Cordova” is an answer I get from time to time, which is a start. Well, if you imply that Xamarin helps building cross-platform mobile applications, it is correct, but it is not really “like” Cordova.

What I like with Xamarin is the fact that it allows me to create native applications like an Android or iOS developer would do. The only difference is that I do not use the same programming language, instead of Java/Kotlin or Objective-C/Swift, I use C#. Like an Android developer I deal with activities, fragments, intents, AXML files and like an iOS developer I use storyboards, view controllers, UIView controls…

So, if the only difference is the programming language, what is the advantage of using Xamarin? Well, if you develop a mobile application on only one platform it might not be very interesting to use it except if you only know C#. But if you create an application on several platforms, it becomes relevant, because you can share code between Android, iOS and Windows Phone for instance. All of your apps use the same programming language. For example you can create a library with a API client for you application and use it on Android, iOS and Windows Phone: write it once and use it three times.

It is also possible to use Xamarin.Forms to share code between the User Interface (UI) for the three platforms I previously mentioned. But I will not go into the details because I have not used this technology at the moment. I can only tell you that it used a similar XAML format than the one available on the Windows platform.

The tools

“But how do I write C# with Xcode?” You cannot, to develop mobile applications with C#, Xamarin provides an Integrated Development Environment (IDE) called Xamarin Studio which is available on Mac OS and Windows. You can also use a Visual Studio plugin to create Android and iOS apps from Windows, but keep in mind that you will still need a Mac for iPhone/iPad to be able to build and for the simulator.

Xamarin also provides their own Android simulator to test and debug android applications: the Xamarin Android Player, which is pretty good and available on Windows and Mac.

You can also monitor your applications with the Xamarin Profiler (still in preview at the moment) in order to track the memory allocations and to find potential memory leaks. It also allows to track time and to find bottlenecks. I used it to review the memory usage of an existing application and I was able to detect several anomalies easily, it is a very helpful tool.

The services

Xamarin not only provide tools to help us developing cross-platform applications, it also offers several services to improve the overall experience. Learning mobile apps development can be overwhelming at first, especially when you try to learn several platforms at the same time. The Xamarin University aims to help you in this matter, but it clearly targets organization and not individuals (it is expensive).

Xamarin also offers a cloud platform in order to test your applications on a lot of different devices: Xamarin Test Cloud. You can access more smartphones configurations than you will ever be able to get, you will be able to detect issues related to a specific OS version.

Once your applications is released you might want to monitor what is going on, is it stable? What are the errors my clients encountered? What the users do with the application? To answer these questions you can use the Xamarin Insights services. It will give you access to a dashboard allowing you to see a lot of useful information for your applications. But you will have to use the SDK and “plug it” inside your code base. So you have to plan it before your release if you want to use it, it is not something you just activate afterward.

Here is my introduction of the Xamarin platforms, I hope this helps you to gain a better understanding of what is Xamarin and what are the tools and services available with it. Xamarin is not just a technology it is also an entire ecosystem available to the developers who want to create native applications. You also have to keep in mind that some of these products might change in the future depending on the strategy of Microsoft for the entire Xamarin platform.

See you next time !

AkkaOfEmpires: Dependency Injection with Akka.DI

akkadotnet-logoIn my last AkkaOfEmpires blog post, I started to use dependency injection (DI) for my various actors, but it was made “by hand”. So today I will show how to do it with Akka.DI, which is a plugin bringing DI to Akka.NET.

My goal is to be able to ask the actor system for VillagerActor instances without having to specify their dependencies, I’ll let Akka.DI handle this job.

Here is the VillagerActor constructor having the dependencies:

public VillagerActor(IActorRef resourcesSupervisor, SubroutinesFactory subroutinesFactory)
{
    _resourcesSupervisor = resourcesSupervisor;
    _subroutinesFactory = subroutinesFactory;
    Profession = Profession.Idle;
}

And here is the use case:

// Program.cs
var system = AkkaOfEmpiresSystem.Start();
 
var supervisorProps = Props.Create<ConsoleResourcesSupervisorActor>();
var supervisor = system.ActorOf(supervisorProps);
 
var consoleSubroutinesFactory = new ConsoleSubroutinesFactory();
var villagerProps = Props.Create<ConsoleVillagerActor>(supervisor, consoleSubroutinesFactory);
var gatherer = system.ActorOf(villagerProps, "Gatherer");
gatherer.Tell(new GatherFruits());

Using Akka.DI

Now I will change this last part in order to use dependency injection. First there is a nuget to install, in my case I will use StructureMap for the Inversion of Control (IoC) container.

Install-Package Akka.DI.StructureMap

Now, if you want to use another one you can see the list of available Akka.DI extensions here.

First I will rework the SubroutinesFactory by extracting an interface.

public interface ISubroutinesFactory
{
    IActorRef CreateResourceHarvesterActor(IActorContext actorContext, IActorRef villagerActor);
}
 
public class SubroutinesFactory : ISubroutinesFactory
{
    public IActorRef CreateResourceHarvesterActor(IActorContext actorContext, IActorRef villagerActor)
    {
        var props = Props.Create<ResourceHarvesterActor>(actorContext.System.Scheduler, villagerActor);
        var resourceHarvesterRoutine = actorContext.ActorOf(props);
        return resourceHarvesterRoutine;
    }
}
 
public class ConsoleSubroutinesFactory : ISubroutinesFactory
{
    public IActorRef CreateResourceHarvesterActor(IActorContext actorContext, IActorRef villagerActor)
    {
        var props = Props.Create<ConsoleResourceHarvesterActor>(actorContext.System.Scheduler, villagerActor);
        var consoleActor = actorContext.ActorOf(props);
        return consoleActor;
    }
}

Like before, I have two factories: a “classic” one and another one for the Console GUI. I will use the latter in my DI configuration.

Akka.DI uses a dependency resolver to link the IoC container with the actor system, there is one avaialble in the nuget package. I can now update the code:

// Program.cs
static void Main(string[] args)
{
    var system = AkkaOfEmpiresSystem.Start();
    var container = GetDependencyContainer();
    var resolver = new StructureMapDependencyResolver(container, system);
 
    var villagerProps = system.DI().Props<ConsoleVillagerActor>();
    var gatherer = system.ActorOf(villagerProps);
    gatherer.Tell(new GatherFruits());
 
    system.AwaitTermination();
}
 
static IContainer GetDependencyContainer()
{
    var container = new Container(c =>
    {
        c.For<ISubroutinesFactory>().Use<ConsoleSubroutinesFactory>();
    });
    return container;
}

I have specified that every instance of ISubroutinesFactory will be automatically resolved as ConsoleSubroutinesFactory instances and that is what will happen when requesting a new VillagerActor from the system.

I have taken care of one of the two dependencies for the actor. The other one is tricky because it is a IActorRef instance which can refer to every type of actor in the system.

The easy way

Well, at the moment the only IActorRef I need to inject through DI is for the ResourcesSupervisorActor, so I can have the following workaround:

static void Main(string[] args)
{
    var system = AkkaOfEmpiresSystem.Start();
    var container = GetDependencyContainer(system);
    var resolver = new StructureMapDependencyResolver(container, system);
 
    var villagerProps = system.DI().Props<ConsoleVillagerActor>();
    var gatherer = system.ActorOf(villagerProps);
    gatherer.Tell(new GatherFruits());
 
    system.AwaitTermination();
}
 
static IContainer GetDependencyContainer(ActorSystem system)
{
    var container = new Container(c =>
    {
        c.For<ISubroutinesFactory>().Use<ConsoleSubroutinesFactory>();
        c.ForSingletonOf<IActorRef>().Use(system.ActorOf<ConsoleResourcesSupervisorActor>());
    });
    return container;

I defined the dependency as a singleton because I want the resources supervisor to be the same for all the villagers. But now every classes that will need a IActorRef dependency will have a supervisor actor when constructed through DI.

With some IoC containers it is possible to play with named instance and conditions over the constructor parameters to provide the correct instance. But… meh… it is painful to set up and I think it can be dangerous. Let’s try something else.

Another way

What I can also do to fix my problem is removing the dependency to the IActorRef. Instead I will inject a service that will provide the reference to the supervisor actor, like I did for the subroutine actor.

public interface ISupervisorsFactory
{
    IActorRef GetResourcesSupervisor();
}
 
public class SupervisorsFactory : ISupervisorsFactory
{
    public SupervisorsFactory(ActorSystem system)
    {
        _resourcesSupervisor = system.ActorOf<ResourcesSupervisorActor>();
    }
 
    private readonly IActorRef _resourcesSupervisor;
 
    public IActorRef GetResourcesSupervisor()
    {
        return _resourcesSupervisor;
    }
}
 
public class ConsoleSupervisorsFactory : ISupervisorsFactory
{
    public ConsoleSupervisorsFactory(ActorSystem system)
    {
        _resourcesSupervisor = system.ActorOf<ConsoleResourcesSupervisorActor>();
    }
 
    private readonly IActorRef _resourcesSupervisor;
 
    public IActorRef GetResourcesSupervisor()
    {
        return _resourcesSupervisor;
    }
}

Now this factory can be used by the VillagerActor like this:

public VillagerActor(ISupervisorsFactory supervisorsFactory, ISubroutinesFactory subroutinesFactory)
{
    _resourcesSupervisor = supervisorsFactory.GetResourcesSupervisor();
    _subroutinesFactory = subroutinesFactory;
    Profession = Profession.Idle;
}

And I can update my IoC container configuration to link everything.

static IContainer GetDependencyContainer(ActorSystem actorSystem)
{
    var container = new Container(c =>
    {
        c.For<ISubroutinesFactory>().Use<ConsoleSubroutinesFactory>();
        c.ForSingletonOf<ISupervisorsFactory>()
            .Use<ConsoleSupervisorsFactory>()
            .Ctor<ActorSystem>()
            .Is(actorSystem);
    });
    return container;
}

Here is the end of my introduction to Akka.DI for Akka.NET. It allows the instantiation of actor references without having to declare all their dependencies every time a new actor is needed. Yet using DI with Akka.NET can become tricky when these dependencies are others IActorRef. At the moment I prefer avoiding them as much as possible.

Feel free to share your own experience with Akka.DI when it comes to IActorRef.

See you next time!

AkkaOfEmpires: Extending the GUI and actor factory

akkadotnet-logoIn my last AkkaOfEmpires blog entry I started a Graphic User Interface (GUI), only on console mode, to display how the actors in my system behave. In this project I use the Akka.NET framework (implementation of the actor model)  to re-create some of the rules present in Age of Empires II.

I was able to add a “console” implementation for two actors on the three I currently have in the system. This last actor is harder to “override” because its creation is done by another actor. Here is the code I am talking about (inside the VillagerActor):

var props = Props.Create<ResourceHarvesterActor>(Context.System.Scheduler, Self);
var resourceHarvesterRoutine = Context.ActorOf(props);

An I would like to use the following implementation of the ResourceHarvesterActor.

public class ConsoleResourceHarvesterActor : ResourceHarvesterActor
{
    public ConsoleResourceHarvesterActor(ITellScheduler messageScheduler, IActorRef villagerAcor)
        : base(messageScheduler, villagerAcor)
    {
    }
 
    public override void Handle(ResourceHarvested message)
    {
        base.Handle(message);
        Console.WriteLine("1 unit of {0} harvested. (carrying {1}).", ResourceToHarvest, CurrentlyCarrying);
    }
}

But, as I said in my last article, I cannot directly use this class in the VillagerActor, because it would create a circular reference and I don’t want to have “GUI” classes in my “core” project.

I think this issue shows that there is some coupling in the VillagerActor, indeed the class directly use the Props API and the Context. I believe it would be a good thing to extract this part of the code and encapsulate it in a dependency.

An actor factory

To fix this issue I will create a factory which will deal with the creation of the subroutine for the other actors and I will be able to use this class as a dependency for the VillagerActor. This way I will remove some coupling in the code.

Here is the factory:

public class SubroutinesFactory
{
    public virtual IActorRef CreateResourceHarvesterActor(IActorContext actorContext, IActorRef villagerActor)
    {
        var props = Props.Create<ResourceHarvesterActor>(actorContext.System.Scheduler, villagerActor);
        var resourceHarvesterRoutine = actorContext.ActorOf(props);
        return resourceHarvesterRoutine;
    }
}

The method in this factory needs some parameters to do its job, first an actor context in order to access the Scheduler and to create the IActorRef instance, secondly the IActorRef for the VillagerActor needing the subroutine.

I can now update my code to use this new class.

public class VillagerActor : ReceiveActor
{
    private readonly IActorRef _resourcesSupervisor;
    private readonly SubroutinesFactory _subroutinesFactory;
 
    public VillagerActor(IActorRef resourcesSupervisor, SubroutinesFactory subroutinesFactory)
    {
        _resourcesSupervisor = resourcesSupervisor;
        _subroutinesFactory = subroutinesFactory;
        //...
    }
 
    //...
 
    protected virtual void ResourceHarvester(IHarvestResourceCommand command)
    {
        //...
 
        var resourceHarvesterRoutine = _subroutinesFactory.CreateResourceHarvesterActor(Context, Self);
        resourceHarvesterRoutine.Tell(command);
 
        //...
    }
 
    //...
}

Override in the GUI

Now, the good thing is that I can create another implementation for this factory in my Console GUI project to use the ConsoleResourceHarvesterActor instead of the regular ResourceHarvesterActor.

public class ConsoleSubroutinesFactory : SubroutinesFactory
{
    public override IActorRef CreateResourceHarvesterActor(IActorContext actorContext, IActorRef villagerActor)
    {
        var props = Props.Create<ConsoleResourceHarvesterActor>(actorContext.System.Scheduler, villagerActor);
        var consoleActor = actorContext.ActorOf(props);
        return consoleActor;
    }
}

And now I can update my program in the GUI project to inject the implementation I want.

static void Main(string[] args)
{
    var system = AkkaOfEmpiresSystem.Start();
 
    var supervisorProps = Props.Create<ConsoleResourcesSupervisorActor>();
    var supervisor = system.ActorOf(supervisorProps);
 
    var consoleSubroutinesFactory = new ConsoleSubroutinesFactory();
    var villagerProps = Props.Create<ConsoleVillagerActor>(supervisor, consoleSubroutinesFactory);
    var gathered = system.ActorOf(villagerProps);
    gathered.Tell(new GatherFruits());
 
    system.AwaitTermination();
}

(To avoid too much flooding on the console I put only one villager instead of three).

And when launching the application, we can see the following output, letting us know what is happening.

AkkaOfEmpires-Second

We now have what we wanted, information is displayed for each actor and we have a pretty good idea of what is going on. The overall behavior looks good.

In this post I showed a way to extract the logic of creating an actor in a dependency in order to override the behavior, you can find the entire solution here.

For the moment my project is quite small and I only have two levels in my class hierarchy, therefore this “factory” fix will be hard to continue in the future because I have to inject the dependencies at the “boundaries” (the Main() method in my case). In the next AkkaOfEmpires post I will introduce Dependency Injection (DI) when working with Akka.NET to remove this future problem.

See you next time!

AkkaOfEmpires: Refactoring and First GUI

akkadotnet-logoToday, I will continue my journey with my project named AkkaOfEmpires. In this project I implement some of the rules of the game Age Of Empires II using the actor model with Akka.NET. You can find the last entries about the project here and here.

In this blog post I will not add new functionalities related to the game, first I feel the need to change a few things I made. I want to change the communication between the VillagerActor and the ResourceHarvesterActor routine. See the code for these two classes below.

Here is 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)));
    }
}

And theResourceHarvesterActor:

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(ResourceToHarvest, CurrentlyCarrying));
        else
            _messageScheduler.ScheduleTellOnce(TimeSpan.FromSeconds(1), Self, new ResourceHarvested(), Self);
    }
 
    public class ResourceHarvested { }
}

Refactoring

What I don’t like with this code is the fact that the “routine” sends the message to the resources supervisor directly. In my opinion the routine should notify the VillagerActor when the capacity is reached and then stops its process.

For me this child actor should not be aware of any actor except itself and its parent. The higher level actor will take care of the communication with the supervisor.

Akka.NET does not provide any shortcut to send messages to the parent of an actor, therefore we will have to inject the reference. We already have a parameter in the constructor of type IActorRef, for the supervisor, from now it will be a reference to the VillagerActor. The type does not change but the actor at the other side of this reference will, then it is extremely important to use proper names when manipulating IActorRef references.

private readonly IActorRef _villagerActor;
 
public ResourceHarvesterActor(ITellScheduler messageScheduler, IActorRef villagerAcor)
{
    _messageScheduler = messageScheduler;
    _villagerActor = villagerAcor;
    CurrentlyCarrying = 0;
}

I now need to refactor the case when the maximum capacity is reached. The villagerActor will be notify and will behave accordingly and the routine will be stopped.

public virtual void Handle(ResourceHarvested message)
{
    CurrentlyCarrying++;
    if (CurrentlyCarrying == MAX_CAPACITY)
    {
        _villagerActor.Tell(new MaxCapacityReached(CurrentlyCarrying));
        Context.Stop(Self);
    }
    else
        _messageScheduler.ScheduleTellOnce(TimeSpan.FromSeconds(1), Self, new ResourceHarvested(), Self);
}

To do this, I created a new message type names MaxCapacityReached with the amount of resource gathered. And to stop the actor I use the Stop() method of the Context property with Self as argument. By doing so the actor system will stop the current instance of the actor.

Now I need to update the behavior of the VillagerActor to properly use the ResourceGathererActor.

protected virtual void ResourceHarvester(IHarvestResourceCommand command)
{
    _currentCommand = command;
    Profession = command.AssociatedProfession;
    ResourceToRecolt = command.ResourceToRecolt;
 
    var props = Props.Create<ResourceHarvesterActor>(Context.System.Scheduler, Self);
    var resourceHarvesterRoutine = Context.ActorOf(props);
    resourceHarvesterRoutine.Tell(command);
 
    ListenForCommands();
}

I moved the creation of the child actor (the usage of Props and Context) inside the method (it was in the constructor before), because now the routine actor will stop once its job is done. If this is not done, the program will not crash, instead the message will not be delivered and will become a “dead letter” (more information on JVM Akka website here). Note that I also save the received command in a field, which will be used shortly.

Now this VillagerActor also need a new handler for MaxCapacityReached message in order to “return to a depot” to increase the amount of resources available.

protected virtual void ResourceCarrier(uint quantity)
{
    _resourcesSupervisor.Tell(new ResourceGathered(ResourceToRecolt, quantity));
    Self.Tell();
    ListenForCommands();
}
 
private void ListenForCommands()
{
    Receive<IHarvestResourceCommand>(m => Become(() => ResourceHarvester(m)));
    Receive<MaxCapacityReached>(m => Become(() => ResourceCarrier(m.Quantity)));
}

Once the message has been sent to the ResourceSupervisorActor the VillagerActor will send itself the command it previously stored, this way it will continue its job by creating a new child actor (a routine) to gather resources.

Now the question is: Does that really work as expected? I could try to make some tests to cover these cases but I fear that they will be extremely difficult to write. Instead I think it is time for me to create the first GUI for the project. Do not get too excited, I will simply be a Console GUI…

The Console GUI

280px-Age_of_Empires_2_The_Age_of_Kings_LogoTo display the behaviors of the actors, I could simply add some Console.WriteLine() in the methods but I don’t want to pollute the code of my actors with this. Instead I will use inheritance to add this behavior.

To be able to do this, I have to change a few private methods and make them protected virtual (see in the code samples above). And I can now define some ConsoleActors in a new project (AkkaOfEmpires.ConsoleUI).

ConsoleResourcesSupervisorActor:

public class ConsoleResourcesSupervisorActor : ResourcesSupervisorActor
{
    public override void Handle(ResourceGathered message)
    {
        Console.WriteLine("ResourceGathered: {0} {1}", message.Quantity, message.ResourceType);
        base.Handle(message);
        Console.WriteLine("Resources available: {0}: {1} | {2}: {3} | {4}: {5} | {6}: {7}",
            Resource.Food, ResourcesAmounts[Resource.Food],
            Resource.Wood, ResourcesAmounts[Resource.Wood],
            Resource.Gold, ResourcesAmounts[Resource.Gold],
            Resource.Stone, ResourcesAmounts[Resource.Stone]);
    }
}

ConsoleVillagerActor:

public class ConsoleVillagerActor : VillagerActor
{
    public ConsoleVillagerActor(IActorRef resourcesSupervisor)
        : base(resourcesSupervisor)
    {
    }
 
    protected override void PreStart()
    {
        Console.WriteLine("A new villager appears!");
        base.PreStart();
    }
 
    protected override void ResourceHarvester(IHarvestResourceCommand command)
    {
        Console.WriteLine("Villager becomes {0}", command.AssociatedProfession);
        base.ResourceHarvester(command);
    }
 
    protected override void ResourceCarrier(uint quantity)
    {
        Console.WriteLine("Villager carries {0} {1}", quantity, ResourceToRecolt);
        base.ResourceCarrier(quantity);
    }
}

This way I am able to separate the “UI logic” from the message handling of the actors.

I have also created a static method creating the actor system (in the AkkaOfEmpires project this time):

public static class AkkaOfEmpiresSystem
{
    public static ActorSystem Start()
    {
        var system = ActorSystem.Create("AkkaOfEmpires");
 
        return system;
    }
}

And here is the Main program of the console application:

static void Main(string[] args)
{
    var system = AkkaOfEmpiresSystem.Start();
 
    var supervisorProps = Props.Create<ConsoleResourcesSupervisorActor>();
    var supervisor = system.ActorOf(supervisorProps);
 
    var villagerProps = Props.Create<ConsoleVillagerActor>(supervisor);
    var gathered = system.ActorOf(villagerProps);
    gathered.Tell(new GatherFruits());
 
    var shepherd = system.ActorOf(villagerProps);
    shepherd.Tell(new ShepherdFlock());
 
    var lumberjack = system.ActorOf(villagerProps);
    lumberjack.Tell(new CutTrees());
 
    system.AwaitTermination();
}

This program will create the resources supervisor actor and 3 villagers, the first will become a gatherer, the second a shepherd and the last a lumberjack. Now if we launched this program we have the following ouput (after about 50 seconds).

AkkaOfEmpires-First

Looks good, the food and wood amounts increase over time, these villagers are now efficient workers!

But… What about a ConsoleResourceHarvesterActor? Well, this one is a bit different, its creation is directly inside the VillagerActor and not in the program. I cannot used this specific actor in the code of the VillagerActor (Circular reference between AkkaOfEmpires and AkkaOfEmpires.ConsoleUI) and I do not want to, a UI class has nothing to do in my core project.

The resolution of this “issue” will be in my next AkkaOfEmpires blog post. Meanwhile you can take a look at the entire solution on GitHub.

See you next time!

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!

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!