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.
- To facilitate the migration due to the terminology changes in
the textual scenarios/stories and in the Ant/Maven files, one can use
the script provided in the migrating-from-2.x
example.
- 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?
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 quickest
and most instructive way to get up to speed with the changes outlined
above.