Meta Matchers

One of the principal use cases for defining meta info in our stories is to be able to filter the stories based on the meta info provided.

A meta filter is represented as a string and supports multiple meta matcher languages based on the prefix used:

Default Meta Matcher

The default meta matcher has a very simple language structure that mirrors that of the meta properties, expressed as a sequence of name-value patterns:

   default meta matcher :== ([+|-] [name] [value pattern])+

where [+|-] indicates if the filter should include or exclude the meta property and the [value pattern] can be either an exact match of the property value (including empty value) or use the * matching notation.

The following are all valid meta matchers:

   +author Mauro
   +theme filtering
   +author * +theme filtering
   +author * +theme filtering -skip
   -skip

A few examples of meta matchers and properties that matched or not:

Meta MatcherMeta PropertyMatched
+theme smoke testing -skip@theme smoke testingtrue
+theme smoke testing -skip@skipfalse
+theme smoke testing@theme smoke testingtrue
+theme smoke testing@theme testingfalse
-skip@theme testingtrue
-skip@skipfalse
+theme smoke testing -theme UI@theme smoke testingtrue
+theme smoke testing -theme UI@theme UIfalse

Groovy Meta Matcher

The Groovy meta matcher allows the logic of the matching to be expressed in Groovy using the values of the meta property names and values:

The following are all valid meta matchers (excluding the "groovy:" prefix):

   author == 'Mauro'
   !skip
   theme == 'filtering' && theme != 'smoke testing' 
   theme ==~ /.*[testing|regression].*/
As Groovy is an optional dependency, users wanting to use the Groovy Meta Matcher need to add it to the runtime classpath. If using Maven, you need to define Groovy as a Plugin dependency, c.f. Maven goals.

Filtering on Story and Scenario Elements

In addition to the meta info that is defined by the user, both at story and scenario level, JBehave also exposes the top-level elements of stories and scenarios, which can be filtered on. These include:

The meta properties are exposed by default with no prefix, but can be configured to have one via the configuration StoryControls:

configuration.storyControls().useStoryMetaPrefix("story_").useScenarioMetaPrefix("scenario_");

Configuring Meta Filters

As usual, JBehave allow multiple equivalent ways of configuration. One can specify the meta filters directly via the Embedder, either programmatically or via the annotation:

Embedder embedder = ... // define as required
embedder.useMetaFilters(asList("+author Mauro", "+theme filtering", "-skip"));
@RunWith(AnnotatedEmbedderRunner.class)
@UsingEmbedder(metaFilters = {"+author Mauro", "+theme filtering", "-skip"})
public class AnnotatedTraderEmbedder extends InjectableEmbedder {
}

The meta filters can also be specified via Ant tasks or Maven goals, using the "metaFilters" attribute or configuration element.

Note that because of its additive sequential nature, the meta filters will all be joined together when running the stories. Have different meta filters comes into play when doing story mapping.