Click here to Skip to main content
15,173,299 members
Articles / All Topics
Technical Blog
Posted 25 Jan 2016

Tagged as



Better Test Documentation

Rate me:
Please Sign up or sign in to vote.
5.00/5 (1 vote)
25 Jan 2016CPOL2 min read
Better test documentation

Let's look at some tests.

Typical Test Folders

Ok, so we can assume there is some User and Controller functionality. But to really know more, we have to dig deeper.

User Tests

Looking at the User test folder, have we gained more insight? It is only when diving into UserTests that we get to see what our functionality really is. And here, we see the same old same old:

  • A class, testing many different (and separate) things regarding Users
  • Long tests names all starting with Given_Something_Then

I am going to make a statement: Well written tests serve as documentation.

Duplication and not adhering to the Single Responsibility Principle makes our tests hard to read, hard to maintain and we have to dig around in the code to figure out what is actually going on.

How can we make this better? By being specific! We can use namespaces/folders to extract duplication and serve as an overview of functionality. By following the Single Responsibility Principle, we can advance our initial understanding by having well named files that point to single area's of functionality.

Let's look at an example.

Content Tests

Right of the bat, we can see that we are dealing with content and more specifically content creation and publishing.

Content Tests Folders

Even more functionality is exposed by opening these folders. And when finally looking at the actual test classes, a very good overview what our code should actually be doing is gained.

Content Tests Folders

Up to this point, we have not read any code. This is much better than ContentTests and ContentFactoryTests would ever be. When reading the actual code, some attention needs to be paid to the namespace and class name to get all the information regarding the tests, but this is minor to the readability gained on a folder level.

namespace App.Tests.ContentCreation.WhenUpdatingContent
    public class ThrowExceptionIf

        public void BrowsableIdentifierNotSet()


        public void BrowsableDisplayNameNotSet()


Personally, I think this is great, but I would love to hear your comments, suggestions and improvements!

Image 6 Image 7 Image 8 Image 9 Image 10 Image 11

Image 12

This article was originally posted at


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Software Developer (Senior)
I write about Domain Driven Design, Clean Code and .net

Comments and Discussions

-- There are no messages in this forum --