Current Version is 1.0.1.16. You can download it here or get the latest sources from the trunk.

Happy specifying . . .

The feature deals with chained properties on interfaces. Consider the following example: A presenter working against a composed passive view.

public interface IComplexView
{
    ISubView Header {get;set;}
}  

public interface ISubView
{
    string Description {get;set;}
} 

public class Presenter
{
    private IComposedView _view;        

    public Presenter(IComposedView view)
    {
       _view = view;
    }    

    public void Initialize()
    {
       _view.Header.Description = "Some caption . . ."
    }
}

A spec documenting the behavior of the presenter can now look like this if you’re using xUnit.BDDExtensions.

[Concern(typeof(Presenter))]
public class When_the_presenter_is_initialized : InstanceContextSpecification<Presenter>
{
     protected override EstablishContext()
     {
          The<IComposedView>().HasProperties();
     }   

     protected override void Because()
     {
           Sut.Initialize();
     }     

     [Observation]
     public void It_should_set_the_headers_caption()
     {
           The<IComposedView>().Header.Description.ShouldBeEqualTo("Some caption . . . ");
     }
}

A really large portion of the necessary glue code has been removed for that scenario. Only the HasProperties() extension method remains.

Great work, Sergey. I really like the implementation of that feature . . .

Damn it

The biggest addition is the new ReportGenerator

I’ve wanted this for quite a while now but never really found the time to implement it. After running the RunBuild.cmd in the "Build" folder of the trunk you’ll find the .exe in the "Deploy" folder. It’s still a bit raw but exactly what I need for my current client (yes, you heard right. xUnit.BDDExtensions is currently being picked up at my current client )

Here are the current console arguments:

/assembly configures the spec assembly to extract a report from one or more assemblies.

ReportGenerator.exe /assembly:SomeSpecAssembly
ReportGenerator.exe /assembly:C:\Test\SomeSpecAssembly.dll
ReportGenerator.exe /assembly:’C:\Path with spaces\SomeSpecAssembly.dll’ ReportGenerator.exe /assembly:SomeSpecAssembly /assembly:SomeOtherSpecAssembly

/generator configures the generator to use. There are currently two generators implemented. One building an ASCII .txt file which looks like this. In order to use it you have to run the generator with

ReportGenerator.exe /assembly:SomeSpecAssembly /generator:Text

The other creating an HTML file which looks like this. This is the default generator which is used when you omit the /generator argument.

The files created by the generator are created on a per assembly basis and named like the assembly with the suffix .html or .txt. By default they are created in the same directory the generator is run from.

You can change this by configuring a different folder via /path.

ReportGenerator.exe /assembly:C:\Test\SomeSpecAssembly.dll /path:C:\temp

The deployment has changed slightly

The build script now merges xUnit.BDDExtensions to a single assembly (the external Rhino.Mocks assembly is not needed any more). Same applies to the ReportGenerator which uses StructureMap and NVelocity internally.

Some small changes to the API

• Dependency<TDependency>() has been marked as obsolete in InstanceContextSpecification<T> and StaticContextSpecification.
• AutoDependency<TDependency>() has been marked as obsolete in InstanceContextSpecification<T>.
• An<TDependency>() and Some<TDependency>() have been added to both InstanceCOntextSpecification<T> and StaticContextSpecification.
• The<TDependency>() has been added to InstanceCOntextSpecification<T>,

Its mostly naming which has been changed. Some discussions at my current client made me realize that
it’s easier to describe the behavior of xUnit.BDDExtensions to developers who haven’t used the tool before with An<ICar>() in favor of Dependency<ICar>() and The<ICar>() in favor of AutoDependency<ICar>().

An<TDependency>() returns a new dynamic stub object every time it’s called. The<TDependency>() behaves differently. BDDExtensions has AutoMocking support built-in. Once you let the framework create your test object you’re able to access the automatically injected dynamic stubs with this method. Last but not least Some<TDependency>() provides the same behavior as An<T>(). It only returns a collection of newly created stub objects.

I’m going to write a more detailed documentation of the current version soon. So in case you’re interested in the BDDExtensions, stay tuned . . .

As you might know xUnit.BDDExtensions is using Rhino.Mocks behind the scenes, but hides a lot of the mechanics of the library. This was done in order to eliminate a lot of the ceremony in a specification, so that a writer of a specification could focus on its essence (Quote MASHUP from JP and Jeremy D. Miller ). However, especially when configuring and verifying behaviors Rhino.Mocks still shines through (with all its power).

