Cross Reference

The CrossReference is a special report Format that build a cross reference of stories being executed during the run. It provides both JSON and XML representations, detailing both the stories and scenarios run, as well as the step matches.

These representations can then be used by any app that can navigate its contents and render it interactively.

A typical xref.json file is:

{"xref": {
  "whenMade": 1298245533227,
  "createdBy": "JBehave",
  "meta": [
  ],
  "stories": [
    {
      "description": "",
      "narrative": "",
      "name": "unmatched_search_term.story",
      "path": "org/jbehave/examples/trader/stories/unmatched_search_term.story",
      "html": "org.jbehave.examples.trader.stories.unmatched_search_term.html",
      "meta": "",
      "scenarios": "Scenario:Search term does match examples table header\u000aG
iven that I am on Google's Homepage\u000aWhen I enter the search term ridiculou
sSearchTerm and proceed\u000aThen I should see ridiculous things\u000a\u000a\u0
00aScenario:Search term does not match examples table header and step is marked 
as pending\u000aGiven that I am on Google's Homepage\u000aWhen I enter the searc
h term ridiculousSearchTerm and proceed\u000aThen I should see ridiculous thin
gs\u000a\u000a\u000a",
      "passed": true,
      "pending": false
    }
  ],
  "stepMatches": [
    {
      "type": "GIVEN",
      "annotatedPattern": "that I am on Google's Homepage",
      "resolvedPattern": "that\\s+I\\s+am\\s+on\\s+Google's\\s+Homepage",
      "usages": [
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does match examples table header",
          "step": "Given that I am on Google's Homepage"
        },
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does not match examples table header and step
 is marked as pending",
          "step": "Given that I am on Google's Homepage"
        }
      ]
    },
    {
      "type": "WHEN",
      "annotatedPattern": "I enter the search term ridiculousSearchTerm and pr
oceed",
      "resolvedPattern": "I\\s+enter\\s+the\\s+search\\s+term\\s+ridiculousSear
chTerm\\s+and\\s+proceed",
      "usages": [
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does not match examples table header and step
 is marked as pending",
          "step": "When I enter the search term ridiculousSearchTerm and proce
ed"
        },
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does match examples table header",
          "step": "When I enter the search term ridiculousSearchTerm and proce
ed"
        }
      ]
    },
    {
      "type": "THEN",
      "annotatedPattern": "I should see ridiculous things",
      "resolvedPattern": "I\\s+should\\s+see\\s+ridiculous\\s+things",
      "usages": [
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does not match examples table header and step
 is marked as pending",
          "step": "Then I should see ridiculous things"
        },
        {
          "story": "org/jbehave/examples/trader/stories/unmatched_search_term.st
ory",
          "scenario": "Search term does match examples table header",
          "step": "Then I should see ridiculous things"
        }
      ]
    }
  ]
}}

Configuration

The CrossReference instance needs to configured in the StoryReporterBuilder:

public class TraderStories extends JUnitStories {
    
    @Override
    public Configuration configuration() {
        CrossReference xref = new CrossReference();
        return new MostUsefulConfiguration()
            .useStoryReporterBuilder(new StoryReporterBuilder()
                .withCrossReference(xref)) 
            .useStepMonitor(xref.getStepMonitor());                               
    }
}

If the CrossReference is configured, the JSON and XML representations are generated automatically in the JBehave report view directory (target/jbehave/view by default) by the JUnit-based ConfigurableEmbedder, i.e. JUnitStory and JUnitStories. In other case, you may generate them on demand via the Embedder method generateCrossReference().

Optionally, CrossReference can be configured to update file output after each story and to output to JSON or XML only (instead of both). Moreover, the user can choose to exclude stories when there are no executed scenarios

Note that in the above code fragment we are only focusing on the configuration of the CrossReference. In particular, you may be chaining more than one step monitor together in the useStepMonitor(..) line. Also, there will be typically other methods to implement in JUnitStories for finding stories and other configuration elements to specify.

Examples

Examples of configuration of CrossReference can be found in core example and the JBehave Tutorial.