XBehave – Exporting your Given, Then, When to html

For a project in my day job we have been using the excellent XBehave for our integration tests. I love XBehave in that it lets you use a Given, When, Then syntax over the top of XUnit. There are a couple of issues with XBehave that I have yet to find a neat solution for (unless I am missing something please tell me if this is the case). The issues are

1) There is not a nice way to extract the Given, When, Then gherkin syntax out of the C# assembly for reporting
2) The runner treats each step in the scenario as a separate test

To solve these to problems I am writing an open source parser that takes the xml produced by the XUnit console runner and parses it to a C# model. I can then use razor to render these models as html and spit out the resultant html.

This will mean that I can take the html and post it up to a wiki so every time a new build runs the tests it would be able to update the wiki with the latest set of tests that are in the code and even say whether the tests pass or fail. Allowing a business/product owner to review the tests, see which pieces of functionality are covered and which features have been completed.

To this end I have created the XUnit.Reporter github repository. This article will cover the parsing of the xml into a C# model.

A neat class that I am using inside the XUnit.Reporter is the AssemblyResource class. This class allows easy access to embedded assembly resources. Which means that I can run the XUnit console runner for a test, take the resultant output and add it to the test assembly as an embedded resource. I can then use the AssemblyResource class to load back the text from the xml file by using the following line of code:

AssemblyResource.InAssembly(typeof(ParserScenarios).Assembly, "singlepassingscenario.xml").GetText())

To produce the test xml files for the tests I simply set up a console app, added XBehave and then created a test in the state I wanted for example a single scenario that passes. I then ran the XUnit console runner with the -xml flag set to produce the xml output. I then copied the xml output to a test file and named it accordingly.

The statistics for the assembly model and test collection model are not aligned to what I think you would want from an XBehave test. For example if you have this single XBehave test:

public class MyTest
public void MyScenario()
"Given something"
._(() => { });

"When something"
._(() => { });

"Then something should be true"
._(() => { });

"And then another thing"
._(() => { });

Then the resultant xml produced by the console runner is:

<?xml version="1.0" encoding="utf-8"?>
<assembly name="C:\projects\CommandScratchpad\CommandScratchpad\bin\Debug\CommandScratchpad.EXE" environment="64-bit .NET 4.0.30319.42000 [collection-per-class, parallel (2 threads)]" test-framework="xUnit.net" run-date="2017-01-27" run-time="17:16:00" config-file="C:\projects\CommandScratchpad\CommandScratchpad\bin\Debug\CommandScratchpad.exe.config" total="4" passed="4" failed="0" skipped="0" time="0.161" errors="0">
<errors />
<collection total="4" passed="4" failed="0" skipped="0" name="Test collection for RandomNamespace.MyTest" time="0.010">
<test name="RandomNamespace.MyTest.MyScenario() [01] Given something" type="RandomNamespace.MyTest" method="MyScenario" time="0.0023842" result="Pass" />
<test name="RandomNamespace.MyTest.MyScenario() [02] When something" type="RandomNamespace.MyTest" method="MyScenario" time="0.0000648" result="Pass" />
<test name="RandomNamespace.MyTest.MyScenario() [03] Then something should be true" type="RandomNamespace.MyTest" method="MyScenario" time="0.0000365" result="Pass" />
<test name="RandomNamespace.MyTest.MyScenario() [04] And then another thing" type="RandomNamespace.MyTest" method="MyScenario" time="0.000032" result="Pass" />

If you look carefully at the xml you will notice a number of things which are counter-intuative. Firstly look at the total in the assembly element it says 4, when we only had a single test. This is because the runner is considering each step to be a separate test. The same goes for the other totals and the totals in the collection element. The next thing that you will notice is that the step names in the original test have had a load of junk added to the front of them.

In the parser I produce a model with the results that I would expect. So for the above xml it I produce an assembly model with a total of 1 test, 1 passed, 0 failed, 0 skipped and 0 errors. Which I think makes much more sense for XBehave tests.

Feel free to clone the repository and look through the parsing code (warning it is a big ugly). Next time I will be talking through the remainder of this app which is rendering the test results to html using razor.


  1. gregsdennis says:

    Have you seen StoryQ?

    1. I hadn’t seen StoryQ it does look quite interesting, thanks I will check it out

  2. adamralph says:

    I’m glad you’re enjoying xbehave!

    Regarding each step being a separate test, this is one of the key features of xbehave. The advantage is that when a step fails, the test runner tells you exactly which step that was.

    1. XBehave is awesome, am loving it. I know which is good for a developer to know which step fails but when you want to export the tests for viewing by a business or product owner they want to see the tests at a higher level. Each test to them is a requirement and they want to know if the requirement is done or not (whether the whole test passes or fails). Also I couldn’t find any other way of extracting the given, when then back out of my code for reporting hence the little tool.

      1. adamralph says:

        > when you want to export the tests for viewing by a business or product owner they want to see the tests at a higher level

        I totally agree. In fact, I’ve always been meaning to bake something into xbehave itself which can do this, but I’m not really sure where it would fit. E.g. see https://github.com/xbehave/xbehave.net/issues/12

        A tool which operates on the final output is probably a good way to do it for now. By the way, you’re not the only one who had this idea. 🙂 It may be worth also taking a look at https://github.com/appccelerate/xBehaveMarkdownReport to see what they’ve done over there.

      2. Thanks the xBehaveMarkdownReport is doing pretty much the same thing as me. My version allows me to provide a razor template which means I can format the html to my pleasing.

        It would be cool if the test runner had an option to provide a razor template to render the html. You could then define how the test result model looked. Then people would be free to render the test output however they wanted and it would be much more flexible. You could even use a default template if the user chose to output to html but did not provide one, giving you the best of all worlds. I would be happy to help work on this feature…

  3. adamralph says:

    I like the idea regarding the test runner, but bear in mind that there is no “xbehave test runner”. Since xbehave is an xunit extension, all the test running is done the xunit test runner you’ve chosen to use, e.g. xunit.console.exe, so the changes will have to be made to that runner.

Leave a Reply to adamralph Cancel reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s