Getting Started

Write a textual story

Create a textual story file with a name that expresses the behaviour to verify, e.g. i_can_toggle_a_cell.story and define steps in it:

      Given a 5 by 5 game
      When I toggle the cell at (2, 3)
      Then the grid should look like
      .....
      .....
      .....
      ..X..
      .....
      When I toggle the cell at (2, 4)
      Then the grid should look like
      .....
      .....
      .....
      ..X..
      ..X..
      When I toggle the cell at (2, 3)
      Then the grid should look like
      .....
      .....
      .....
      .....
      ..X..

Steps must start with one of the keywords highlighted (see Concepts for more details) and are not limited to a single line. Also, unless otherwise indicated, a story has at least one implicit scenario, each of which is a collection of steps.

Map scenario steps to Java methods

Define your Steps class, e.g. call it GridSteps, which will contain the Java methods that are mapped to the textual steps. The methods need to annotated with one of the JBehave annotations and the annotated value should contain a regex pattern that matches the textual step:

      public class GridSteps {

        private Game game;
        private StringRenderer renderer;

        @Given("a $width by $height game")
        public void theGameIsRunning(int width, int height) {
            game = new Game(width, height);
            renderer = new StringRenderer();
            game.setObserver(renderer);
        }

        @When("I toggle the cell at ($column, $row)")
        public void iToggleTheCellAt(int column, int row) {
            game.toggleCellAt(column, row);
        }

        @Then("the grid should look like $grid")
        public void theGridShouldLookLike(String grid) {
            Ensure.ensureThat(renderer.asString(), CoreMatchers.equalTo(grid));
        }

      }

Map story to Java class

Define your RunnableStory class with a name that can be mapped to the textual story filename, e.g. ICanToggleACell.java:

      public class ICanToggleACell extends JUnitStory {

        public ICanToggleACell() {
            addSteps(new StepsFactory().createCandidateSteps(new GridSteps())); // varargs, can have lots of steps
        }
      }

The story is now configured to use the GridSteps that hold the step mappings.

Run story in IDE

Open your favourite IDE, the ICanToggleACell.java class will allow itself to run as a JUnit test. Be sure to check that you have all the required dependencies in your classpath.

Next?

JBehave development has been example-driven and it is very instructive to go through one or more working examples in the source repository, which illustrate features. Be sure to read about running examples. The examples also show command-line ways of running stories.