Examples Philosophy

JBehave was developed as behaviour-driven and example-driven. As such, examples are an integral part of the build, since they act as automated acceptance criteria verifying the correctness of the JBehave's behaviour. The examples are run as integration tests, complementing the behaviour verified by unit tests.

Examples could also be called Behaviours, as they represent integration-level behaviours.

Example Modules

Examples are split into several modules, of which a few are standalone, while others (the trader examples) have minimal interdependency to avoid duplication and repetitions, which would increase maintainance overhead.

  • gameoflife: verifies multi-line scenarios behaviours
  • noughtsandcrosses: verifies GUI behaviours
  • spring-security: verifies Spring-based security behaviours
  • trader: contains stories verifying the behaviour of multiple functionalities of JBehave
  • trader-annotations: extends trader example verifying configuration via annotations
  • trader-urls: extends trader example verifying running stories accessible via URLs, including remote resources
  • trader-maps: extends trader example verifying generation of story maps
  • trader-stepdocs: extends trader example verifying generation of stepdocs
  • trader-i18n: extends trader example verifying the writing of stories in different locales
  • trader-groovy: extends trader example verifying using Groovy for writing steps
  • trader-guice: extends trader example verifying configuration using Guice for dependency injection
  • trader-pico: extends trader example verifying configuration using PicoContainer for dependency injection
  • trader-spring: extends trader example verifying configuration using Spring for dependency injection
  • trader-weld: extends trader example verifying configuration using Weld for dependency injection
All the trader example modules re-use the same stories and steps classes of the trader example, but focus on different complementary aspects, e.g. annotation-based configuration, localisation, scripting steps, or dependency injection. The trader-example module is declared as a normal Maven dependency for all extension trader modules and must be installed in your local repository before these can be run.

src/main or src/test?

A recurring question that is often asked is where one should place the behaviour code, in src/main or src/test. The answer is largely a matter of convention and depends on the build system you are using.

In Maven, src/test tends to be used for unit testing and anything found in the test directory is not packaged in the artifact being built. Also, src/test conventionally tests only the code contained in that module. This is why it is recommendable for integration testing to have a separate module and to place the behaviour code in src/main. This allows the integration testing module to verify the behaviour of multiple production modules and it also allows the modularisation of the integration testing itself.

That said, JBehave allows the running of stories from either src/main or src/test (the behaviour is controlled by the scope=[main|test] property of the Ant/Maven configuration). So it's down the the user preference where to place the behaviour code.

The examples modules contain a mix of stories/steps classes as well as other code used in the running of the examples. This code is functional to the testing and should be thought of as "test code". It constitutes a test harness that verifies the "production code" that is found in the JBehave core modules.