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:
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
A recurrent use case is to report the steps that are configured in the Embeddables used to run the stories.