Authoring stories with NBehave 0.3

        Right now, I only care about finding by name.  It could be argued that the original story is too broad, but it will suffice for this example.  I’m confident those conversations will take place during iteration planning meetings in any case.
        
        Now that we have a story and a scenario, I can author the story in NBehave.  First, I’ll need to set up my environment to use NBehave.
        
        #### Setting up the environment
        
        I use a fairly common source tree for most projects:
        
        ![](http://s3.amazonaws.com/grabbagoftimg/NBehaveExample_SourceTree.PNG)
        
        All dependencies (i.e. assemblies in the References of my project) go into the “lib” folder.  All tools, like NAnt, NUnit, etc. that are used as part of the build go into the “tools” folder.  For NBehave, I’ve copied the “NBehave.Framework.dll” into the “lib” folder, and the entire NBehave release goes into its own folder in the “tools” folder.  For more information about this setup, check out [Tree Surgeon](http://www.codeplex.com/treesurgeon).
        
        Now that I have NBehave in my project, I’m ready to write some NBehave stories and scenarios.
        
        #### The initial scenario
        
        Before I get started authoring the story and scenario, I need to create a project for these scenarios.  If I have a project named MyProject, its scenarios will be in a MyProject.Scenarios project.  Likewise, its specifications will be in a MyProject.Specifications project.  You can combine the stories and specifications into one project if you like.  Finally, I create a class that will contain all of the stories in my “customer search” theme.
        
        I don’t name the class after the **class** it might be testing, instead I name it after the **theme**.  The reason is that the implementation of the stories and scenarios can (and will) change independently of the story and scenario definition.  **Stories and scenarios shouldn’t be tied to implementation details.**
        
        After adding a reference to NBehave and NUnit from the “lib” folder, Here’s what my solution tree looks like at this point:
        
        ![](http://s3.amazonaws.com/grabbagoftimg/NBehaveExample_SolutionTree.PNG)
        
        Note that I named my file after the theme, not the class I’m likely to test (CustomerRepository).  Here’s my entire story file:
        
        <div class="CodeFormatContainer">
          <pre><span class="kwrd">using</span> NBehave.Framework;

        story.AsA(<span class="str">"customer support staff"</span>)
            .IWant(<span class="str">"to search for customers in a very flexible manner"</span>)
            .SoThat(<span class="str">"I can find a customer record and provide meaningful support"</span>);

        story.WithScenario(<span class="str">"Find by name"</span>)
            .Pending(<span class="str">"Search implementation"</span>)

            .Given(<span class="str">"a set of valid customers"</span>)
            .When(<span class="str">"I ask for an existing name"</span>)
            .Then(<span class="str">"the correct customer is found and returned"</span>);
    }
} }

        A few things to note here:
        
          * Theme classes are decorated with the **Theme attribute** 
              * Themes have a mandatory title
              * Story methods are decorated with the **Story attribute** 
                  * The initial story is marked **Pending**, with an included reason</ul> 
                The attributes are identical in function to the &#8220;TestFixture&#8221; and &#8220;Test&#8221; attributes of NUnit, where they inform NBehave that this class is a Theme class and it contains Story methods.&nbsp; NBehave finds classes marked with the Theme attribute, and executes methods marked with the Story attribute.
                
                Now that we have a skeleton story definition in place, I can run the stories as part of my build
                
                #### Using the console runner
                
                New in NBehave 0.3 is the console runner, which runs the Themes and Stories and collects metrics from those runs.&nbsp; To run the above stories, I use the following command:
                
                <pre>NBehave-Console.exe NBehaveExample.Core.Scenarios.dll</pre>
                
                From the console runner, I get the following output:
                
                <pre>NBehave version 0.3.0.0 Copyright (C) 2007 Jimmy Bogard. All Rights Reserved.

                I only have one scenario thus far, but NBehave tells me several things so far:
                
                  * Dot results 
                      * A series of one character results shows me I have one scenario pending (similar to the dots NUnit outputs)
                      * Result totals 
                          * Includes total scenarios run, number of failures, and number of pending scenarios
                          * Individual summary result 
                              * List of failing and pending scenarios 
                                  * Name of&nbsp;story, scenario, and pending/failing reason</ul> 
                            
                            Let&#8217;s say I want a dry-run of the scenario output for documentation purposes:
                            
                            <pre>NBehave-Console.exe NBehaveExample.Core.Scenarios.dll /dryRun /storyOutput:stories.txt</pre>
                            
                            I&#8217;ve set two switches for the console runner, one to do a dry run and one to have a file where the stories will be output.&nbsp; Story output can be turned on regardless if I&#8217;m doing&nbsp;a dry run or not.&nbsp; Here&#8217;s the contents of &#8220;stories.txt&#8221; after I run the statement above:
                            
                            <pre>Theme: Customer search

Story: List customers by name

