From 4.x to 5.0

JBehave 5.x is an evolution of 4.x.

From the textual stories point of view, these are completely backward compatible.

From the Java point of view, the most significant changes are:

• Changed visibility of method JUnitStories#storyPaths() from protected to public. Subclasses overriding the method should change visibility accordingly.
• Changed method names for filter exclusion from 'notAllowed' to 'excluded'.
• Rename Status NOT_ALLOWED to EXCLUDED.
• Changed default scenario type in @BeforeScenario/@AfterScenario annotations.
• Deprecated use of date format String parameter in OutcomesTable. Use map parameter instead.
• Removed deprecated org.jbehave.core.reporters.StoryReporterBuilder.Format. Use org.jbehave.core.reporters.Format instead.
• Removed deprecated SameThreadExecutors.
• Removed deprecated methods in step collectors.
• Removed deprecated methods in StoryReporter, StepMonitor and EmbedderMonitor.
• JUnitStory now inherits from JUnitStories. ConfigurableEmbedder now inherits from InjectableEmbedder.
• Ant tasks no longer supported. Use JUnit support instead.
• Hudson/Jenkins plugins no longer supported.
• CrossReference and story navigator no longer supported
• StoryRunner no longer supported. Use PerformableTree instead.
• Adding CandidateSteps via an Embedder no longer supported. Use InjectableStepsFactory instead.
• Embedder controls storyTimeoutInSecs and storyTimeoutInSecsByPath no longer supported. Use storyTimeouts instead.
• Stop reporting BeforeStories/AfterStories steps as stories. New hooks are introduced: org.jbehave.core.reporters.StoryReporter#beforeStoriesSteps and org.jbehave.core.reporters.StoryReporter#afterStoriesSteps
• Fix typo in StoryReporter method: lifecyle -> lifecycle
• Invoke StoryReporter#beforeStep(Step) hook before all steps (including comment, pending, ignorable), previously the hook was invoked only for parameterized steps
• CurrencyConverter, PatternConverter, FileConverter and VerbatimConverter classes were removed, their functionality is covered by new instances of FunctionalParameterConverter class
• Always trigger StoryReporter.beforeStep(Step) hook and report all outcomes (previously only failures were reported, successful outcome was silent) for methods annotated with @BeforeStories, @AfterStories, @BeforeStory, @AfterStory, @BeforeScenario, @AfterScenario
• Replace StoryReporter hooks:
• StoryReporter#beforeStep(String) with StoryReporter#beforeStep(Step)
• StoryReporter#beforeStorySteps(Stage) with StoryReporter#beforeStorySteps(Stage, Lifecycle.ExecutionType)
• StoryReporter#afterStorySteps(Stage) with StoryReporter#afterStorySteps(Stage, Lifecycle.ExecutionType)
• StoryReporter#beforeScenarioSteps(Stage) with StoryReporter#beforeScenarioSteps(Stage, Lifecycle.ExecutionType)
• StoryReporter#afterScenarioSteps(Stage) with StoryReporter#afterScenarioSteps(Stage, Lifecycle.ExecutionType)

From 3.x to 4.0

JBehave 4.x is an evolution of 3.x.

From the textual stories point of view, these are completely backward compatible.

From the Java point of view, the most significant change is the execution mechanism of the stories, with the StoryRunner replaced by the PerformableTree. The result of execution of the performable tree should be serialisable and consumable by any reporting/UI layer independent of the StoryReporters. Correspondingly, the CrossReference class has also changed. As customising the StoryRunner and the CrossReference is likely to be a very niche use case, most users will not notice any significant difference. The rest of the configuration is backward compatible.

From 3.0 to 3.1

The Story Maps view has been added to the Story Reports view. As such, the default output directory has been renamed from jbehave-reports to jbehave. The main index view in target/jbehave/view/index.html now links to both the maps and reports views (view/maps.html and view/reports.html, respectively). Currently, it assumes that both views are generated and there is no check on whether these views exist or not. An upcoming enhancement will determine which views have actually been generated and enabled the links accordingly.

Operationally, users should change the target view directory of the jbehave view resources to target/jbehave/view. Maven users can use the new unpack-view-resources goal which will derive the view directory from the configured Embedder.

It is also recommended to use the latest released version 3.1.1 of the jbehave-site-resources.zip, which uses a SyntaxHighlighter BDD brush to decorate all plain-text output.

From 2.x to 3.0

JBehave 3.x is an evolution of 2.x, based on the experience using it in commercial projects. With the benefit of this experience, we feel that the overall design stood well the wear and tear, but there were areas which called for improvements that required to break backward compatibility.

From the textual stories point of view, these are almost completely backward compatible. The only exceptions being:

• GivenScenarios keyword has changed to GivenStories. Full backward compatibility can be nonetheless ensures by configuring the keywords bundle entry to GivenScenarios until the migration has been completed. See stories in your language on how to configure and override default keywords to suit your needs.
• Regex-based story parser now enforces that step keywords must be at the start of a new line. This allow keywords to be found in the step text and in the examples table. The convention of having keywords at start of line is already universally adopted and but may encounter the occasional failure due spurious spaces before the keywords.

From the Java point of view, significant changes have occurred, but only in the configuration of the running of the stories. The Steps classes, which is where most users' efforts will have gone into can be used without change in JBehave 3.

On the configuration side, the main changes are:

• Terminology has changed throughout to refer to Story in place of Scenario where this refers to the textual or Java representation reflecting the fact that scenarios in JBehave 2 were already stories in all but name. Terminology concerning report rendering has been changed to view generation.
• The Ant tasks and Maven goals have also been renamed to reflect the terminology change.
• The root package has changed from org.jbehave.scenario to org.jbehave.core to avoid classpath clashes.
• JUnitStory does not extend JUnit's TestCase any more. To ensure the class is recognised as a JUnit test, you must make the source code of jbehave-core available to your IDE. Alternatively, check the FAQ for other workarounds.
• The concerns of running stories and view generation has been centralised in an embeddable component - Embedder - around which there are thin wrappers for running in multiple environments, e.g. JUnit, Ant/Maven, Spring etc. Using the Embedder, the user can choose to run multiple textual story using a single Java entry point. The embedder behaviours can be controlled via EmbedderControls.
• JUnitStory is now a JUnit-specific extension of ConfigurableEmbedder and allows the overriding of the default MostUsefulConfiguration only via the useConfiguration method, and the specification of Steps only via the addSteps method. Equivalently, the user can override the methods configuration() and candidateSteps().
• Configuration has been consolidated into a single builder and moved to org.jbehave.core.configuration package. Configuration and CandidateSteps are now fully specifiable via annotations, with or without dependency injection.
• The textual story lookup paradigm has shifted from an Embeddable class to a story path, which can be resolved from the class via the StoryPathResolver, and its implementations UnderscoredCamelCaseResolver and CasePreservingResolver. As such, the StoryLoader implementations only define the model story from a story path. The FilePrintStreamFactory correspondingly now handles only story paths.

Next?