Tim Scott's Blog

October 8, 2010

Getting Started With Should Assertion Library

Filed under: Test Driven Development, Unit Testing — Tim Scott @ 7:04 pm

What Is It?

Should Assertion Library (“Should” for short) is a library of test assertion methods for .NET.  It is totally independent of, and completely compatible with any testing framework.  It was created by Eric Hexter, and I subsequently added a fluent interface which I ported from ShouldIt.  ShouldIt is now deprecated.

Should comes in two flavors:

  • normal (Should.dll)
  • fluent (Should.Fluent.dll).

Get It

You can get the latest binaries from NuPack or the project site.

By the way, if you haven’t tried NuPack yet, go get it right now!  You’ve got it? Okay, open the Package Management Console and enter:

> Install-Package Should


> Install-Package ShouldFluent

This will install Should as a package in the current solution.  You probably want to use either the fluent API or the normal API in any given test project – but not both.  Choosing one or the other will promote a consistent practice within your team.  Obviously, I prefer the fluent API.

Use It

There’s not much to say about usage.  It’s really pretty intuitive and discoverable.  Just start typing “.Should” after your actual object, and you will see what’s available.  To give you a taste, here’s a simple example:


Or fluently:


There are several examples of both the normal and the fluent syntax here.


A Note To ShouldIt Users: If you have been using ShouldIt, just remove the ShouldIt DLLs, add Should.Fluent.dll, and change the namespaces.  Everything should just work. Of course depending on which test framework you were using with ShouldIt, the underlying assertion behavior could change slightly. It should be pretty easy to spot the differences and make any small corrections as needed.

Goodbye ShouldIt, Hello Should Assertion Library

Filed under: Test Driven Development, Unit Testing — Tim Scott @ 7:00 pm

First There Was ShouldIt

Almost a year and a half ago I created ShouldIt.   Soon after I added a fluent API.  My goal was to create a test assertion library that would be portable across all major test frameworks.  This would allow me to move from project to project using the same nice test assertions without the sick feeling I was getting from copy-paste reuse.  So I created the API, sprinkled in a little MEF, stirred, and ShouldIt was born.  It felt really good.

My joy was dampened however by one nagging issue.  Although ShouldIt plugged nicely into any framework I might ever use, it carried with it a binary dependency to some particular version of each testing framework.  This made it really hard to distribute, and thus hard to achieve any kind of adoption.  This is probably why Eric Hexter yawned when I told him about ShouldIt.  He went looking for a better way.

Then Came Should

Recently he found it, and created Should Assertion Library (or “Should” for short) .  Whereas ShouldIt leveraged the assertion machinery of whatever test runner you might be using, Eric created a library with it’s own machinery, thus completely breaking any dependence on a testing framework.  On a side note, I had briefly considered doing this myself with ShouldIt.  I was cured of this notion by perusing the assertion source code in NUnit.  It is, uh, non-trivial.  So how did Eric pull it off?  Is he a more talented and dedicated programmer than I am?  Probably yes, but he did not create it either.  Rather, he forked the assertion machinery of xUnit (with the blessings of the xUnit folks).  Brilliant!

They Get Married

When I saw Should Assertion Library I knew immediately that this was the way to go.  My only complaint was that ItUsedVeryLongPascalCaseNamedAssertionMethods.  Okay, you either love the fluent style of assertions or you hate it.  I love it, and I refuse to go back.  So I decided to see how hard it would be to port ShouldIt’s fluent API bits into Eric’s project.  It turned out to be very easy, so I suggested to Eric that Should Assertion Library might support two styles: fluent and long name.  He agreed, and very soon the Should.Fluent assembly was created.

More: Getting Started With Should Assertion Library.

January 10, 2010

ShouldIt Is ILMerged

Filed under: Programming, Test Driven Development, Unit Testing — Tim Scott @ 6:49 pm

ShouldIt is a library of fluent specification extensions that works with all of the popular testing frameworks. My goal with ShouldIt is to provide a robust set of testing extensions that I can drop in to any test project, and it just works.

So far ShouldIt has met that goal, well mostly. One small friction point is the need to reference four DLLs (not counting the testing framework itself) in my test projects. No more. I have added an automated build that ILMerges all the required assemblies. And to make it easy for others to adopt ShouldIt, the download page now has a single file download for each testing framework.

