Category.NET

Testing the boundaries of your Web APIs

How do you make sure an entire software you wrote works? And how would you do that if your system doesn’t have a UI? Well, simply by testing the boundaries of course!

From time to time I like to extract pieces of code from what I’m working on and create small repos just to showcase a single functionality or idea. 

This time I’m putting some efforts on TDD on APIs and after few refactorings I came up with a nice structure that you can use as a starting skeleton for a simple system. You can find all the sources here on GitHub.

The demo is very simple, just a single controller that stores and provides user details. Nothing fancy. The user model class exposes only three properties: id, full name and email.

Few points worth noting though:

  • the class is immutable. I wrote a bit about the concept here.
  • I’m adopting the Special Case (or Null Object) pattern a lot these days. Hence the NullUser static property.

Persistence is done in-memory as it’s obviously outside the scope. Moreover, as you can see the Tests project contains only the end-to-end tests, no unit/integration test to cover the persistence layer.

The testing infrastructure is where things gets interesting, even though it’s actually fairly straightforward. An XUnit Fixture is firing up a TestServer and bootstrapping the application using (possibly) the same settings as the real system.

A shared WebHostBuilderFactory class is indeed responsible of building the required IWebHostBuilder instance.

That’s it!

Ok, just to be honest, I got the idea from Mark Seemann : he has a very interesting course on Pluralsight named “Outside-in TDD“. If you have the chance, I strongly suggest you to watch it.

So, now that we have our nice infrastructure ready, all we have to do is write our tests! Being this a Web API, these might be considered either “functional” or “end to end”.

Honestly I think it’s simply a naming thing and doesn’t change the fact that probably these should be the first tests you would write.

Why? Because (and Mark explains it really well in his course) you’re ensuring from the consumer’s perspective that your APIs do what they’re expected to do.

You’ll be “testing the boundaries”.

But most importantly, you’re validating your acceptance criteria and making sure your system works. 

Everything else is just an implementation detail.

So what are we testing here? The routes of course! Our API is managing users, and being it RESTful, we’re asserting that all the http verbs are doing what we expect to do. 

Most of these tests should derive directly from the acceptance criteria written by your Product Owner. In case you don’t have one but instead rely on some (even vague) specifications, a good starting point is simply testing inputs and outputs. 

Happy testing!

Immutable Builder Pattern

This time we’ll talk about the Immutable Builder Pattern, but with a twist: the resulting instance has to be immutable.

From time to time I need to move away from the routine, just to avoid getting bored. Also, taking short breaks might help viewing things under a different perspective. Anyways, while working on Statifier I felt the need to get back to the roots and dive a little bit into the Design Patterns World ™ .

Straight from Wikipedia:

“the intent of the Builder design pattern is to separate the construction of a complex object from its representation”

This pattern is indeed extremely useful when you have to create an instance of a complex class, eg. with a long list of properties that have to be initialized.

It can be confused sometimes with the Factory pattern, but there’s a very important difference: Factories can be used to create an object instance based on some rules and return an interface. The result will be any concrete implementation of that interface, but consumers won’t (and don’t need to ) know which one.

Builders instead know how to create a single, specific class and the result is exactly an instance of that class.

And why should I be using the Builder if it can create just one thing? Well maybe because the creation is complex and requires several steps. Maybe you cannot just do something like builder.Build(param1, param2…..) , but you need a more structured approach.

The Wikipedia page has already some good examples of how the pattern can be implemented so I won’t talk much about that. 

But what is immutability anyway? Why do I need it?

At its core, immutability is a simple, very important concept: don’t let anyone from the outside update the internal state of your objects. That’s it.

Coding-wise, it translates basically into classes with no setters at all. All the properties will be initialized in the cTor, along with all the dependencies.

And why should I use it? Here’s an excellent article by Martin Fowler (yeah I love quoting him). Take your time, I’ll wait.

Ok so now let’s get back to out Builder. Here’s a sample implementation:

Few points to note:

  1. Vehicle cTor is private. Only the Builder can create an instance, and this is the main reason why the Builder class is declare inside the Vehicle class.
  2. all properties on Vehicle are get-only. Internal state cannot be changed, immutability is ensured. Good luck changing them.
  3. every call to Build() creates a new instance of Vehicle. This is again made to ensure immutability but comes with a twist: you have to be more careful if you want to reuse an instance of the builder to create more vehicles. You’ve been warned.

How an AppDomain can help you isolate your method calls

In one of my latest pet-projects (which with a bit of luck is about to become a real project, knock on wood!) I have been in need of executing code in total isolation form the containing application. 

Without giving too many details, the system allows plugins to be uploaded ( as standard .NET assemblies ), stored and eventually executed. However, in order to avoid a rogue plugin to jeopardise the entire application with nasty stuff like infinite loops or random exceptions, I needed a way to isolate their execution.

Being this a new project, I started writing it using .NET Core but had to revert very quickly to the ol’ reliable Framework. Seems that as of now Assemblies can be loaded in memory but there’s no way to unload them.
Just for the sake of documentation, the class responsible of loading is AssemblyLoadContext . Unfortunately loaded assemblies will be kept in memory till the containing process gets closed (more details here).

