JGiven User Guide

JGiven consists of a couple of modules.

If you are using JUnit, you must depend on the jgiven-junit artifact. Note that jgiven-junit does not directly depend on JUnit, thus you also must have a dependency to JUnit itself. JGiven requires at least JUnit 4.9, while the recommended version is 4.13.2.

If you are using TestNG, you must depend on the jgiven-testng artifact. Note that jgiven-testng does not directly depend on TestNG, thus you also must have a dependency to TestNG itself.

Note that you should compile your test classes with all debugging information (javac -g). Otherwise JGiven cannot obtain the parameter names of step methods and will generate names of the form argX instead.

First of all you create a JUnit test class that inherits from com.tngtech.jgiven.junit.ScenarioTest:

The ScenarioTest requires 3 type parameters. Each of these type parameters represents a stage of the Given-When-Then notation. Note that there is also the SimpleScenarioTest class that only requires a single type parameter. In that case, all your scenario steps are defined in a single class. For scenarios where you only want to differentiate between steps that modify state (setup in given(), changes in when()) and steps that assert state (then()) you can use the DualScenarioTest which takes two parameters: a combined GivenWhen stage and a single Then stage.

To make your class compile, create the following three classes:

JGiven does not require you to inherit from the Stage class, however, the Stage class already provides some useful methods like and() and self().

Now you can write your first scenario

The scenario is then executed like any other JUnit test, for example, by using your IDE or Maven:

Sometimes it is not possible to derive your test class from the ScenarioTest class, because you might already have a common base class that you cannot easily modify. In that case you can directly use the JUnit Rules of JGiven. Instead of providing your stage classes as type parameters, you inject the stages into the test class with the @ScenarioStage annotation.

Note that your stage classes have to inherit from the Stage class in order to have the given(), when(), and then() methods. You can now also define convenient methods in your test class to get cleaner scenarios if you like:

By default JGiven outputs plain text reports to the console when executed. To disable plain text reports set the following Java system property:

By default JGiven will generate JSON reports into the jgiven-reports/json directory. JGiven tries to autodetect when it is executed by the Maven surefire plugin and in that case generates the reports into target/jgiven-reports/json. To disable JSON report generation set the following Java system property:

There is a dry run option, which just generates a report without actually executing the code. This might be helpful to generate a test report quickly without having to wait for the tests to be executed.

To generate an HTML report you have to run the JGiven report generator with the html format option. The reporter is part of the jgiven-html5-report module. The report generator can be executed on the command line as follows (assuming that the jgiven-core and the jgiven-html5-report JAR and all required dependencies are on the Java CLASSPATH)

To see the HTML report in action you can have a look at the HTML report of JGiven itself

JGiven will optionally load a configuration properties file, defaulting to: jgiven.properties. The path to the configuration can be customized with the system property:

The encoding for the file is assumed to be UTF-8, but can be customized with the system property:

The following can be defined in the properties file:

Configuration defined via Java system properties will take precedence over values in the configuration file.

A stage class contains multiple step methods that can be called in a scenario and that will appear in the report. Every non-private, non-final, non-static method of a stage class can be used as a step method. There are no further requirements. In particular, no annotations are needed. Step methods should return the this reference so that chaining of calls is possible. In addition, a step method should be written in snake_case so that JGiven knows the correct casing of each word of the step.

The following code shows a valid step method of the WhenCook stage:

JGiven removes the underlines so the step will appear as the cook mangles everything to a dough in the report.

Sometimes it is necessary to override the default way of the step reporting. For example, if you want to use special characters that are not allowed in Java methods names, such as (, +, or %. You can then use the @As annotation to specify what JGiven should put into the report.

For example, if you define the following step method:

The step will appear as 10 % are added in the report, when invoked with 10.

If you need full control over the step text you can inject the CurrentStep interface into the stage by using the @ScenarioState annotation. You can then use the setName method to change the steps text. Note, however, that this does not work well when used within parametrized scenarios, because JGiven will not be able anymore to generate data tables. In general, the preferred way to change the step name should be the @As annotation.

Steps can be completely hidden from the report by using the @Hidden annotation. This is sometimes useful if you need a technical method call within a scenario, which should not appear in the report.

For example:

Note that it is useful to write hidden methods in CamelCase to make it immediately visible in the scenario that these methods will not appear in the report.

Steps can get an extended description with the @ExtendedDescription annotation. You can use this to give additional information about the step to the reader of the report. In the HTML report this information is shown in a tooltip.

Example:

If the predefined introductionary words in the Stage class are not enough for you and you want to define additional ones you can use the @IntroWord annotation on a step method.

Example:

Note that you can combine @IntroWord with the @As annotation. To define a , as an introductionary word, for example, you can define:

Filler words can be used to build a common and reusable vocabulary for your tests. This enables you to write beautifully fluent tests whilst at the same time keeping your stage methods clear and concise.

The @FillerWord annotation can also be added to stage methods where you want to maintain the continuation of sentences in reports.

For example, given the following filler words:

You can write test stages such as:

This would generate the following report:

Filler words can also be joined to other words in sentences. Using joinToPreviousWord and joinToNextWord you can create new words without trailing and leading whitespace respectively. A typical use case for using these attributes is adding punctuation to your tests.

For example, given the following filler words:

You could write test stages such as:

This would generate the following report:

Please note that the annotations @IntroWord and @FillerWord are mutually exclusive. @IntroWord takes precedence over @FillerWord; where there are occurrences of methods having both annotations @FillerWord will be ignored.

Very often it is necessary to share state between steps. As long as the steps are implemented in the same Stage class you can just use the fields of the Stage class. But what can you do if your steps are defined in different Stage classes? In this case you just define the same field in both Stage classes. Once in the Stage class that provides the value of the field and once in the Stage class that needs the value of the field. Both fields also have to be annotated with the special annotation @ScenarioState to tell JGiven that this field will be used for state sharing between stages. The values of these fields are shared between all stages that have the same field. For example, to be able to access the value of the ingredients field of the GivenIngredients stage in the WhenCook stage one has to annotate that field accordingly:

Instead of the @ScenarioState annotation one can also use @ExpectedScenarioState and @ProvidedScenarioState to indicate whether the state is expected by the stage or provided by the stage. These function in exactly the same way as @ScenarioState but are more descriptive about what the code is doing.

In many cases three stages are typically enough to write a scenario. However, sometimes more than three are required. JGiven provides two mechanism for that: stage injection and dynamic adding of stages.

In practice, it often makes sense to have a hierarchy of stage classes. Your top stage class can implement common steps that you require very often, while subclasses implement more specialized steps.

One problem with subclassing stage classes is to keep the fluent interface intact. Let’s have an example:

Now assume that we create a subclass of GivenCommonSteps:

If you now want to use the GivenSpecialSteps stage, you will get problems when you want to chain multiple step methods:

This code will not compile, because my_common_step() returns GivenCommonSteps and not GivenSpecialSteps.

Luckily this problem can be fixed with generic types. First you have to change the GivenCommonSteps class as follows:

That is, you give GivenCommonSteps a type parameter SELF that can be specialized by subclasses. This type is also used as return type for my_common_step(). Instead of returning this you return self(), which is implemented in the Stage class.

Now your subclass must be change as well:

The life-cycle of a scenario is as follows.

@BeforeScenario and @AfterScenario methods are often used to set up and tear down some resource. If you want to reuse such a resource in another stage, you would have to copy these methods into that stage. To avoid that, JGiven offers a concept similar to JUnit rules. The idea is to have a separate class that only contains the before and after methods. This class can then be reused in multiple stages.

A scenario rule class can be any class that provides the methods before() and after(). This is compatible with JUnit’s ExternalResource class, which means that you can use classes like TemporaryFolder from JUnit directly in JGiven.

To place parameters within a sentence instead of the end of the sentence you can use the $ character.

In the generated report $ is replaced with the corresponding formatted parameter. So the generated report will look as follows:

If there are more parameters than $ characters, the remaining parameters are added to the end of the sentence.

If a $ should not be treated as a placeholder for a parameter, but printed verbatim, you can write $$, which will appear as a single $ in the report.

The @As annotation can be used to override the shown sentence. To reference arguments you can use the three different interoperable options which apply to every description in JGiven. For more examples look up JGiven StepFormatter Tests

Use $ to access the arguments in natural order.

Or enumerate them $1, $2, …​ to have a direct reference:

Or reference them via the argument names:

The call to given().$_eggs_and_$_rice_bowls(5, 2) will be shown as:

An extended description is shown if you hover above the step as tooltip, but hidden by default.

The call to given().$_eggs_and_$_rice_bowls(5, 2) will still be shown as:

The extended description can also be set by using the CurrentStep interface, which can be injected into a state with the @ScenarioState annotation.

Sometimes the toString() representation of a parameter object does not fit well into the report. In these cases you have three possibilities:

The default formatting of a parameter can be overridden by using the @Format annotation. It takes as a parameter a class that implements the ArgumentFormatter interface. In addition, an optional array of arguments can be given to configure the customer formatter. For example, the built-in BooleanFormatter can be used to format boolean values:

In this case, true values will be formatted as on and false as off.

As using the @Format annotation is often cumbersome, especially if the same formatter is used in multiple places, one can define and use custom formatting annotations instead.

An example is the pre-defined @Quoted annotation, which surrounds parameters with quotation marks. The annotation is defined as follows:

As you can see, the annotation itself is annotated with the @Format annotation as described above, which will be applied to all parameters that are annotated with @Quoted.

When step parameter is a POJO, it may sometimes be useful to get a string representation using part or all of the fields composing this POJO.

The @POJOFormat fulfills this need while providing a way to format fields values following customizable field formats.

Given the following POJO :

Then you can define a step method as follows:

where @NamedFormat associates a format (classic @Format or any custom format annotation) to a field by its name.

Finally, the step method can be called with an argument :

Then the report will look as follows:

For additional options, see the JavaDoc documentation of the @POJOFormat annotation

Sometimes information can be represented very concisely by using tables. JGiven supports this with the @Table annotation for step parameters. Such parameters are then formatted as tables in the report. The types of such parameters can be:

JGiven supports several different ways to parameterize a JUnit test:

We use the JUnit Dataprovider in the following.

JUnit Dataprovider provides a JUnit test runner that enables the execution of paramterized test methods. It is similar to the way parameterized tests work in TestNG.

If your test has multiple cases, you can use the @CaseAs to provide additional information to the description for each case.

The resulting report will then look as follows:

Tags can have descriptions. These descriptions appear in the report on the corresponding page for the tag. For example:

It is possible to override the name of a tag by using the name attribute of the IsTag annotation. This allows you to have a different name for the tag than the actual type of the annotation. For example, if you want to have a tag Feature: Coffee you can define the CoffeeFeature annotation as follows:

Sometimes you do not want to always create a new annotation for each tag. Let’s say you organize your work in stories and for each story you want to know which scenarios have been written for that story. Instead of having a separate annotation for each story you can define a Story annotation with a value() method:

Annotations with different values are treated as different tags in JGiven. So using the above annotation you can now mark scenarios to belong to certain stories:

In the report the tag will now be ACME-123 instead of Story.

If you want that the type is prepended to the value in the report you can set the prependType attribute of the IsTag annotation to true. In this case the tag will be shown as Story-ACME-123. Note that this feature works in combination with the name attribute.

Annotations with the same type but different values are grouped in the report. E.g. multiple @Story tags with different values will be grouped under Story.

If you want to group several annotations with different types under a common name. You can combine the name attribute with the value attribute as follows:

The tag will appear as Tag in the report and all annotations with name Feature will be grouped together.

If your number of tags grow you typically want to organize your tags somehow. This is easily possible in JGiven by forming tag hierarchies. A tag hierarchy is defined by just annotating a tag annotation with other tags. Each of these tags will then become a parent tag in the hierarchy. For example, if you want to organize your features into ‘Core Features’ and ‘Secondary Features’ you can do so by first defining two tags @CoreFeature and @SecondaryFeature for each of these categories as you would define a normal JGiven tag. If you now want to define a feature tag as a Core Feature you just annotated that tag accordingly:

There are several ways to create an attachment by using static factory methods of the Attachment class. For example, you can create textual attachments from a given String by using the fromText method.

To add an attachment to a step you have to first inject the CurrentStep class into your stage class by using @ExpectedScenarioState.

Now you can use currentStep inside step methods to add attachments using the addAttachment method. The method takes as argument an instance of Attachment.

If you are using Selenium WebDriver and want to add screenshots to a JGiven step you can do so as follows:

For a full example, see the Html5AppStage class that is used by the JGiven tests.

Let’s assume you want to verify that in the step method doing_some_action a certain exception is thrown and you write the following scenario using JUnit:

This scenario has two drawbacks: first it will not work and second the generated report will not make clear that actually an exception is expected. It will not work, because the JUnit mechanism to check for an expected exception actually comes too early. As already explained above, JGiven will throw the exception itself, after the scenario has finished. As JGiven is actually implemented as a JUnit rule, throwing this exception will be after JUnit has checked for an expected exception. This technical issue can be fixed by using the ExpectedException rule of JUnit:

In this case, the actual verification of the exception is done after JGiven has thrown the exception and thus the ExpectedException rule will get the exception.

The above example has still the big disadvantage that it will not be visible in the report that an exception is actually expected. More helpful would be the following scenario:

Note, that this is scenario is still very technical and you should consider replacing the word ‘exception’ with a more domain specific term.

In order to realize the above scenario you have to explicitly catch the exception in the doing_some_action step and store it into a scenario state field.

In the When-Stage you then just have to check whether the field is set:

Spock support is provided by the jgiven-spock dependency.

JGiven support for Spock is provided by extending ScenarioSpec<Given, When, Then> and JGiven is enabled.

You find a complete example project on GitHub: https://github.com/TNG/JGiven/tree/master/example-projects/spock

Spring support is provided by the jgiven-spring-junit4 and the jgiven-spring-junit5 dependencies, depending on which JUnit version you are using. JUnit 5 is only supported with version 5 of Spring.

In order to enable the JGiven Spring integration you have to tell Spring about the existence of JGiven.

In order to treat JGiven stages as Spring beans, e.g. if you want to inject other Spring beans into your stages, you have to annotate the stage class with the @JGivenStage annotation.

You find a complete example project, a SpringBoot webapp tested with JGiven, on GitHub: https://github.com/TNG/JGiven/tree/master/example-projects/spring-boot

It is possible to treat Selenium page objects directly as JGiven stages. This sometimes makes sense for simple cases, but from a code design perspective, it is better to separate these different concerns into multiple classes. The page object should be solely responsible for the low-level interaction with a HTML page. The stage class contains the high-level steps of the scenario and handles the state of the scenario.

You find a complete example project on GitHub: https://github.com/TNG/JGiven/tree/master/example-projects/selenium

If you want to execute your tests on an Android device or emulator, for example when you want to use the Espresso test framework, then you need some additional setup.

You find a complete example project on GitHub: https://github.com/TNG/JGiven/tree/master/example-projects/android

JUnit 5 support is provided by the jgiven-junit5 dependency.

JGiven support for JUnit 5 is provided by the JGivenExtension JUnit 5 extension. You just annotate your JUnit 5 test class with @ExtendWith( JGivenExtension.class ) and JGiven is enabled.

If you just use the extension directly, you have to inject your stage classes by using the @ScenarioStage annotation.

Alternatively, you can use one of the test base classes ScenarioTest, SimpleScenarioTest or DualScenarioTest that provide additional convenience methods and allows you to specify stage classes by using type parameters:

Please note that JGiven is built around each scenario, i.e. test method, having its own test instance. Therefore, we cannot support JUnit’s per-class test instance lifecycle. An exception will be thrown if any such attempt is made.

You find a complete example project on GitHub: https://github.com/TNG/JGiven/tree/master/example-projects/junit5