Narrative:
	As a customer support staff
	I want to search for customers in a very flexible manner
	So that I can find a customer record and provide meaningful support

	Scenario 1: Find by name
		Pending: Search implementation
		Given a set of valid customers
		When I ask for an existing name
		Then the correct customer is found and returned

                            This output provides a nice, human-readable format describing the stories that make up my system.
                            
                            Now that I have a story, let’s make the story pass, using TDD with Red-Green-Refactor.
                            
                            #### Make it fail
                            
                            First, I’ll add just enough to my story implementation to make it compile:
                            
                            <div class="CodeFormatContainer">
                              <pre>[Story] <span class="kwrd">public</span> <span class="kwrd">void</span> Should_find_customers_by_name_when_name_matches() {
Story story = <span class="kwrd">new</span> Story(<span class="str">"List customers by name"</span>);

story.AsA(<span class="str">"customer support staff"</span>)
    .IWant(<span class="str">"to search for customers in a very flexible manner"</span>)
    .SoThat(<span class="str">"I can find a customer record and provide meaningful support"</span>);

CustomerRepository repo = <span class="kwrd">null</span>;
Customer customer = <span class="kwrd">null</span>;

story.WithScenario(<span class="str">"Find by name"</span>)
    .Given(<span class="str">"a set of valid customers"</span>,
        <span class="kwrd">delegate</span> { repo = CreateDummyRepo(); })
    .When(<span class="str">"I ask for an existing name"</span>, <span class="str">"Joe Schmoe"</span>,
        <span class="kwrd">delegate</span>(<span class="kwrd">string</span> name) { customer = repo.FindByName(name); })
    .Then(<span class="str">"the correct customer is found and returned"</span>,
        <span class="kwrd">delegate</span> { Assert.That(customer.Name, Is.EqualTo(<span class="str">"Joe Schmoe"</span>)); }); }

                            All I’ve done is removed the Pending call on the scenario and added the correct actions for the Given, When, and Then fragments.  The “CreateDummyRepo” method is just a helper method to set up a CustomerRepository:
                            
                            <div class="CodeFormatContainer">
                              <pre><span class="kwrd">private</span> CustomerRepository CreateDummyRepo() {
Customer joe = <span class="kwrd">new</span> Customer();
joe.CustomerNumber = 1;
joe.Name = <span class="str">"Joe Schmoe"</span>;

Customer bob = <span class="kwrd">new</span> Customer();
bob.CustomerNumber = 1;
bob.Name = <span class="str">"Bob Schmoe"</span>;

CustomerRepository repo = <span class="kwrd">new</span> CustomerRepository(<span class="kwrd">new</span> Customer[] { joe, bob });

<span class="kwrd">return</span> repo; }

                            I compile successfully and run NBehave, and get a failure as expected:
                            
                            <pre>F Scenarios run: 1, Failures: 1, Pending: 0

                            Now that I’ve made it fail, let’s calibrate the test and put only enough code in the FindByName method to make the test pass.
                            
                            #### Make it pass
                            
                            To make the test pass, I’ll just return a hard-coded Customer object:
                            
                            <div class="CodeFormatContainer">
                              <pre><span class="kwrd">public</span> Customer FindByName(<span class="kwrd">string</span> name) {
Customer customer = <span class="kwrd">new</span> Customer();
customer.Name = <span class="str">"Joe Schmoe"</span>;
<span class="kwrd">return</span> customer; }

                            NBehave now tells me that I have 1 scenario run with 0 failures:
                            
                            <pre>. Scenarios run: 1, Failures: 0, Pending: 0

                            The dot signifies a passing scenario.  Now I can make the code correct and put in some implementation.
                            
                            #### Make it right
                            
                            Since CustomerRepository is just sample code for now, it only uses a List<Customer> for its backing store.&nbsp; Searching isn&#8217;t that difficult as I&#8217;m not involving the database at this time:
                            
                            <div class="CodeFormatContainer">
                              <pre><span class="kwrd">public</span> Customer FindByName(<span class="kwrd">string</span> name) {
<span class="kwrd">return</span> _customers.Find(<span class="kwrd">delegate</span>(Customer customer) { <span class="kwrd">return</span> customer.Name == name; }); }

                            With this implementation in place, NBehave tells me I’m still green:
                            
                            <pre>. Scenarios run: 1, Failures: 0, Pending: 0

                            I can now move on to the next scenario.  If I had additional specifications for CustomerRepository not captured in the story, I can go to my Specifications project to detail them there.
                            
                            #### Where we’re going
                            
                            With NBehave’s console runner, I can now easily include NBehave as part of my build.  I’m not piggy-backing NUnit for executing and reporting tests, as I’m writing Stories and Scenarios, not Tests.  This option is still available to me and I can create stories inside of tests, so we’re not forcing anyone to use the Theme and Story attributes if they don’t want to.
                            
                            It’s a good start, but there are a few things still lacking:
                            
                              * Integration with testing/specification frameworks 
                                  * The story for authoring the “Then” part of the scenario still isn’t that great
                                  * Features targeted for automated builds/CI 
                                      * XML output 
                                          * A nice XSLT formatter for XML output 
                                              * HTML output of stories in addition to raw text 
                                                  * Integration with CC.NET</ul> 
                                                  * Setup/Teardown for stories/themes, with appropriate BDD names 
                                                      * Not sure, since having everything encapsulated in the story can direct my API better</ul> 
                                                Happy coding!