Stories with easyb

BDD principles support the notion of stories quite nicely-- you can think of a story as narrative between a stakeholder and development (almost like a use case). In short, think of a story as a description of a requirement, which has an associated benefit and criteria for validation.

Stories can be made up of scenarios that group specifications. The specifications are essential-- they are essentially steps that are friendly to read. They are:

  • Given (a context)
  • When (something happens)
  • Then (something else happens)

Stories in action

The default convention for stories in easyb is to place each story in a file ending with MyStory.story. So if you have story regarding shipping calculations, for example, you'd have a file named ShippingCalculations.story.

The code below shows a story in easyb in action-- the code has two scenarios which reside in a story file named EmptyStack.story.


import io.easyb.bdd.stack.Stack

scenario "null is pushed onto empty stack", {
  given "an empty stack",{
    stack = new Stack()
  }

  when "null is pushed", {
    pushnull = {
      stack.push(null)
    }
  }

  then "an exception should be thrown", {
    ensureThrows(RuntimeException){
      pushnull()
    }
  }

  and "then the stack should still be empty", {
    stack.empty.shouldBe true
  }
}


scenario "pop is called on empty stack", {
  given "an empty stack",{
    stack = new Stack()
  }

  when "pop is called", {
    popnull = {
      stack.pop()
    }
  }

  then "an exception should be thrown", {
    ensureThrows(RuntimeException){
      popnull()
    }
  }
  
  and "then the stack should still be empty", {
      stack.empty.shouldBe true
    }

}

Does it not convey the intention clearly? Of course it does!! It's so easy too.

Take notice of multiple scenarios in that file, each with their own set of givens,whens and thens all coming together to create a story.

Pending stories and scenarios

easyb makes it easy to create stories with no coding so that you can come back to fill in the implementation later.

scenario "customers should receive discounts", {
 given "a shopping cart with 3 items"
 when "a user checks out"
 then "they should receive a 10% discount"
}

Note how the above scenario has no code-- it's simply just the text of the scenario-- easyb will mark any unimplemented feature as a pending specification.

Printing stories

It wouldn't be fair to only let the developers see this beautiful story now would it? We didn't think so either, so we decided to give you an easy way to print out the story without all that icky implementation code (we're too familiar with that glossy eye look stakeholders get when you show them code).

Story printing is available from command line as a format flag as well as via the easyb ant task. For instance, below is an example of two stories-- one with two scenarios and the other containing three.

This example also shows what you see when a specification isn't filled out and is marked as pending.


33 specifications (including 2 pending) executed successfully


  Story: empty stack

    scenario null is pushed onto empty stack
      given an empty stack
      when null is pushed
      then an exception should be thrown
      then the stack should still be empty

    scenario pop is called on empty stack
      given an empty stack
      when pop is called
      then an exception should be thrown
      then the stack should still be empty

  Story: single value stack

    scenario pop is called on stack with one value
      given an empty stack with one pushed value
      when pop is called
      then that object should be returned
      then the stack should be empty

    scenario stack with one value is not empty
      given an empty stack with one pushed value
      then the stack should not be empty

    scenario peek is called
      given a stack containing an item
      when peek is called
      then it should provide the value of the most recent pushed value
      then the stack should not be empty
      then calling pop should also return the peeked value which is \
        the same as the original pushed value
      then the stack should  be empty
      then an example pending [PENDING]

  etc...

Easy story printing, eh?

Other features of stories

Stories in easyb support a number of other features including the notion of narratives, fixtures and shared behaviors.

easyb supports the notion of narratives, which attempt to set the stage of a story. Narratives use a narrative clause followed by a series of descriptors that can either be written with underscores or not.

For example, the following narrative describes a story regarding currency management:

narrative "regarding currency management", {
 as a "person who uses money"
 i want "to be able to add currencies together"
 so that "that I can become rich over time"
}

If you'd like to re-use a bit of logic throughout a story, you could use easyb's before or before_each keywords to delineate a fixture like so:

before "start selenium", {
 given "selenium is up and running", {
  selenium = new DefaultSelenium("localhost",
    4444, "*firefox", "http://acme.racing.net/greport")
  selenium.start()
 }
}

In the code above, an instance of Selenium is started once for the entire story -- if you'd like to start Selenium for each scenario, then you'd use the before_each keyword.

Ideally, any before or before_each clauses should reside in the beginning of a story; what's more, easyb supports post style fixtures via after and after_each -- these clauses should reside at the bottom of story.

Somewhat similar to fixtures is easyb's notion of shared behaviors -- these are a bit more logical in that rather than creating a before-style clause, you construct a basic scenario and then refer to it later in other scenarios. In essence, this style of re-use is a bit more descriptive.

Shared behaviors use easyb's shared_behavior and it_behaves_as clauses like so:

shared_behavior "shared behaviors", {
  given "a string", {
    var = ""
  }
  
  when "the string is hello world", {
    var = "hello world"
  }
}

scenario "first scenario", {
  it_behaves_as "shared behaviors"
  
  then "the string should start with hello", {
    var.shouldStartWith "hello"
  }
}

scenario "second scenario", {
  it_behaves_as "shared behaviors"
  
  then "the string should end with world", {
    var.shouldEndWith "world"
  }
}

For more examples and information on stories, see easyb's Story examples section.