Skip to main content

Meta Specs

Meta specs are Gherkin specifications that describe how your features will execute and are the automation glue in Gwen. They define all the step definitions and bindings required for automation and attach to features at runtime.

StepDefs#

Composable step definitions#

Step definitions are defined as @StepDef annotated Scenarios with names that match feature steps and bodies that call out to one or many DSL steps to perform operations.

tip

Put all your step definitions in meta to keep your features clean and free of automation concerns.

Consider the following feature step:

Feature Step

File: features/todo.feature

  Given a new todo list

A step definition for executing this could be defined in meta as follows:

StepDef

File: features/todo.meta

  @Context  @StepDef  Scenario: a new todo list      Given my todo list can be located by css ".todo-list"       When I navigate to "${todo.page.url}"       Then the page title should contain "TodoMVC"        And my todo list should be hidden

Calls DSL steps:

Notice how the name of the StepDef matches the feature step. This is how step definitions bind to feature steps in Gwen; by name. Notice also that the body calls out to several DSL steps to perform the desired operations. Composing StepDefs in meta is all you need to do to make your features executable.

StepDefs with parameters#

StepDefs can also be declared to accept parameters using one or more <param-name> placeholders in the declared name as follows:

Feature Step
  Then the list will contain 2 items
StepDef with a parameter
  @Assertion  @StepDef  Scenario: the list will contain <expected-count> items      Given the displayed count can be located by css ".todo-count strong"       Then the displayed count should be "$<expected-count>"

Calls DSL steps:

Here the name of the StepDef matches the feature step when the value 2 (in the feature step) is substituted in place of <expected-count> in the StepDef name. This is how parameters are passed to StepDefs in Gwen; by substitution. The last step in the body extracts the parameter value with $<expected-count>.

Synchronized StepDefs#

In the rare case where you might need to synchronize the execution of your StepDef to a single thread (due to resource contention or a conflict for example), you can do so by tagging it with the @Synchronized annotation. Gwen will then guarantee that only one thread will execute your StepDef at any given time when multiple features or scenarios are executed in parallel by concurrent threads.

Meta Load Strategies#

Associative Strategy#

When associative meta is enabled, a meta and feature file are considered to be associated with each other if the two files are in the same directory and have the same names (excluding their file extensions). The associative strategy will, for every feature:

  1. Auto discover all the meta files in the path to the feature file and only load those that are either:
    • Not associated with any feature (one or many)
    • Associated with the current feature (one or none)
  2. Execute the feature
Coming to Gwen 3

We are planning to enable associative meta by default in the upcomming Gwen 3 release. The current and prior releases use the default strategy by default.

If you have your meta and feature files in a directory structure as follows:

/features โ”œโ”€โ”€ todo.meta โ”œโ”€โ”€ todo.feature โ”œโ”€โ”€ /dir1 โ”‚    โ”œโ”€โ”€ todo1.meta โ”‚    โ”œโ”€โ”€ todo1.feature โ”‚    โ””โ”€โ”€ todo1a.feature โ””โ”€โ”€ /dir2      โ”œโ”€โ”€ todo2.meta      โ”œโ”€โ”€ todo2.feature      โ””โ”€โ”€ /dir3           โ””โ”€โ”€ todo3.feature

When you launch Gwen to execute on the features directory, the associative strategy will:

  • Load the todo.meta and execute the todo.feature
  • Load the todo.meta and todo1.meta and execute the todo1.feature
  • Load the todo.meta and execute the todo1a.feature
  • Load the todo.meta and todo2.meta and execute the todo2.feature
  • Load the todo.meta and execute the todo3.feature

When you launch Gwen to execute on the features/dir1 directory, the associative strategy will:

  • Load the todo.meta and todo1.meta and execute the todo1.feature
  • Load the todo.meta and execute the todo1a.feature

When you launch Gwen to execute the features/dir2/todo2.feature file, the associative strategy will:

  • Load the todo.meta and execute the todo2.feature

External Strategy#

The external strategy enables you to manage common and reusable meta files in a directory that is separate or external to your features directory. How you name your meta files or manage your meta directory structure does not matter. This strategy can be used in conjunction with any other meta load strategy.

To load a single meta file from an external directory, use the -m/--meta CLI option and specify the path to the meta file:

./gwen features -m external-meta/common.meta

To recursively load all meta files in an external directory:

./gwen features -m external-meta

Import Strategy#

The import strategy enables you to selectively import one or more meta files for any given feature file so they will load automatically without you having to specify their locations using the -m/--meta CLI option on every launch. This is useful for cases where you have many reusable meta files and it is not practical to load all of them for every feature file.

caution

When using this strategy, it is important to ensure that the meta files you want to import are not located in or under any directories containing your feature files. This is to prevent them from being auto-loaded by the default or associative strategies. Similarly, they should also not reside in any directories containing meta files loaded by the external strategy if you are using that in conjunction with this strategy.

The import strategy can be used to avoid redundant meta loads and improve performance and scalability in extreme cases where all your common meta combined exceeds or approaches 500 KB in size (that is: when you have LOTS of common meta).

For example, say you have your common meta files in one directory and your feature files in another directory as follows:

