Configuring tests with @CucumberOptions

Cucumber is very popular framework to define BDD tests. Clear division helps to write them quickly and maintain easily. In additionally, it contains some of useful configurable options, such as output formatting or file sources definition.

This article focuses on configuration options which can be applied to Cucumber tests. The first short part contains definition of @CucumberOptions. After, we describe options supported by this annotation. Every part presents different configuration family. We'll begin with file sources configuration. After, we'll describe some test-oriented features. We'll finish with output configuration options.

What is @CucumberOptions ?

Test options in Cucumber are configured through @CucumberOptions annotation. It can apply only on class definition, in occurrence on test runner. This annotation allows us to configure test exactly in the same way as it should run directly from command line.

Under the hood, @CucumberOptions is handled by cucumber.runtime.RuntimeOptionsFactory. This factory constructs test running command with all specified commands.

Configure file sources

Tests defined for Cucumber must contain files from 3 families: features, glue and runner. The last one is the easiest one because it can be found by Cucumber directly through @RunWith(Cucumber.class) annotation. But 2 others can be configured.

Feature files describe what given test should do. It can be configured in @CucumberOptions with features argument. For example, this entry features= "classpath:bdd" will look for feature files in /test/resources/bdd directory.

The same configuration applies to glue files which can be translated as features code implementation. It's modified with glue argument. For example, this entry glue = "com/waitingforcode/bdd/glue/user" means that Cucumber runner should look for glue files in /test/java/com/waitingforcode/bdd/glue/user directory.

Configure tests

The second customization family concerns tests themselves. The first one, dryRun can be used to define a kind of read-only test. Read-only means here that Cucumber will only check if corresponding glue files are defined. But it won't execute test cases.

More useful than dryRun can be strict argument. If set to true, every not defined test will make feature test fail. Normally the failure should be translated by this PendingException:

cucumber.api.PendingException: TODO: implement me

Thanks to name argument we can specify the pattern to apply on scenarios or features which should be executed. For example, name = "Successful.*" makes that Cucumber will execute only features or scenarios which names beginning with "Successful" word.

Another option helping to configure what should be executed and what shouldn't executed, is tags. For example, tags={"@Executable", "~@Deprecated"} will execute all features or scenarios annotated with @Executable annotation and not execute those annotated with @Deprecated.

Cucumber in other other versions than Java 8 allows to specify an argument called snippets. It can take a value of camelcase or underscore from cucumber.api.SnippetType enum. It helps to specify which convention is used to define steps in Java glue code. It applies to Java 6 and 7 Cucumber versions because they define Given/When/Then steps with methods annotated with @Given, @When and @Then annotation.

Configure output

And the funniest part concerns output. Normally tests are printed in console but they can only be saved to HTML, JSON or Junit files. It can be configured through plugin argument. For example, plugin={"html:reports/html", "json:reports/cucumber.json", "junit:reports/cucumber.xml", "pretty"} will use pretty plugin to console output. In additionally, it will generate report files in HTML, JSON and JUnit (XML) formats.

Outputs contain some information about executed tests, such as: duration, result (passed or not), name, matching Given/When/Then glue code, skipped and failing tests. Maybe the most important plugin is pretty because it prints executed tests in console which can be useful when separated tests are executed in IDE. Without pretty, generated output will look such as:

3 Scenarios (3 passed)
9 Steps (9 passed)

This article shows configuration available for Cucumber BDD tests. We can see that we can easily configure files used by Cucumber (glue, feature), but also tests and output format.

If you liked it, you should read: