Within this tutorial and related video, you will get a step-by-step guide on how to set up and start unit testing an Umbraco website. When it comes to unit testing an Umbraco website, for the most part, the code you need to write will be the same as a normal .NET website.
The main difference on an Umbraco site is that there are certain Umbraco-specific controllers, base types, and APIs that you will need to include within your testing process.
For the most part, mocking these special types is easy enough, however, like most things, some aspects are a little more involved and tricker to set up. An example of this is trying to mock CMS data that uses the Umbraco model builder. As mocking models builder involves quite a bit of code, I've created a separate article that focuses on that topic. For reference, you can find a link to that article here.
Aside from that, if you want to learn how to be a complete Umbraco unit testing hero, read on
How To Set Up Your Unit Test Library
To start creating unit tests within your solution, the first thing that you need to do is create a new project to contain your unit tests. This means your first task is to create a normal C# class library. To make this class library a test-specific library that you can use to test your website, there are two set-up tasks that you will need to perform.
First, you need to link your web project to your test project. Second, you need to install the test runners and the testing SDKs. Doing this will allow you to write and run your tests within Visual Studio. For this article, I will use NUnit, however, it's worth mentioning that there is nothing Umbraco-specific that prevents you from using any of the other popular .NET testing frameworks. So if you want to use the .NET test framework or xUnit, go for it!
Aside from needing to install these testing staples, you will also need to install a mocking framework. As the hands-down most popular .NET mocking framework is Moq, we will use that. Alternatively, I also always use a package called FluentAssertiations. FluentAssertiations will make your unit test code easier to understand, so I recommend you check it out if you have yet to come across it!
How To Test An Umbraco Controllers
Page Controllers
The first thing that you will likely want to start unit testing within your Umbraco site is your pages. Assuming you are following a code-first architecture, this means you need to learn how to unit test your controllers.
When it comes to rendering a page, Umbraco differs from a normal .NET website because the underlying routing within a CMS project differs. Due to this difference, Umbraco provides a number of Umrbaco-specific base controllers that you can use. This means that instead of inheriting from say Controller, you will inherit from one of these Umbraco controller types instead
If you want to learn more about these controller types you can read about them here, so I'm not going to cover the differences between the different controller types in detail here.
The takeaway is that if you want to create a normal page controller within Umbraco, you will need to create a controller that inherits from RenderController. An example of the code you would need to create is shown below:
It might be useful for people on older versions of Umbraco, to quickly point out that in earlier versions of Umbraco, RenderController used to support a parameterless constructor configuration, however, this is not the case anymore. From Umbraco 9 onwards, you need to provide a bunch of dependencies to your controller constructors. This means that if you want to unit-test RenderController, you will need to mock these incoming constructor arguments. Within your unit test, you will need to add some config that looks something like this:
API Controllers
Aside from rendering normal pages, you can also create and expose API endpoints within your Umbraco application. You can do this by creating a controller that inherits from UmbracoApiController and then adding your end-points in as actions. The good news is that unlike RenderController, UmbracoApiController does not force you to supply any constructor arguments. This means unit test UmbracoApiController is pretty easy. Take this API controller:
You can write tests against it without needing to mock anything:
Form Postbacks
On some pages, you might want to render a page that contains a form. The obvious challenge with handling forms is that users will need to post data back to your server in order for you to process it somehow.
Within Umbraco, you can deal with postbacks by creating a controller that inherits from SurfaceController. Let us say you had a surface controller that contained an action like this:
Within your form, you can set the post-back destination URL to this submit endpoint. With the form defined, dow do you test the action?
This covers all the basics you need to master in order to start unit testing your forms.
