Finding Steps

The matching of textual steps to Java methods, each representing an executable step, is a key concept in creating a Domain-Specific Language (DSL). Once a DSL has been defined, we need a way to display the "grammar" of the DSL to enable to story writer to exercise that grammar in writing the scenarios.

JBehave centers around the matching of textual steps with Java methods contained in steps instances. Each annotated method in the steps instances corresponds to a StepCandidate, which is responsible for the matching and for the creation of an executable step.

When the number of CandidateSteps instances grows, it can become more difficult to find a matching step candidates. In this case, it is useful to make use of the StepFinder to report matching candidates. JBehave provides the concept of Stepdoc, as a documentation facade around a single StepCandidate, i.e. a single annotated method in the steps instance. This documentation includes:

  • the associated annotation in the method of the steps instance class
  • the method in the steps instance class
  • the pattern to match the step candidate that is configured in the annotation
  • the alias patterns for the step candidate (optional)

To find and report matchings Stepdocs via the Embedder:

    Embedder embedder = new Embedder();
    embedder.useConfiguration(...); // specify your configuration
    embedder.useCandidateSteps(...); // create your CandidateSteps using the InjectableStepsFactory from your steps instances 
    embedder.reportMatchingStepocs("Given a step that I'm looking to match")

The result of the search would by default be output to console, e.g.:

Step 'When traders are subset to ".*y" by name' is matched by annotated methods:
When traders are subset to "%regex" by name
When traders are filtered by "%regex"
org.jbehave.examples.trader.TraderSteps.subsetTradersByName(java.lang.String)
from steps instances:
org.jbehave.examples.trader.TraderSteps
org.jbehave.examples.trader.BeforeAfterSteps

And if a match is not found:

Step 'Given a step that I'm looking to match' is not matched by any method
from steps instances:
org.jbehave.examples.trader.TraderSteps
org.jbehave.examples.trader.BeforeAfterSteps

To change the output from console, you can configure the StepdocReporter to output to any print stream:

   embedder.configuration().useStepdocReporter(new PrintStreamStepReporter(...)); // defaults to System.out

Reporting Stepdocs As Embeddables

A recurrent use case is to report the steps that are configured in the Embeddables used to run the stories.

Using Maven Goal