The reasons for JBehave 3
While JBehave 1 was more of a thought experiment, helping to
spread and understand new concepts around BDD. JBehave 2 has been a
complete rewrite based on new technologies (e.g. Java 5 annotations). By
contrast, JBehave 3 is an evolution of JBehave 2, 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 would have
broken backward compatibility.
Migration path from JBehave 2
From the textual stories point of view, these are almost
completely backward compatible. The only exception being the GivenScenarios
keyword, whose default value 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 Writing Stories in
your language on how to configure and override default keywords to suit
your needs.
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. E.g. JUnitScenario is now JUnitStory.
- The root package has also changed from org.jbehave.scenario
to org.jbehave.core.
- The Ant tasks and Maven goals have also been renamed to
reflect the terminology change. To facilitate the migration, one can
use the script provided in the migrating-from-2.x
example.
- Configuration has been consolidated into a single builder
object. and moved to org.jbehave.core.configuration package.
- JUnitStory allows the overriding of the default
MostUsefulConfiguration only via the useConfiguration method,
and the specification of Steps only via the addSteps
method.
- The textual story lookup paradigm has shifted from a RunnableStory
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.
- Terminology concerning report rendering has been changed to
stories view generation.
- The concerns of running stories and view generation has been
centralised in an embeddable component - Embedder - which has
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 managed via EmbedderControls.
Next?
JBehave development has been
example-driven and the examples illustrate all the features, migrated
from 2.x or new in 3.x. Be sure check out the running examples, as it's the best and
most instructive way to get up to speed with the changes outlined above.