Grammar

What are the grammar modules to be provided and why?

Feature/Story

The Feature -> Scenario / Story -> Scenario style of BDDing makes it possible to define high level feature specs for my projects. The module will include:

• feature
• story
• scenario
• component -- for those situations when I need to describe the behavior of a component of the system in formal terms.

Given, When, Then (GWT)

I find that the combination of GWT and Feature/Story grammar really helps me mentally visualize the desired behavior of the code I'm crafting.

Challenge - no "expect" in Suite

An additional requirement for this module would be to provide "and" and "but" elements to extend the logic described by "when" and "then". Unfortunately, due to limitations imposed by Jasmines implementation, specifically the Suite and Spec classes, it may not be possible to have these conjunctions apply to both "when" and "then".

The reason for this is simply that in Jasmine, a Suite cannot have "expect"s defined directly within itself. Any "expect"s associated with a suite must be defined in a Spec.

This is a hurdle since aroma merely wraps the "describe" and 'it" calls. Consider the following map of the elements in jasmine.aroma.GWT:

• given => wraps "describe" => yields an instance of Suite
• when => wraps "describe" => yields an instance of Suite
• then, because it is an end-result specification, hence would contain "expect"s:
  • wraps "it" => yields an instance of Spec

Solution

I wish it was possible to have an "expect" in suites as well. There are certain cases where I see value in being able to guarantee that my system has been put into a specified state by having an "expect" in my "given" block. Anyways, life's short so let's make the best of this.

My decision is to ignore the 'when" block completely. So for the moment it will not be possible to do this:

• given
• when
  • and
  • and
• then
  • and

The only option for users would be:

• given some precondition
• when an even occurs
• then I expect this outcome
  • and I expect this outcome too
  • but not this outcome

Okay that should suffice for now.

Context/Specification

The elements provided are:

• concern -- a general reference to the system being described
• context -- a specific use-case or scenario
• spec -- a direct replacement of "test". The specification that describes the expected output.

This may end up being a classic case of YAGNI, however against my better judgement, I've decided to include a grammar module for Context/Specification style BDD. Why? There are two reasons:

1. When I first started experimenting with BDD, Context/Specification examples were very instrumental in helping me understand the manner in which BDD augments TDD. These days I no longer use literal Context/Specification grammar in my projects if I can help it. I find that the "describe/it" and "feature/scenario" grammar capture the ideas of "concern -> context -> spec" rather nicely.
2. The Big Design Upfront Solutions Architect in me just thinks that "someone, somewhere, sometime will need this, so let's build it!"

Actually, I think this is a case that is a literal YAGNI. However, taken in the context of the "spirit of YAGNI" (take a look at Steven Harman's post), I think it's a valid addition to the grammar. Because, hey, it's not "imported" into the global namespace by default.

Executable documentation (XDocs)

I'm not sure how this would work yet. But the general idea is to have grammar for creating specs from a documentation standpoint.

Key requirements

• It should enable a developer to provide examples usages of the api that may be verified by running them as standard Jasmine specs.
• It should be possible for XDocs to be structured as Topic => Example to make the examples easier to find and read.