## Configuration

JBehave was designed to be highly embeddable in its configuration and execution. At its heart, we have the Embeddable interface, which can specify the Embedder to use for the running of the stories.

The Embedder separates the concerns of the configuration of the story execution from the matching of the textual story steps to Java methods:

- Configuration instances are responsible for the configuration of story execution.
- CandidateSteps instances are used to find the Java methods that match the textual steps in the stories.

The Embedder needs both the Configuration and the list of CandidateSteps. Although it has sensible defaults for the configuration (such as MostUsefulConfiguration) we need, for any significant story running, to configure at least one steps instance.

JBehave allows multiple paths to the configuration of the Embedder, so that users can choose the one that best fits their need.

### Using AnnotatedEmbedder

JBehave supports the ability to specify configuration elements and steps instance via annotations. An example of annotated configuration of the Embedded via annotations is:

Here we are actually using a JUnit Runner, AnnotatedEmbedderRunner, to bootstrap the configuration process. The AnnotatedEmbedderRunner is a very thin wrapper around the AnnotationBuilder, building the Embedder and injecting in the test class, which extends InjectableEmbedder.

Note that JBehave follows a configuration-by-convention approach, by which a default value of the configuration element is always provided but can be overridden, when needed.

### Using AnnotationBuilder

If we wanted to use the AnnotationBuilder directly, the above example would become:

The AnnotationBuilder requires that configuration elements and the steps instances provide a default constructor. This limitation is overcome by using dependency injection containers. Note that the use of dependency injection annotations overrides the one specified by the @Configure and @UsingSteps.

### Using ConfigurableEmbedder

A ConfigurableEmbedder is an abstract implementation of Embeddable, which allows subclasses to specify the Configuration and CandidateSteps directly. A notable subclass of ConfigurableEmbedder is JUnitStory, which allows each subclass to be run as a separate individual story.

Even if each JUnitStory Java class can be configured independently, it is good practice to collect the configuration that applies to all stories in an abstract (i.e. not runnable) base class:

Once we have a configured instance of ConfigurableEmbedder, all we need to do is to extend it providing the name of the executable Story class that maps to the textual story file. For example, to map to trader_is_alerted_of_status.story using the resolver defined above:

    public class TraderIsAlertedOfStatus extends TraderStory {

    }

To run multiple stories, specified as story paths, one can use another subclass of ConfigurableEmbdder, JUnitStories:

Note that in this second example, we are using story paths as URLs, and correspondingly we configure the use of LoadFromURL.

### Configurable Elements

All configurable elements of Configuration come with a default behaviour, configured in the MostUsefulConfiguration:

- Keywords: defaults to LocalizedKeywords.
- FailureStrategy: Allows to define the strategy for error handling. The default value is RethrowingFailureStrategy.
- StepCollector: Represents the strategy for the collection of executable steps from a given story matching a list of candidate steps. The default implementation is MarkUnmatchedStepsAsPending.
- StoryControls: Controls the story execution workflow.
- StoryParser: Parses stories contained in a textual story file. The default implementation is RegexStoryParser.
- StepPatternParser: defaults to RegexPrefixCapturingPatternParser.
- StepMonitor: defaults to SilentStepMonitor, useful to either debug the step matching or to describe the steps being performed to some output.
- The StoryReporterBuilder: facade for building instances of StoryReporter. The ViewGenerator allows to generate view of reports run. The default implementation is FreemarkerViewGenerator.
- ParameterConverters: facade for collecting user-defined implementations of ParameterConverter.

### Controlling the Embedder using Maven or Ant

All the elements of EmbedderControls are also configurable via Maven goals or Ant tasks.

It is important to note that JBehave adopts an out-in approach to configuration. Any inner-layer configuration, such as specified in the code, will be overridden by the outer-layer configuration, such as specified by the command-line tools like Maven or Ant.