/meta โ”œโ”€โ”€ module-1.meta โ”œโ”€โ”€ module-2.meta โ”œโ”€โ”€ module-3.meta โ”‚    .. โ”œโ”€โ”€ module-n.meta โ”œโ”€โ”€ /dir1 โ”‚    โ”œโ”€โ”€ submodule-1.meta โ”‚    โ”œโ”€โ”€ submodule-2.meta โ”‚    โ”œโ”€โ”€ submodule-3.meta โ”‚    โ”‚    .. โ”‚    โ””โ”€โ”€ submodule-n.meta โ”‚/features โ”œโ”€โ”€ spec-1.feature โ”œโ”€โ”€ spec-2.feature โ”œโ”€โ”€ spec-3.feature โ”‚    .. โ””โ”€โ”€ spec-n.feature

To load only one meta file for one feature file using the external meta strategy, you would have to explicitly specify which one using the -m/--meta CLI option as follows:

./gwen -m meta/module-1.meta features/spec-1.feature

Having to remember exactly which meta to load for which features is inconvenient and blindly loading all meta files to execute a feature that only requires one or some of them is wasteful.

With associative meta enabled, you can do away with having to explicitly specify any meta files on CLI calls to Gwen by creating an associative meta file for each feature file and specifying the required meta to import in each.

Use imports in associative meta

Although it's possible to specify imports directly in feature files, we do not recommend you doing so since it would introduce automation concerns into your features. Confining imports to associative meta instead will keep your features clean and untouched. You must enable associative meta to use this approach (note that this setting will be enabled by default in the upcoming Gwen 3 release).

For example, you could import the module-1.meta into a new (or existing) associative meta file for spec-1.feature as follows:

File: features/spec-1.meta

  @Import("meta/module-1.meta")  Feature: Associative spec 1 meta

Note that this associative meta specification contains nothing except one import annotation followed by a feature declaration and name. It contains nothing else since it serves only to import one meta file. It would sit alongside your unchanged feature file on the file system as follows:

/features โ”œโ”€โ”€ spec-1.feature โ”œโ”€โ”€ spec-1.meta โ”‚    ../meta โ”œโ”€โ”€ module-1.meta |   ..

With the import in place, you could then invoke Gwen to execute the feature without having to explicitly specify the meta file in the CLI call:

./gwen features/spec-1.feature

Gwen would then load the associative meta which in turn would load the imported meta before proceeding to execute the feature.

You can add any number of meta imports to a file. The following example imports two meta files for spec 2:

File: features/spec-2.meta

  @Import("meta/module-1.meta")  @Import("meta/module-2.meta")  Feature: Associative spec 2 meta

You can also chain or link imports together. For example, if you wanted module-2.meta to load whenever module-3.meta is loaded, you could import the former into the latter as follows:

File: meta/module-3.meta

  @Import("meta/module-2.meta")  Feature: meta 3

  @StepDef  Scenario: ..      Given ..       When ..       Then ..  ..

Now any import of module-3.meta will also import module-2.meta.

File: features/spec-3.meta

  @Import("meta/module-3.meta")  Feature: Associative spec 3 meta

In this example, the module-2.meta and module-3.meta files will be loaded (in that order) before test-3.feature is executed. Again, this would happen without you having to specify any meta in the CLI call to Gwen.

./gwen features/spec-3.feature

The path to the meta file in all imports can be absolute or relative to the directory where Gwen is invoked. If a recursive (or cyclic) import is detected in any import chain, Gwen will report it by throwing an exception with a message identifying the offending import and the file it was declared in.

Meta files loaded through the import strategy get last precedence and therefore can be overridden by meta files loaded through any other meta load strategy.

Default Strategy#

The default strategy will, for every feature:

  1. Auto discover and unconditionally load all the meta in the path to the feature
  2. Execute the feature

If you have your meta and feature files in a directory structure as follows:

/features โ”œโ”€โ”€ todo.meta โ”œโ”€โ”€ todo.feature โ”œโ”€โ”€ /dir1 โ”‚    โ”œโ”€โ”€ todo1.meta โ”‚    โ”œโ”€โ”€ todo1.feature โ”‚    โ””โ”€โ”€ todo1a.feature โ””โ”€โ”€ /dir2      โ”œโ”€โ”€ todo2.meta      โ”œโ”€โ”€ todo2.feature      โ””โ”€โ”€ /dir3           โ””โ”€โ”€ todo3.feature

When you launch Gwen to execute on the features directory, the default strategy will:

  • Load the todo.meta and execute the todo.feature
  • Load the todo.meta and todo1.meta and execute the todo1.feature
  • Load the todo.meta and todo1.meta and execute the todo1a.feature
  • Load the todo.meta and todo2.meta and execute the todo2.feature
  • Load the todo.meta and todo2.meta and execute the todo3.feature

When you launch Gwen to execute on the features/dir1 directory, the default strategy will:

  • Load the todo.meta and todo1.meta and execute the todo1.feature
  • Load the todo.meta and todo1.meta and execute the todo1a.feature

When you launch Gwen to execute the features/dir2/todo2.feature file, the default strategy will:

  • Load the todo.meta and todo2.meta and execute the todo2.feature