Adding 'Living Documentation' to BDDfy

[liammclennan]

I like the notion of 'living documentation' as provided by http://www.relishapp.com/ and http://getgauge.io/, however I think BDDfy has the correct model (code -> documentation).

I'd like to add support for including markdown in the story class comments, and step method comments. The content then obviously flows through to the report. I've not investigated in depth, but I think this should be possible for both fluent and reflective syntaxes.

When I start a new development project I'd like to start by defining all of my stories and scenarios, complete with all known requirements, screenshots, links etc, and generating the report. From then on that document serves as a complete view of the project, its requirements and status.

The implementation is slightly complicated because comments are not available via reflection. It could be done by parsing source (ala http://dontangg.github.io/nocco/#section_5) but my preference is to rely on xml documentation and /// commments, that way msbuild deals with the parsing and source code is not required.

Generating the html report would require a Markdown->Html component, such as https://github.com/Knagis/CommonMark.NET/ or http://www.toptensoftware.com/markdowndeep/.

If I implement this will it get merged?

[JakeGinnivan]

Would have to have @MehdiK 's blessing too, but I like the idea.

There are a few considerations:

• I think we need filtering/grouping in the report. A giant flat list might not scale for this sort of thing? (Test grouping in reports #185)
• The model should be extensible, I could see a runtime API for when you are doing UI automation which turns your BDD test into a flow of screenshots each time the page transitions, or an action is performed.

It would be good to have a quick mockup as well just to think of the potential downsides/issues which could arise from this.

[liammclennan]

I think we need filtering/grouping in the report. A giant flat list might not scale for this sort of thing? (#185)

Absolutely, but this is orthogonal to what I am proposing. I've considered adding a third report option that creates an empty page with a json object containing all the data. Its much easier to build new report UIs by providing mappings json->DOM than to provide new stringbuilder based implementations in C#.

The model should be extensible, I could see a runtime API for when you are doing UI automation which turns your BDD test into a flow of screenshots each time the page transitions, or an action is performed.

Love the idea. At this stage I am just talking about passing through some markdown.

In general, if a story or scenario has markdown content then it makes sense to follow the title in the report, but this is up to the particular report implementation.

[robi-y]

Hi, I was lately suggesting on the chat to add living glossary as part of preparing a living documentation. If this fits also, please let me know, I might help. See also the new book on the subject I linked there.

[MehdiK]

I am personally not a big fan of code comments tbh. Story narrative, scenario title and step names should be descriptive enough to explain what the system does; so I'm not sure how much value adding extra comments provides; that said I am more than happy for that be be added. It's just one more offering for devs who find this useful.

a third report option that creates an empty page with a json object containing all the data

I love this idea.

[liammclennan]

Food for thought. My previous PR added a story image and story url (for linking to Trello, JIRA etc) so I'm not sure what other info I'd actually want to add.

[MehdiK]

I loved the story image and url. I would also like a way to inject the image into the story at runtime; e.g. screenshot for a broken UI test!