Asciidoctor Meets JBehave.

User story is one or more sentences in natural language or business language which captures the requirements of what end user wants to be implemented in the product we are developing.

User Stories typically have the form:

"In order to <receive benefit> as a <role>, I want <goal/desire>"

User stories are also documentation for our project, first of all because they express what the product should do, and second one because they will be used by our clients/stakeholders, to validate that we are building the right thing.

JBehave is a framework for Behaviour-Driven Development (BDD). BDD is an evolution of test-driven development (TDD) and acceptance-test driven design, and is intended to make these practices more accessible and intuitive to newcomers and experts alike. The core of JBehave from the point of view of end users are user story files, where we define stories that our product should meet to validate that we are aligned with what our client wants. A user story example in JBehave is:

	Users should receive alerts depending on price of stocks
	Narrative:
	In order to sell stocks at optimum price
	As a user
	I want to receive alerts when stock is above a price
	Scenario: Alerts are switched on/off depending on price and a threshold.
	Given a stock of <symbol> and a <threshold>
	When the stock is traded at <price>
	Then the alert status should be <status>
	Examples:
	|symbol|threshold|price|status|
	|STK1|10.0|5.0|OFF|
	|STK1|10.0|11.0|ON|

view raw example.story hosted with ❤ by GitHub

Note that first sentence is a description, then a narrative section which contains sentences of the form in order to, as a, I want. And finally the definition of scenarios that must meet this story to be considered completed.

So as you can see, story files are project documentation, and as project documentation would be awesome if we could add them inside our documents as documentation and not as simple plain text. And here is where Asciidoctor comes to action. Asciidoctor is a Ruby, Java and Javascript processor for converting AsciiDoc source files and strings into HTML 5, DocBook 4.5 and other formats. Your project may contain different kind of documents written in AsciiDoc like Software Design Specifications (SDS), manuals, or for example a test plan. And it is in test plan where including user stories, could be a really good improvement. And for this reason jbehave-asciidoctorj-extension has been developed.

Let's see an example. Suppose that we are writing a document where we want to test some user stories manually (apart of automatically of course) due to the criticality of the process:

	= Manual Tests
	In order to ensure the quality of our projects critical user stories are going to test it manually.
	These user stories are included in this document and testers should execute all of them.
	*Name:*
	*Date:*
	include::jbehave::userStories:src/**/*.story[initialLevel=1, manual=true]
	== Supervision
	Explanation of the global result of the test.

view raw manualTest.txt hosted with ❤ by GitHub

As you can see we have created a simple AsciiDoc document with some information. But the interesting part is include::jbehave::userStories:src/**/*.story[initialLevel=1, manual=true]. Note that we are including all jbehave userstories that are placed on src folder. This extension supports any valid glob expression. And at the end we can set two attributes, the first one is the initial level of the section where user stories will be rendered (remember that the first one is 0), and finally if the steps will be executed manually or not, which has a deep impact on final rendered document as we will see soon.

Our project has two story files:

	Narrative:
	In order to take decisions based on stock prices
	As a system
	I want to receive all stocks with their prices
	Scenario: Receiving stocks and prices
	Given stock server
	When I connect to it
	Then I receive all stocks

view raw refreshable_stocks.story hosted with ❤ by GitHub

	Users should receive alerts depending on price of stocks
	Narrative:
	In order to sell stocks at optimum price
	As a user
	I want to receive alerts when stock is above a price
	GivenStories: org/asciidoctor/asciidoctorj/extension/jbehave/userstory/refreshable_stocks.story
	Scenario: Alerts are switched on/off depending on price and a threshold.
	Given a stock of <symbol> and a <threshold>
	When the stock is traded at <price>
	Then the alert status should be <status>
	Examples:
	|symbol|threshold|price|status|
	|STK1|10.0|5.0|OFF|
	|STK1|10.0|11.0|ON|

view raw trade_alerts.story hosted with ❤ by GitHub

As you can see the second story has a dependency to the first story, which means that this second story is only valid if first story has passed successfully. Apart from this fact, we can set examples as tables as well.

So let's see an screenshot of previous document rendered:

I think it is important to note two blocks. The first one is the NOTE block. See that GivenStories are rendered as Admonition, and with a link pointing to another story; this is pretty important because clicking there it will move the page where that (precondition) story was defined, so you can also inspect what was that story about. The other interesting part is the Result part. Because we have set user stories as manual, the extension will render three checkboxes so tester can mark if the scenario passes, fails or also if he wants to add some comment.

So now there is no excuse to not adding user stories in your documents in a really fashion way.

You can see the code of this extension at: https://github.com/lordofthejars/asciidoctorj-extensions/tree/master/jbehave-asciidoctorj-extensions

We keep learning,

Alex.

Maman dit Annotate"travailler c'est bien", Bien mieux qu'être mal accompagné, Pas vrai ? (Papaoutai - Stromae)

Music: http://www.youtube.com/watch?v=oiKj0Z_Xnjc