July 17, 2009

ShouldIt Gets More Fluent

Filed under: C#, Test Driven Development, Unit Testing — Tim Scott @ 3:26 am

ShouldIt now gives you the option to use a more fluent syntax.  For example, the following:


Can now be expressed as:


You can still chain asserts as before.  So this:

    .ShouldContainOne(x => x.Id == exptected.Id)

Can now alternatively be expressed as:

    .Should().Contain.One(x => x.Id == exptected.Id)

The new syntax can be found in the ShouldIt.Clr.Fluent namespace in the Should.Clr assembly.

Why the new syntax?  Whether it’s more or less readable is largely a matter of taste.  For me, words separated by dots are an improvement over Pascal cased phrases.    However, the extra parentheses surely do not help. (Anyone else wish that parens were optional for calls to methods with no parameters?)  Nonetheless, I think that the new syntax has some nice advantages.

  1. Better Intellisense. With the old style, Intellisense offers a long list of every possible assertion for the target type.  It’s annoying to scroll through the list and/or type the entire word “should” plus one more letter before the list shirinks.  Using the new style, only one extension method appears at first.   As you type each new node, the list remains very small until you narrow down to the assertion that you want.   Overall I believe that this will facilitate faster and more accurate coding.
  2. More Maintainable And Extensible. The original extension methods all live together in one big fat static class.  The new code is more object oriented and spreads responsibilities over more small classes.  While this does not immediately provide any value to the user, it will make it easier to add nice features over time.

Give it a try and let me know what you think.

May 31, 2009

Reusable “Should” Extensions

Filed under: Test Driven Development, Unit Testing — Tim Scott @ 4:06 am

Should Extensions

UPDATE (6/9/09): Get the code here.

Some months ago I started wrapping my test asserts in fluent “should” extensions, like this:

public static T ShouldEqual<T>(this T actual, T expected)
    Assert.AreEqual(expected, actual);
    return actual;

Some of these extensions do a little more than just wrap assertions, for example:

public static T ShouldContainOne<T>(this IEnumerable<T> e, Func<T, bool> predicate)
    var match = e.ShouldContainAtLeastOne(predicate);
    if (match.Count() != 1)
        Assert.Fail("Expecting 1 matching item.  Found {0}.", match.Count());
    return match.First();

Reuse Dilemma

I put these extension methods in a static class in a helper project for re-use across test projects within the application.  Then one day I began work on a new application for a new client.  I love my “should” extensions and felt I could not live without them. Cut-and-paste to the rescue. Yuck. Now I am on to another application. Cut-and-paste again. Get me off this merry-go-round!

I considered creating a common assembly to share across my projects. However, as a consultant I prefer not to leave behind binary bits with this client and that client.

Making matters worse, the aforementioned applications do not all use the same testing framework.


So I have started developing a library of reusable “should” extensions that I am planning to release as open source – tentatively named “ShouldIt.” It will plug-and-play with all the major unit testing frameworks – with zero configuration using MEF.  To use it, with NUnit for example, you will reference ShouldIt.Core, ShouldIt.Clr and ShouldIt.NUnit in your test project.

You might be wondering, what is ShouldIt.Clr, and why is it separate from ShouldIt.Core?  ShouldIt.Clr will provide extensions to the CLR base class library types.  This leaves room to add, for example, ShouldIt.Watin.

By the way I considered writing my own assertions instead of wrapping those provided by the testing framework.  Then I opened NUnit and MbUnit in Reflector.  Whew!  There’s a lot more to those simple-looking assertions than I had expected.

Challenges And Questions

The biggest challenge I foresee is managing multiple binary dependencies to the testing frameworks.  This is mitigated by the fact that references will not be version specific.  Hence, pain will only be felt when the Assert APIs, more specifically those methods that ShouldIt calls, are changed.  I expect that those APIs are fairly stable.  That said, we can expect major releases to have breaking changes, as we have seen recently with MbUnit 3 (Gallio).

My questions for you:

  1. Anyone else feeling this pain?
  2. Has someone solved this already and I just have not seen it?
  3. Can you think of a better name than “ShouldIt?”

Blog at WordPress.com.