So let’s take a closer look at the problem I’m referring to. It has to do with specifications which observe indirect outputs. The following code is part of a little object-to-object-mapper I wrote some months ago.

public class ExpressionBasedWriter<Target, PropertyType> : IWriteStrategy<Target>
{
	private readonly IExpressionHandler expressionHandler;
	private readonly MemberExpression memberExpression;

	public ExpressionBasedWriter(
		Expression<Func> memberSelector,
		IExpressionHandler expressionHandler)
	{
		this.memberExpression = (MemberExpression) memberSelector.Body;
		this.expressionHandler = expressionHandler;
	}

        public void WriteTo(Target instance, object value)
	{
		expressionHandler.Handle(new HandlerContext
                {
                      TargetInstanceType = instance.GetType(),
                      TargetInstance = instance,
                      ValueToWrite = value,
                      MemberSelector = memberExpression
                });
	}
}

It’s not so important to understand the full context of the code. The important part is in the body of the WriteTo() method. Do you see it? It constructs an instance and passes it into an internal dependency. The interesting question now is how to verify the indirect output passed to the dependeny in a spec…

Take 1: Overriding Equals and GetHashcode() in the indirect output class.

In case you correctly implemented both of these methods you could write a spec, that looks like somewhat like this.

    [Concern(typeof(ExpressionBasedWriter<,>))]
    public class When_something_is_about_to_be_written : InstanceContextSpecification<IWriteStrategy<TestDto1>>
    {
        private IExpressionHandler expressionHandler;
        private Expression<Func> targetExpression;
        private TestDto1 target;
        private string valueToWrite;

        protected override void EstablishContext()
        {
            targetExpression = x => x.StringProperty;
            expressionHandler = Dependency();
            target = new TestDto1();
            valueToWrite = "uninteresting value";
        }

        protected override IWriteStrategy CreateSut()
        {
            return new ExpressionBasedWriter(targetExpression, expressionHandler);
        }

        protected override void Because()
        {
            Sut.WriteTo(target, valueToWrite);
        }

        [Observation]
        public void should_form_a_context_and_pass_it_to_the_actual_expression_handler()
        {
            expressionHandler.WasToldTo(x => x.Handle(new HandlerContext
            {
                MemberSelector = (MemberExpression)targetExpression.Body,
                TargetInstance = target,
                TargetInstanceType = target.GetType(),
                ValueToWrite = valueToWrite
            }));
        }
    }

This works. Ok, but what I don’t like about this solution is that I expose the concrete HandlerContext class to the spec. Test isolation is broken here. Besides I have to be very carefully with my implementation of Equals in this case, although it might only be needed in the specification.

Take 2: Introduce a factory

You can prevent the direct exposure of the specification to the concrete HandlerContext by introducing a factory which abstacts the creation of the HandlerContext class away.

	public class ExpressionBasedWriter<Target,PropertyType> : IWriteStrategy<PropertyType>
	{
		private readonly IExpressionHandler expressionHandler;
		private readonly IHandlerContextFactory handleContextFactory;
		private readonly MemberExpression memberExpression;

		public ExpressionBasedWriter(
			Expression<Func> memberSelector,
			IExpressionHandler expressionHandler,
			IHandlerContextFactory handleContextFactory)
		{
			this.memberExpression = (MemberExpression) memberSelector.Body;
			this.expressionHandler = expressionHandler;
			this.handleContextFactory = handleContextFactory;
		}

		public void WriteTo(Target instance, object value)
		{
			var context = handleContextFactory.CreateContext(memberExpression, instance, value);
			expressionHandler.Handle(context);
		}
	}

	[Concern(typeof (ExpressionBasedWriter<,>))]
	public class When_something_is_about_to_be_written :
		InstanceContextSpecification<IWriteStrateg<TestDto1>>
	{
		private IExpressionHandler expressionHandler;
		private IHandlerContext handlerContext;
		private IHandlerContextFactory handlerContextFactory;
		private TestDto1 target;
		private Expression<Func> targetExpression;
		private string valueToWrite;

		protected override void EstablishContext()
		{
			targetExpression =  x => x.StringProperty;
			expressionHandler = Dependency();
			handlerContextFactory = Dependency();
			handlerContext = Dependency();

			target = new TestDto1();
			valueToWrite = "uninteresting value";

			handlerContextFactory.WhenToldTo(x => x.CreateContext((MemberExpression)targetExpression.Body, target, valueToWrite)).Return(handlerContext);
		}

		protected override IWriteStrategy CreateSut()
		{
			return new ExpressionBasedWriter(targetExpression, expressionHandler, handlerContextFactory);
		}

		protected override void Because()
		{
			Sut.WriteTo(target, valueToWrite);
		}

		[Observation]
		public void should_call_the_context_handler_factory_in_order_to_create_a_context()
		{
			handlerContextFactory.WasToldTo(x => x.CreateContext((MemberExpression)targetExpression.Body, target, valueToWrite));
		}

		[Observation]
		public void should_call_the_expression_handler_in_order_to_handle_the_created_context()
		{
			expressionHandler.WasToldTo(x => x.Handle(handlerContext));
		}
	}

