Getting Started with ConventionTests

It is really easy to get started with ConventionTests, there are a number of included conventions that come out of the box:

• All Classes Have Default Constructor
• All Methods are Virtual
• Class type has specific namespace (for example, all dtos must live in the ProjectName.Dtos namespace)
• Files are Embedded Resources
• Project does not reference dlls from Bin or Obj directory

Others are being added over time and you can create your own custom ones

Writing your first Convention test

1. Using your favourite testing framework, create a new test. Lets call it:

entities_must_have_default_constructor

2. Define some types to validate against a convention

The following line get a list of all the types in the assembly that contains SampleDomainClass.

var itemsToVerify = Types.InAssemblyOf<SampleDomainClass>();

There are also overloads to restrict the types to a specific namespace within the assembly.

3. Assert the convention

Now we have a list of types to check, we can use one of the pre-built conventions and check all of the types against this convention:

Convention.Is(new AllClassesHaveDefaultConstructor(), itemsToVerify);

That's it!

When you run this convention, if any of the types don't meet with the chosen convention, it fails and an exception will be thrown, which will look something like this:

ConventionFailedException
Message = Failed: 'Types must have a default constructor'
-----------------------------------------------------------------

TestAssembly.ClassWithNoDefaultCtor
TestAssembly.ClassWithPrivateDefaultCtor

How cool is that!

Reporting

If you would like to use ConventionTests reporting features, you just have to opt in by specifying the reporter you want. This makes it easy to add your own reporters, for example a WikiReporter may be better than the HtmlReporter

In your Properties\AssemblyInfo.cs file add the reporters you want. This are global reporters which will report the results of all conventions.

[assembly: ConventionReporter(typeof(HtmlConventionResultsReporter))]
[assembly: ConventionReporter(typeof(MarkdownConventionResultsReporter))]

Then if you look in the directory where your test assembly is, there will be an html report called Conventions.htm, serving as living documentation!

Defining Conventions

If you want to define your own conventions, it is really easy.

Step 1
Create a new class, inheriting from IConvention, lets use the must have default constructor convention as an example

public class AllClassesHaveDefaultConstructor : IConvention<Types>
{
    public void Execute(Types data, IConventionResult result)
    {

    }
}

Step 2
Write the convention logic

var typesWithoutDefaultCtor = data.TypesToVerify.Where(t => t.HasDefaultConstructor() == false);
result.Is("Types must have a default constructor", typesWithoutDefaultCtor);

Final result

public class AllClassesHaveDefaultConstructor : IConvention<Types>
{
    public void Execute(Types data, IConventionResult result)
    {
        var typesWithoutDefaultCtor = data.TypesToVerify.Where(t => t.HasDefaultConstructor() == false);
        result.Is("Types must have a default constructor", typesWithoutDefaultCtor);
    }
}

IConventionResult

Currently convention tests supports two types of convention results, the one we have just seen is a normal result. The other type is a symmetric result, which is the result for a symmetric convention.

An example of a symmetric convention is ClassTypeHasSpecificNamespace. It can verify a particular class type (dto, domain object, event handler) lives in a certain namespace, but it will also verify that ONLY that class type lives in that namespace. new ClassTypeHasSpecificNamespace(t => t.Name.EndsWith("Dto"), "TestAssembly.Dtos", "Dto")

The result will look like this:

result.IsSymmetric(
    string.Format("{0}s must be under the '{1}' namespace", classType, namespaceToCheck),
    string.Format("Non-{0}s must not be under the '{1}' namespace", classType, namespaceToCheck),
    classIsApplicable,
    TypeLivesInSpecifiedNamespace,
    data.TypesToVerify);

Symmetric Conventions

Symmetric conventions will verify a convention and also the inverse of that convention.

An example of a symmetric convention is ClassTypeHasSpecificNamespace. It can verify a particular class type (dto, domain object, event handler) lives in a certain namespace, but it will also verify that ONLY that class type lives in that namespace.

In the above example, let us say 'Dtos must live under Project.Dtos'. This means that all data contains ALL TYPES in the assembly, correct data is a dto living in the Project.Dtos namespace. But we have two failure conditions.

The first is if a Dto is outside the Project.Dtos namespace, the convention fails. The second is if a non-dto class lives inside the Project.Dtos namespace.

How to use a symmetric convention

var types = new Types("Types in MyProject")
{
    TypesToVerify = typeof(MyDto).Assembly.GetTypes()
};
var convention = new ClassTypeHasSpecificNamespace(
    classIsApplicable: t => t.Name.EndsWith("Dto"), 
    namespaceToCheck : "MyProject.Dtos", 
    classType: "Dto");
Convention.Is(convention, types);

As you can see, symmetric conventions are no different to enforce