Using Instancio with JUnit 5¶
This article is an introduction to using Instancio extension for JUnit 5. Here we will cover
InstancioExtensionfor reproducing failed tests
- injecting settings into test classes
- running tests with custom seed values
- generating data for
- You will need to include
- It is assumed you already have JUnit 5 on the classpath.
Why use the Instancio JUnit extension¶
By default, Instancio tests your code against randomly generated data. Unless you configured it otherwise, each time a test is executed, it is run against a different data set. This brings up the question of how to reproduce a failed test? One of the benefits of the extension is that it reports the seed value that was used to generate the data. Knowing the seed value allows us to reproduce the original data that caused the test to fail.
To get started, we will need to declare the extension in our test class. This is similar to using other test extensions, such as
MockitoExtension. In fact, they can be used together if both are needed. We will use the following sample test case verifying the conversion of a
If this test fails, Instancio will report the failure as follows:
Using the reported seed value
34567, we can annotate the test method to reproduce the data:
|Reproducing the data|
Now each time the test is run, it will produce the same data, allowing us to fix the cause of the failure. Once the cause is resolved, the
@Seed annotation can be removed so that new data will be generated on each subsequent test run. How this works is described in more detail in the user guide, but to summarise, Instancio supplies each test method with a seed value. If the
@Seed annotation is present, Instancio will use its value; if not, it will generate a random seed.
Injecting Settings into tests¶
Another feature provided by the extension is its support for injecting custom settings. Instancio settings are encapsulated by the
Settings class. This allows overriding various parameters like generated number ranges; array, map, and collection sizes; whether generated values can be null, and so on. For example, by default, Instancio generates
- non-null values
- non-empty collections
- positive numbers
@WithSettings annotation we can override default behaviour as follows:
With the above settings in place, Instancio might generate
null strings, empty collections, and negative integers. The settings will apply to test methods in this test class only. If you need to override settings globally, this can be done by placing instancio.properties file at the root of the classpath.
Instancio Arguments Source¶
Last but not least, you can use the
@InstancioSource annotation with
@ParameterizedTest methods. JUnit 5 provides
@ParameterizedTest support via the
Once you have the dependency on the classpath, you can declare a test method as follows:
|Parameterized test with a single argument|
Instancio will provide a populated instance of the class specified in the annotation. You can specify any number of classes in the annotation. Just remember to declare a method argument for each class in the annotation:
|Parameterized test with multiple arguments|
There are a couple of important limitations to using @InstancioSource to be aware of.
First, it cannot provide instances of generic types. For example, there is no way to specify a List
Second, you cannot customise the object as you would with the builder API. In other words, there is no way to specify something like this:
However, in situations where these limitations do not apply, it offers a convenient way of providing data to a test method. From simple values such as Strings and numbers to complex data types.