So what’s the alternative? AppDomains ! As often happens, the MS documentation does a pretty good job explaining what they are and how should be used so I’ll move straight to the point.

I wrote a small example and pushed it to GitHub, you can find it here.

The core is the Isolator class: as you can see from the code it can be instantiated passing the Type of the class you want to isolate and the name of the method you want to run on it. Something like this:

using (var isolatedFoo = new Isolator(typeof(Foo), “Bar”))
     isolatedFoo.Run();

Under the hood the Isolator will:

  • create a new AppDomain
  • load the assembly containing typeof(Foo) 
  • create an instance of Foo
  • execute the “Bar” method on said instance

Also, being a very polite class, it will unload the AppDomain during the Dispose() .

More under the hood, the real magic happens inside the IsolatorRunner class. As you can see from the code it inherits from MarshalByRefObject, this will allow the instance to act as an intermediary between the two AppDomains, with a proxy that will be automatically generated to intercept the calls on the other side.

Being this a quick example, I didn’t focus on the quality of the interfaces. So for example being forced to use a string to denote the method to execute is a little…disappointing. 

I’ll work a little more in the next days (weeks?) and try to come up with a nicer API, maybe using Expressions and Funcs 🙂

How to reset the entities state on a Entity Framework Db Context

I had two bad days. Those days wasted chasing a stupid bug. I had a test class with 4 test cases on my infrastructure layer. If executed one by one, they pass. If the whole suite was executed, only the first one was passing.

At the end I found out that it was due to the Entity Framework Core db Context tracking the state of the entities. More or less. 
In a nutshell, every time a call to SaveChanges() fails,  the subsequent call on the same instance of the db context will retry the operations. 

So let’s say your code is making an INSERT with bad data and fails. Maybe you catch that and then you do another write operation reusing the db context instance.

Well that will fail too. Miserably.

Maybe it’s more correct to say that the second call will look for changes on the entities and will try to commit them. Which is basically the standard and expected behaviour.

Since usually db context instances are created for every request this might not be a big issue.

However, in case you are writing tests using XUnit Fixtures, the instance is created once per test class and reused for all the tests in that class. So in this case it might affect test results.

A potential solution is to reset the state of the changed entities, something like this:

Another option is to avoid entirely reusing the db context and generating a new one from scratch.
In my code the db context was registered on the DI container and injected as dependency. I changed the consumer classes to use a Factory instead and that fixed the tests too 🙂

How to configure StructureMap to inject a typed logger

Logging is an essential part of every application. Might be dead simple as Console.WriteLine() or a complex third party library but every piece of software needs a way to communicate its status.

In my last project I have decided to use the wonderful NLog . One of the good things this library has is the possibility to add some contextual information to the messages, including (by default) the name of the calling class. Something like this:

2017-10-06 17:01:06.0417|INFO|MyAwesomeProgram.MyAwesomeClass|This is my message

As you can see, I have outlined with different colors the level, the name of the caller and the text.

This can be easily accomplished by something like this:

Using a static cTor to init the logger helps to  get a better stack trace in case GetCurrentClassLogger() throws an exception for some reason.

However, in case you’re using a DI container (as you should), it may become complicate to inject a valid Logger instance into each class.

Getting back to my project, for this I am using StructureMap as DI container. Usually I tend to stick with Simple Injector, but I just joined the team and it’s very important to follow the existing conventions.

The idea here is to use a wrapper class around the logger instance that takes as cTor parameter the name of the calling class. I’m using a wrapper just to avoid coupling with a third party library: usually you wouldn’t change from a logging library to another unless you’ve a very good reason for, but this principle applies basically to anything.

Next step is to configure StructureMap to return each time a new instance of the LoggerWrapper with the proper calling class name. And that’s actually the easy part!
Here’s the full code:

As you can see the magic happens during the StructureMap setup: context.ParentType represents the type of the class that will receive the LoggerWrapper instance.

 

Now let’s take a step back. Logging falls into the category of “cross-cutting concerns” , which basically means that logging can be considered part of the “infrastructure” and of course not of the business logic of the application. Caching can be another good example.

That said, unless you really need to  write specific log messages in specific points of your application, another option could be using the Decorator pattern . The idea is pretty straightforward:

  1. create a FooLoggingDecorator class
  2. inject the logger
  3. wrap all the class methods
  4. add logging where needed

Now it’s up to you to decide which approach to take, they both have pros and cons. For example, injecting the logger in some case can imply a SRP violation. On the other hand, using a decorator requires wrapping all the inner class methods. Keep that in mind when you add stuff to your interfaces 🙂

[EDIT]
As Jeremy wrote in his comment, the StructureMap documentation suggests to use a logger convention instead which would  be (quoting):

“significantly more efficient at runtime because the decision about which Logger to use is only done once upfront” 

© 2018 Davide Guida

Theme by Anders NorenUp ↑