Again, this works too. But is that really a path one should go? Introducing an additional factory + interface everytime one encounters an indirect output? Besides that, did you notice how the specification kind of degraded? So much additional noise now in there. This one causes me actually more pain than Take 1, which takes me to …

Take 3: A neat Rhino.Mocks feature

Leave the code from Take 1 as it is. Here’s how you can write the specification, without exposing it to the concrete HandlerContext class and without causing to much noise in the specification itself.

    [Concern(typeof(ExpressionBasedWriter<,>))]
    public class When_something_is_about_to_be_written : InstanceContextSpecification<IWriteStrategy<TestDto1>>
    {
        private IExpressionHandler expressionHandler;
        Expression<Func> targetExpression;
        private TestDto1 target;
        private string valueToWrite;

        protected override void EstablishContext()
        {
            targetExpression = x => x.StringProperty;
            expressionHandler = Dependency();
            target = new TestDto1();
            valueToWrite = "uninteresting value";
        }

        protected override IWriteStrategy CreateSut()
        {
            return new ExpressionBasedWriter(targetExpression, expressionHandler);
        }

        protected override void Because()
        {
            Sut.WriteTo(target, valueToWrite);
        }

        [Observation]
        public void should_form_a_context_and_pass_it_to_the_actual_expression_handler()
        {
            	expressionHandler.WasToldTo(x => x.Handle(Arg<IHandlerContext>.Matches(matcher =>
                       matcher.MemberSelector == targetExpression.Body &&
                       matcher.TargetInstance == target &&
                       matcher.TargetInstanceType == target.GetType() &&
                       matcher.ValueToWrite.Equals(valueToWrite))));
        }
    }

The interesting stuff happens around the generic Arg class. You can use it to specify a callback with which the indirect output can be verified.

Conclusion

In the past I mostly did what I demonstrated with Take 1 when I encountered a situation where I needed to verify indirect outputs. Introducing a factory for this was never really an option for me. I don’t see a real benefit there. The generic argument matching capabilities of Rhino.Mocks really close a gap for me and they’re what I’m going to use for solving similar situations from now on.

I hope I’m not the only kid on the street who didn’t know that this feature exists . . .

This little feature was added to the trunk today. Yes, no CreateSut() call. You can omit it for most of the simple scenarios. You can still override it, if you need/have to. It uses the AutoMocking capabilities of StructureMap internally.

I’m going to merge the different involved assemblies to a single assembly soon in order to make deployment a bit easier . . .

The main reason Dan North decided to use Should instead of all other  possibilities is, that Should implies that you can always question the behavior of your system. It isn’t written in stone. If you think the system doesn’t behave correctly any more, feel free to change or drop the particular spec.

I found this little comment of Dan North worth remembering . . .

Let’s start by looking back on my own efforts with testing and BDD. For about 2 years I wrote (what I consider to be) classical unit tests. Those tests followed strictly a “<MethodName>_<Scenario>_<Behavior>” naming convention originally proposed by Roy Osherove. Here’s short example of what I wrote that time.

[Fact]
public void RegisterSubscriber_NewSubscriber_SubscriberIsRegistered()
{
    var subscriber = new FakeSubscriber();

    subscriptionManager.RegisterSubscriber(subsriber);

    var wasRegistered = subscriptionManger
                                     .AllSubscriptionsFor()
                                     .Contains(subscriber);

    Assert.TruewasRegistered);
}

When changing my tests to a more BDD oriented style last august (if you’re interested why please read here), my style of writing tests changed to something that looked like this.

[Concern(typeof(SubscriptionManager))]
public class When_registering_a_subscriber_at_the_subscription_manager : InstanceContextSpecification
{
    ISubscriber subscriber;

    protected override void EstablishContext()
    {
        subscriber = new FakeSubscriber();
    }

    protected override SubscriptionManager CreateSut()
    {
        return new SubscriptionManager();
    }     

    protected override void Because()
    {
        Sut.RegisterSubscriber(subscriber);
    }

    [Observation]
    public void should_be_contained_in_the_list_of_subscriptions_for_the_subscribed_message()
    {
        subscriptionManger
           .AllSubscriptionsFor()
           .ShouldContain(subscriber);
    }
}

For me at that particular point BDD meant not much more than a bunch of proven practices in test design and a revised naming convention. So what might be wrong with the way the spec is written here (event in that context)?

1. It isn’t fully refactoring safe (to be fair, the classic unit test shown above wasn’t either). Try to rename the term SubscriptionManager (or RegisterSubscriber in the first example). No refactoring tool will help you renaming your existing specs. As a consequence I would strongly suggest not to encode type or member names into a specification.
2. It doesn describe behavior. It describes implementation. A spec should describe what a system under test is supposed to do, not how it achives it.  Do you see the word “list” here?

You could revise the spec like this.

[Concern(typeof(SubscriptionManager))]
public class When_registering_a_new_subscriber : InstanceContextSpecification
{
    ISubscriber subscriber;

    protected override void EstablishContext()
    {
        subscriber = new FakeSubscriber();
    }

    protected override SubscriptionManager CreateSut()
    {
        return new SubscriptionManager();
    }     

    protected override void Because()
    {
        Sut.RegisterSubscriber(subscriber);
    }

    [Observation]
    public void should_enable_the_subscriber_to_recieve_messages_he_is_interested_in()
    {
        subscriptionManger
           .AllSubscriptionsFor()
           .ShouldContain(subscriber);
    }
}

Having said this, IS THAT THE REASON why I consider wording be to so important to BDD?

No, not really. Nearly the same applies to classic unit testing, too.  We should take a closer look at BDD in order to reach the answer.

Was the example shown above even BDD?

IMHO Second no. The example isn’t BDD. It only shows a way how a part of BDD can be implemented, with a framework; be it xunit.bddextensions, SpecUnit, MSpec or any other tool out there.

Ahm, ok what is BDD then?

As I understand it so far, BDD was originally created to codify acceptance criterias of stakeholders into executable code in a way which preseverves most/all of the vocabulary the stakeholder uses. By that a shared language can be established between stakeholders.  (Greg Young wrote a nice post about the subtle difference between BDDs shared language and DDDs ubiquitous language, so I won’t repeat that here).  This shared language is ment to enhance the way different parties/stakeholders interact with each other, a way to enhance communication. And what is the primary utility used in the interactions between stakeholders in BDD? ==> The executable specifications. <==

Coming back to why wording is so important to BDD

What is especially interesting in BDD is, that as there’re different stakeholders, there’re also different kind of audiences, with possibly different kind of vocabulary.  So because BDD specs are targeted to be an acceptance criteria, they need to be written in the vocabulary of the people who will review them. This is a huge influence  besides all the more technical reasons I touched earlier which of course are relevant, too.

Does this make sense to you?

What bothers me lately is that this style mixes context and behavior under test into one fixture class name, which can be extremely long because of that. An example to clarify what I mean:

 public class When_adding_a_contact_to_a_user_with_no_existing_contacts { }
 

“Adding a contact” is the observed behavior in the context of “no existing contacts”. I believe
this should be more obvious, which made me thinking of how a syntax for this could look like.

Having said that, here is what I came up with. It’s heavily inspired by MSpec and RBehave.

[SpecificationFor(typeof(PatientService))]
public class A_patient_with_a_missing_first_name_is_not_allowed_to_be_persisted
{
      Given a_patient_with_a_missing_first_name = () =>
      {
      };

      When trying_to_save_the_patient = () =>
      {
      };

      It should_not_persist_the_supplied_patient = () =>
      {
      };

      It should_return_a_report_indicating_that_the_patients_first_name_is_required = () =>
      {
      };
}

A generated report for this code might look like this:

Specifications for “PatientService”

• A patient with a missing first name is not allowed to be persisted
  • Given a patient transfer object with a missing first name
  • when trying to save the patient
    • it should not persist the supplied patient
    • it should return a report indicating that the patients first name is required
      

I’m still not 100% happy with this, because there is some sort of duplication between the fixture name and the “givens” (at least in the shown example), but with this approach you

1. are able to separate context and behavior in a clean way,
2. can describe the context very fine grained (by having multiple “givens”)
3. and besides that it looks cool

I would like to hear opinions on that. Is this something worth implementing / adding to xUnit.BDDExtensions?
Or am I off the track with this?