User Guide

Introduction¶

Overview¶

Instancio is a Java library for generating test objects. Its main goal is to reduce manual data setup in unit tests. Its API was designed to be as non-intrusive and as concise as possible, while providing enough flexibility to customise generated objects. Instancio requires no changes to production code, and it can be used out-of-the-box with zero configuration.

Project Goals¶

There are several existing libraries for generating realistic test data, such as addresses, first and last names, and so on. While Instancio also supports this use case, this is not its goal. The idea behind the project is that most unit tests do not care what the actual values are. They just require the presence of a value. Therefore, the main goal of Instancio is simply to generate fully populated objects with random data, including arrays, collections, nested collections, generic types, and so on. And it aims to do so with as little code as possible to keep the tests concise.

Another goal of Instancio is to make the tests more dynamic. Since each test run is against random values, the tests become alive. They cover a wider range of inputs, which might help uncover bugs that may have gone unnoticed with static data. In many cases, the random nature of the data also removes the need for parameterising test methods.

Finally, Instancio aims to provide reproducible data. It uses a consistent seed value for each object graph it generates. Therefore, if a test fails against a given set of inputs, Instancio supports re-generating the same data set in order to reproduce the failed test.

Instancio Basics¶

Creating Objects¶

The Instancio class is the entry point to the API. It provides the following shorthand methods for creating objects. These can be used when defaults suffice and generated values do not need to be customised.

1
2
3

Instancio.create(Class<T> type)
Instancio.create(TypeTokenSupplier<T> supplier)
Instancio.create(Model<T> model)

The following builder methods allow chaining additional method calls in order to customise generated values, ignore certain fields, provide custom settings, and so on.

1
2
3

Instancio.of(Class<T> type).create()
Instancio.of(TypeTokenSupplier<T> supplier).create()
Instancio.of(Model<T> model).create()

The three arguments accepted by these methods can be used for different purposes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// Create by specifying the class
Person person = Instancio.create(Person.class);

// Using type tokens
Pair<String, Long> pair = Instancio.create(new TypeToken<Pair<String, Long>>() {});

Map<Integer, List<String>> map = Instancio.create(new TypeToken<Map<Integer, List<String>>>() {});

// Create from a model
Model<Person> personModel = Instancio.of(Person.class)
    .ignore(field(Person::getAge))
    .toModel();

Person personWithoutAgeAndAddress = Instancio.of(personModel)
    .ignore(field(Person::getAddress))
    .create();

It should be noted that generic types can also be created using Instancio.of(Class) and specifying the type parameters as arguments to the withTypeParameters() method:

1
2
3

Pair<String, Long> pair = Instancio.of(Pair.class)
    .withTypeParameters(String.class, Long.class)
    .create();

However, this approach has a couple of drawbacks: it does not support nested generics, and its usage will produce an "unchecked assignment" warning.

Creating collections¶

Collections can be created using one of the following methods. These methods create a collection of random size, between 2 and 6 elements, inclusive:

1
2
3

Instancio.createList(Class<T> elementType)
Instancio.createSet(Class<T> elementType)
Instancio.createMap(Class<K> keyType, Class<V> valueType)

In addition, there is a builder API for creating a collection of a specified size. The builder API also supports customising properties of collection elements.

1
2
3

Instancio.ofList(Class<T> elementType).create()
Instancio.ofSet(Class<T> elementType).create()
Instancio.ofMap(Class<K> keyType, Class<V> valueType).create()

If the element is a generic type, the following methods can be used instead:

1
2
3

Instancio.ofList(TypeTokenSupplier<T> elementType).create()
Instancio.ofSet(TypeTokenSupplier<T> elementType).create()
Instancio.ofMap(TypeTokenSupplier<K> keyType, TypeTokenSupplier<V> valueType).create()

In addition, ofList() and ofSet() can be used to create collections from models:

1
2

Instancio.ofList(Model<T> elementModel).create()
Instancio.ofSet(Model<T> elementModel).create()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

List<Person> list = Instancio.createList(Person.class);

List<Person> list = Instancio.ofList(Person.class).size(10).create();

List<Pair<String, Integer>> list = Instancio.ofList(new TypeToken<Pair<String, Integer>>() {}).create();

Map<UUID, Address> map = Instancio.ofMap(UUID.class, Address.class).size(3)
    .set(field(Address::getCity), "Vancouver")
    .create();

// Create from a model
Model<Person> personModel = Instancio.of(Person.class)
    .ignore(field(Person:getAge))
    .toModel();

Set<Person> set = Instancio.ofSet(personModel).size(5).create()

Specifying the collection size is optional. If no size is specified, a collection of random size (between 2 and 6 inclusive) will be generated.

Creating record and sealed Classes¶

Instancio version 1.5.0 introduced support for creating

• record classes when run on Java 16+, and
• sealed classes when run on Java 17+.

This uses the same API as described above for creating regular classes.

Creating a Stream of Objects¶

Instancio also provides methods for creating a Stream of objects. The stream() methods return an infinite stream of distinct fully-populated instances. Similarly to the create() methods, these have a shorthand form if no customisations are needed:

1
2

Instancio.stream(Class<T> type)
Instancio.stream(TypeTokenSupplier<T> supplier)

as well as the builder API that allows customising generated values:

1
2

Instancio.of(Class<T> type).stream()
Instancio.of(TypeTokenSupplier<T> supplier).stream()

The following are a couple of examples of using streams. Note the calls to limit(), which are required to avoid an infinite loop.

1
2
3
4
5
6
7
8
9

List<Person> personList = Instancio.stream(Person.class)
    .limit(3)
    .collect(Collectors.toList());

Map<UUID, Person> personMap = Instancio.of(new TypeToken<Person>() {})
    .ignore(all(field(Person::getAge), field(Person::getAddress)))
    .stream()
    .limit(3)
    .collect(Collectors.toMap(Person::getUuid, Function.identity()));

Creating Simple Values¶

Instancio provides the Gen class for generating simple value types such as strings, numbers, dates, and so on. This class can generate:

• a single value using get() method
• a list of values using the list(int) method

URL url = Gen.net().url().get();

String randomChoice = Gen.oneOf("foo", "bar", "baz").get();

List<LocalDate> pastDates = Gen.temporal().localDate().past().list(5);

List<String> uuids = Gen.text().uuid().upperCase().withoutDashes().list(5);

Selectors¶

Selectors are used to target fields and classes, for example in order to customise generated values. Instancio supports different types of selectors, all of which implement the TargetSelector interface. These types are:

• regular selectors
• method reference selector
• predicate selectors
• convenience selectors
• setter selectors

All of the above can be created using static methods from the Select class.

Regular selectors¶

Regular selectors are for precise matching: they can only match a single field or a single type.

1
2
3

Select.field(String fieldName)
Select.field(Class<?> declaringClass, String fieldName)
Select.all(Class<?> type)

Select.field(Person.class, "name") // Person.name
Select.all(Set.class)

Select.field() is matched based on the exact field name. If a field with the specified name does not exist, an error will be thrown. Select.all() is matched using Class equality, therefore matching does not include subtypes.

Method reference selector¶

This selector uses method references to match fields.

1

Select.field(GetMethodSelector<T, R> methodReference)

Select.field(Person::getName)

Internally, method reference is converted to a regular field selector, equivalent to Select.field(Class<?> declaringClass, String fieldName). This is done by mapping the method name to the corresponding field name. The mapping logic supports the following naming conventions:

• Java beans - where getters are prefixed with get and, in case of booleans, is.
• Java record - where method names match field names exactly.

For example, all the following combinations of field and method names are supported:

For methods that follow other naming conventions, or situations where no method is available, regular field selectors can be used instead.

Kotlin method reference selector¶

Since Instancio does not include Kotlin dependencies, the method reference selector described above is only supported for Java classes. If you use Kotlin, a similar selector can be implemented as a simple utility class shown below. This sample assumes that the property has a non-null backing javaField:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

class KSelect {
    companion object {
        fun <T, V> field(property: KProperty1<T, V>): TargetSelector {
            val field = property.javaField!!
            return Select.field(field.declaringClass, field.name)
        }
    }
}

// Usage: KSelect.field(SamplePojo::value)

Predicate selectors¶

Predicate selectors allow for greater flexibility in matching fields and classes. These use a plural naming convention: fields() and types().

1
2

Select.fields(Predicate<Field> fieldPredicate)
Select.types(Predicate<Class<?>> classPredicate)

Select.fields(field -> field.getName().contains("date"))
Select.types(klass -> Collection.class.isAssignableFrom(klass))

Unlike regular selectors, these can match multiple fields or types. For example, they can be used to match all fields declared by a class, or all classes within a package. They can also be used to match a certain type, including its subtypes.

Convenience selectors¶

Convenience selectors provide syntactic sugar built on top of regular and predicate selectors.

1
2
3
4
5
6

Select.all(GroupableSelector... selectors)
Select.allStrings()
Select.allInts()
Select.fields()
Select.types()
Select.root()

• Select.all(GroupableSelector... selectors)

This method can be used for grouping multiple selectors, allowing for more concise code as shown below.

all(field(Address::getCity),
    field(Address.class, "postalCode"),
    all(Phone.class))

• Select.fields() and Select.types()

These selectors provide a builder API for constructing predicate selectors. For example, the following selector matches Long fields annotated with @Id

Select.fields().ofType(Long.class).annotated(Id.class)

which is equivalent to using the following predicate:

Select.fields(f -> f.getType() == Long.class && f.getDeclaredAnnotation(Id.class) != null)

• Select.root()

This method selects the root object. The following snippet creates nested lists, where the outer list and inner lists have different sizes:

1
2
3
4

List<List<String>> result = Instancio.of(new TypeToken<List<List<String>>>() {})
    .generate(root(), gen -> gen.collection().size(outerListSize))
    .generate(all(List.class), gen -> gen.collection().size(innerListSize))
    .create();

In this case, all(List.class) matches all lists except the outer list, because root() selector has higher precedence than other selectors.

Setter selectors¶

Setter selectors allow targeting setter methods. These selectors can only be used if Method Assignment is enabled.

1
2
3

Select.setter(String methodName)
Select.setter(Class<?> declaringClass, String methodName)
Select.setter(Class<?> declaringClass, String methodName, Class<?> parameterType)

Select.setter(Person.class, "setName")
Select.setter(Pojo.class, "setValue", String.class) // Pojo.setValue(String)
Select.setter(Pojo.class, "setValue", Long.class)   // Pojo.setValue(Long)

In addition, a setter can be selected using the method reference selector:

1

Select.setter(SetMethodSelector<T, U> methodReference)

Select.setter(Person::setName)

Selector Precedence¶

Selector precedence rules apply when multiple selectors match a field or class:

• Regular selectors have higher precedence than predicate selectors.
• Field selectors have higher precedence than type selectors.

Consider the following example:

1
2
3
4

Address address = Instancio.of(Address.class)
    .set(allStrings(), "foo")
    .set(field("city"), "bar")
    .create();

This will produce an address object with all strings set to "foo". However, since field selectors have higher precedence, the city will be set to "bar".

In the following example, the city will also be set to "bar" because the predicate fields() selector has lower precedence than the regular field() selector:

1
2
3
4

Address address = Instancio.of(Address.class)
    .set(fields().named("city"), "foo")
    .set(field("city"), "bar")
    .create();

Multiple matching selectors¶

When more than one selector matches a given target, then the last selector wins. This rule applies to both, regular and predicate selectors.

In the case of regular selectors, if the two are identical, the last selector simply replaces the first (internally, regular selectors are stored as Map keys).

1
2
3
4

Address address = Instancio.of(Address.class)
    .set(field(Address.class, "city"), "foo")
    .set(field(Address.class, "city"), "bar") // wins!
    .create();

Predicate selectors, on the other hand, are stored as a List and evaluated sequentially starting from the last entry.

1
2
3
4
5

Address address = Instancio.of(Address.class)
    .set(fields().named("city"), "foo")
    .set(fields().named("city"), "bar") // wins!
    .lenient()
    .create();

In this particular example, the first entry remains unused, which would cause an unused selector error. Therefore lenient() mode must be enabled to prevent the error (see Selector Strictness).

Selector Scopes¶

Selectors provide the within(Scope... scopes) method for fine-tuning the targets selectors should be applied to. Instancio supports two types of scope:

• Class-level scope: narrows down a selector to the specified class.
• Field-level scope: narrows down a selector to the specified field of the target class.
• Predicate scope: narrows down a selector using a field or class predicate.

To illustrate how scopes work we will assume the following structure for the Person class (getters and setters omitted).

class Person {
    String name;
    Address homeAddress;
    Address workAddress;
}

class Address {
    String street;
    String city;
    List<Phone> phoneNumbers;
}

class Phone {
    String areaCode;
    String number;
}

Note that the Person class has two Address fields. Selecting field(Address::getCity) would target both addresses, homeAddress and workAddress. Without scopes, it would not be possible to set the two cities to different values. Using scopes solves this problem:

1
2
3
4
5
6
7

Scope homeAddress = field(Person::getHomeAddress).toScope();
Scope workAddress = field(Person::getWorkAddress).toScope();

Person person = Instancio.of(Person.class)
    .set(field(Address::getCity).within(homeAddress), "foo")
    .set(field(Address::getCity).within(workAddress), "bar")
    .create();

For more complex class structures, multiple scopes can be specified using within(Scope...) method. When specifying multiple scopes, the order is important: from outermost to innermost scope. Additional examples are provided below.

Creating scopes¶

Scopes can be created using:

• Select.scope() static methods in the Select class
• Selector.toScope() method provided by regular selectors
• PredicateSelector.toScope() method provided by predicate selectors

The first approach requires specifying the target class and, for field-level scopes, the name of the field:

1
2
3
4

Select.scope(Class<?> targetClass)
Select.scope(Class<?> targetClass, String field)
Select.scope(GetMethodSelector<T, R> methodReference)
Select.scope(PredicateSelector selector)

Select.scope(Phone.class);
Select.scope(Person.class, "homeAddress");
Select.scope(Person::getHomeAddress);
Select.scope(type -> type == Address.class);

The second approach is to create scopes from selectors using the toScope() method.

1
2
3
4
5

Select.all(Class<T> targetClass).toScope()
Select.field(Class<T> targetClass, String field).toScope()
Select.field(GetMethodSelector<T, R> methodReference).toScope()
Select.fields(Predicate<Field> predicate).toScope()
Select.types(Predicate<Class> predicate).toScope()

Select.all(Phone.class).toScope();
Select.field(Person.class, "homeAddress").toScope();
Select.field(Person::getHomeAddress).toScope();
Select.fields(field -> field.getName().equals("id")).toScope();
Select.types(type -> type == Address.class).toScope();

Examples of using scopes¶

To start off, without using scopes we can set all strings to the same value. For example, the following snippet will set each string field of each class to "foo".

1
2
3

Person person = Instancio.of(Person.class)
    .set(allStrings(), "foo")
    .create();

Using within() we can narrow down the scope of the allStrings() selector as shown in the following examples. For brevity, Instancio.of(Person.class) is omitted.

allStrings().within(scope(Address.class))

allStrings().within(scope(List.class))

allStrings().within(scope(Person.class, "homeAddress"))

Using within() also allows specifying multiple scopes. Scopes must be specified top-down, starting from the outermost to the innermost.

allStrings().within(scope(Person::getWorkAddress), scope(Phone.class))

The Person.workAddress object contains a list of phones, therefore Person.workAddress is the outermost scope and is specified first. Phone class is the innermost scope and is specified last.

The final examples illustrate the creation of scope objects from regular selectors. The following examples are equivalent to each other:

allStrings().within(scope(Person.class, "homeAddress"))

allStrings().within(scope(Person::getHomeAddress))

allStrings().within(field(Person.class, "homeAddress").toScope())

allStrings().within(field(Person::getHomeAddress).toScope())

allStrings().within(scope(Person.class))

allStrings().within(all(Person.class).toScope())

Selector Depth¶

Regular and predicate selectors can also be narrowed down by specifying target's depth. Both selector types allow specifying depth as an integer value:

1
2
3
4
5
6

Select.all(Class<T> targetClass).atDepth(int depth)
Select.field(Class<T> targetClass, String field).atDepth(int depth)
Select.field(GetMethodSelector<T, R> methodReference).atDepth(int depth)

Select.fields(Predicate<Field> fieldPredicate).atDepth(int depth)
Select.types(Predicate<Class> typePredicate).atDepth(int depth)

In addition, predicate selectors also support specifying depth as a predicate:

1
2

Select.fields(Predicate<Field> fieldPredicate).atDepth(Predicate<Integer> depthPredicate)
Select.types(Predicate<Class> typePredicate).atDepth(Predicate<Integer> depthPredicate)

We will use the following class structure for the examples:

Depth       Class
----------------------
  0         Root
            /  \
  1        A    B
              / | \
  2          A  A  C
                  / \
  3              A   D
                      \
  4                    A

where the classes are defined as:

record Root(A a, B b) {}
record A(String value) {}
record B(A a1, A a2, C c) {}
record C(A a, D d) {}
record D(A a) {}

In the first few examples, we will target class A at different levels:

Root root = Instancio.of(Root.class)
    .set(all(A.class).atDepth(1), new A("Hello!"))
    .create();

=> Root[a=A[value="Hello!"], b=B[a1=A[value="BRHD"], a2=A[value="AVBMJRP"], c=C[a=A[value="PZK"], d=D[a=A[value="AQVXCT"]]]]]

Similar to the above, but omitting Instancio.of() for brevity:

all(A.class).atDepth(2)

=> Root[a=A[value="FNPI"], b=B[a1=A[value="Hello!"], a2=A[value="Hello!"], c=C[a=A[value="IDLOM"], d=D[a=A[value="QXPW"]]]]]

types().of(A.class).atDepth(depth -> depth > 2)

=> Root[a=A[value="MWAASZU"], b=B[a1=A[value="ODSRTG"], a2=A[value="TDG"], c=C[a=A[value="hello!"], d=D[a=A[value="hello!"]]]]]

all(A.class).within(scope(B.class))

=> Root[a=A[value="GNDUXU"], b=B[a1=A[value="hello!"], a2=A[value="hello!"], c=C[a=A[value="hello!"], d=D[a=A[value="hello!"]]]]]

The next example is targeting allStrings(), therefore the value is being set to "Hello!" instead of new A("Hello!"). This snippet targets all strings that are reachable from class A, but only if class A is at depth 3 or greater.

1
2
3
4
5

Root root = Instancio.of(Root.class)
    .set(allStrings().within(all(A.class).atDepth(3).toScope()), "Hello!")
    .create();

=> Root[a=A[value="SERWVQV"], b=B[a1=A[value="PTF"], a2=A[value="CHZP"], c=C[a=A[value="hello!"], d=D[a=A[value="hello!"]]]]]

The final example is targeting the field A.value but only within the a1 field of class B:

field(A::value).within(field(B::a1).toScope())

=> Root[a=A[value="DBOS"], b=B[a1=A[value="hello!"], a2=A[value="KFBWJL"], c=C[a=A[value="VLTNXF"], d=D[a=A[value="CDV"]]]]]

Selector Strictness¶

Strict Mode¶

Instancio supports two modes: strict and lenient, an idea inspired by Mockito's highly useful strict stubbing feature.

In strict mode, unused selectors will trigger an error. In lenient mode, unused selectors are simply ignored. By default, Instancio runs in strict mode. This is done for the following reasons:

• to eliminate errors in data setup
• to simplify fixing tests after refactoring
• to keep test code clean and maintainable

Eliminate errors in data setup¶

An unused selector could indicate an error in the data setup. As an example, consider populating the following POJO:

1
2
3
4
5
6
7

class SamplePojo {
    SortedSet<String> values;
}

SamplePojo pojo = Instancio.of(SamplePojo.class)
    .generate(all(Set.class), gen -> gen.collection().size(10))
    .create();

At first glance, we might expect a Set of size 10 to be generated. However, since the field is declared as a SortedSet and the class selector targets Set, the generate() method will not be applied.

Since all(Set.class) did not match any target, Instancio produces an error:

org.instancio.exception.UnusedSelectorException:

 -> Unused selectors in generate(), set(), or supply():
 1: all(Set)

Without being aware of this detail, it is easy to make this kind of error and face unexpected results even with a simple class like the above. It gets trickier when generating more complex classes. Strict mode helps reduce this type of error.

Simplify fixing tests after refactoring¶

Refactoring always causes tests to break to some degree. As classes and fields get reorganised and renamed, tests need to be updated to reflect the changes. Assuming there are existing tests utilising Instancio, running tests in strict mode will quickly highlight any problems in data setup caused by refactoring.

Keep test code clean and maintainable¶

Last but not least, it is important to keep tests clean and maintainable. Test code should be treated with as much care as production code. Keeping the tests clean and concise makes them easier to maintain.

Lenient Mode¶

While strict mode is highly recommended, Instancio provides a few options to disable checking for unused selectors. The following are the possible options, with the least recommended last:

1. At selector level, by marking an individual selector as lenient
2. At object level, by treating all selectors as lenient
3. Via Settings
4. Globally via instancio.properties

The first option is shown below, where the selector is marked as lenient():

Person person = Instancio.of(Person.class)
    .set(fields().named("someFieldThatMayNotExist").lenient(), "some value")
    .create();

The second option is to enable lenient mode for all selectors:

Person person = Instancio.of(Person.class)
    .set(fields().named("someFieldThatMayNotExist"), "some value")
    .set(fields().named("anotherFieldThatMayNotExist"), "another value")
    .lenient()
    .create();

Alternatively, lenient mode can be enabled using Settings:

Settings settings = Settings.create()
    .set(Keys.MODE, Mode.LENIENT);

Person person = Instancio.of(Person.class)
    .withSettings(settings)
    // snip... same selectors as above
    .create();

Lastly, lenient mode can also be enabled globally using instancio.properties. This is the least recommended option.

mode=LENIENT

Customising Objects¶

Properties of an object created by Instancio can be customised using

• generate()
• set()
• supply()

methods defined in the InstancioApi class.

Using generate()¶

The generate() method provides access to built-in generators for core types from the JDK, such as strings, numeric types, dates, arrays, collections, and so on. It allows modifying generation parameters for these types in order to fine-tune the data. The usage is shown in the following example, where the gen parameter (of type Generators) exposes the available generators to simplify their discovery using IDE auto-completion.

1
2
3
4
5

Person person = Instancio.of(Person.class)
    .generate(field("age"), gen -> gen.ints().range(18, 65))
    .generate(field("pets"), gen -> gen.array().length(3))
    .generate(field(Phone.class, "number"), gen -> gen.text().pattern("#d#d#d-#d#d-#d#d"))
    .create();

Below is another example of customising a Person. For instance, if the Person class has a field List<Phone>, by default Instancio would use ArrayList as the implementation. Using the collection generator, this can be overridden by specifying the type explicitly:

1
2
3
4

Person person = Instancio.of(Person.class)
    .generate(field("phoneNumbers"), gen -> gen.collection().minSize(3).subtype(LinkedList.class))
    .generate(field(Phone.class, "countryCode"), gen -> gen.oneOf("+33", "+39", "+44", "+49"))
    .create();

Each generator provides methods applicable to the type it generates, for example:

• gen.string().minLength(3).allowEmpty().nullable()
• gen.map().size(5).nullableValues().subtype(TreeMap.class)
• gen.temporal().localDate().future()
• gen.longs().min(Long.MIN_VALUE)
• gen.enumOf(MyEnum.class).excluding(MyEnum.FOO, MyEnum.BAR)

In addition, most generators can also map values to a different type. For example, the following returns generated values as Strings:

1
2
3
4
5
6
7
8
9

class Foo {
    String dateString;
    String enumString;
}

Instancio.of(Foo.class)
    .generate(field("dateString"), gen -> gen.temporal().localDate().past().asString())
    .generate(field("enumString"), gen -> gen.enumOf(MyEnum.class).as(e -> e.name().toUpperCase()))
    .create();

Using set()¶

The set() method can be used for setting a static value to selected targets, just like a regular setter method:

1
2
3
4

Person person = Instancio.of(Person.class)
    .set(field(Phone::getCountryCode), "+1")
    .set(all(LocalDateTime.class), LocalDateTime.now())
    .create();

However, unlike a regular set method that can only be invoked on a single object, the above will set countryCode to "+1" on all generated instances of Phone class. Assuming the Person class contains a List<Phone>, they will all have the specified country code. Similarly, all LocalDateTime values will be set to the same instance of now().

Using supply()¶

The supply() method has two variants:

1
2

supply(TargetSelector selector, Supplier<V> supplier)
supply(TargetSelector selector, Generator<V> generator)

The first accepts a java.util.function.Supplier and is for supplying non-random values. The second accepts an Instancio Generator (a functional interface) and can be used for supplying random values.

Using supply() to provide non-random values¶

The following is another example of setting all LocalDateTime instances to now().

1
2
3

Person person = Instancio.of(Person.class)
    .supply(all(LocalDateTime.class), () -> LocalDateTime.now())
    .create();

Unlike the earlier example using set(), this will assign a new instance for each LocalDateTime:

1
2

set(all(LocalDateTime.class), LocalDateTime.now())        // reuse the same instance for all dates
supply(all(LocalDatime.class), () -> LocalDateTime.now()) // create a new instance for each date

Using supply() to provide random values¶

The second variant of the supply() method can be used for supplying random values and objects. This method takes a Generator as an argument, which is a functional interface with the following signature:

1
2
3
4
5

import org.instancio.Random;

interface Generator<T> {
    T generate(Random random);
}

Using the provided Random instance ensures that generated objects are reproducible. Since Generator is a functional interface it can be specified as a lambda expression:

1
2
3
4
5
6

Person person = Instancio.of(Person.class)
        .supply(all(Phone.class), random -> Phone.builder()
                .countryCode(random.oneOf("+1", "+52"))
                .number(random.digits(7))
                .build())
        .create();

Generators can be used for generating simple value types as well as building complex objects. They are described in more detail in the Custom Generators section.

Using assign()¶

The assignment API allows customising an object by passing in one or more Assignment objects as a vararg:

InstancioApi<T> assign(Assignment... assignments);

Assignments can be created using static methods provided by the Assign class. It provides three entry-point methods for creating an assignment:

1
2
3

Assign.given(TargetSelector origin)
Assign.given(TargetSelector origin, TargetSelector destination)
Assign.valueOf(TargetSelector target)

Each Assignment may have:

• an origin selector - the source of the assignment; must match exactly one value
• destination selector(s) whose target(s) will be assigned a given value
• Generator for generating the value to assign
• Predicate that must be satisfied by the origin for the assignment to be applied
• Function for mapping the value before assigning to destination targets

The three types of expressions can be used for different use-cases described in the following sections.

Assign.valueOf(target)¶

This builder provides two options:

• Assign value directly to the target
• Assign value of the target to another selector

The first option is to assign a value directly to the target selector using set(), supply(), or generate() methods as shown in the following example:

Assignment[] assignments = {
    Assign.valueOf(Person::getName).set("Bob"),
    Assign.valueOf(Person::getAge).generate(gen->gen.ints().range(1,100))
};

Person person = Instancio.of(Person.class)
    .assign(assignments)
    .create();

The second option is to set the value of the target to another selector. For example, the following snippet assigns the value of Person.firstName to Person.preferredName:

1
2
3
4
5

Assignment preferredName = Assign.valueOf(Person::getFirstName).to(Person::getPreferredName);

Person person = Instancio.of(Person.class)
    .assign(preferredName)
    .create();

This method supports an optional predicate to specify when the assignment should be applied. In the following example, the preferred name is set to the first name only if the first name starts with "A". Otherwise, the preferred name will be set to a random value.

1
2
3
4
5
6

Person person = Instancio.of(Person.class)
    .generate(field(Person::getFirstName), gen -> gen.oneOf("Alice", "Alex", "Robert"))
    .assign(valueOf(Person::getFirstName)
            .to(Person::getPreferredName)
            .when((String firstName) -> firstName.startsWith("A")))
    .create()

In addition, the expression allows specifying a Function for transforming the result. For example, the following snippet sets the preferred name to the same value as the first name, unless the first name is Robert, in which case the preferred name will be set to Bob:

1
2
3
4
5
6

Person person = Instancio.of(Person.class)
    .generate(field(Person::getFirstName), gen -> gen.oneOf("Alice", "Alex", "Robert"))
    .assign(valueOf(Person::getFirstName)
            .to(Person::getPreferredName)
            .as((String firstName) -> "Robert".equals(firstName) ? "Bob" : firstName))
    .create()

Assign.given(origin)¶

This expression allows setting different destination selectors with different values based on a given origin and predicate. The following snippet sets cancellation-related order data when the generated order status is CANCELLED:

1
2
3
4
5
6
7

List<Order> orders = Instancio.ofList(Order.class)
    .assign(Assign.given(Order::getStatus)
        .is(OrderStatus.CANCELLED)
        .set(field(Order::getCancellationReason), "Shipping delays")
        .set(field(Order::isRefundIssued), true)
        .generate(field(Order::getCancellationDate), gen -> gen.temporal().instant().past()))
    .create();

Assign.given(origin, destination)¶

This expression allows mapping predicates to different values for a given pair of origin and destination selectors:

1
2
3
4
5
6
7
8

Person person = Instancio.of(Person.class)
    .assign(Assign.given(field(Address::getCountry), field(Phone::getCountryCode))
        .set(When.isIn("Canada", "USA"), "+1")
        .set(When.is("Italy"), "+39")
        .set(When.is("Poland"), "+48")
        .set(When.is("Germany"), "+49")
        .elseGenerate(gen -> gen.ints().range(1, 999).as(code -> "+" + code)))
    .create();

The When class provides convenience methods for creating predicates. In addition to set(predicate, value) method shown above, this API also supports supply() and generate(), as well as the following optional methods to specify an else action if none of the predicates match:

• elseSet()
• elseSupply()
• elseGenerate()

Assignment Restrictions¶

Origin selector restrictions¶

When using assignments, the origin selector must match a single target. For this reason, the origin does not support selector groups and primitive/wrapper selectors, such as allInts().

For example, Assign.given(allStrings()) is acceptable for the following class because there is only one string that matches the selector:

record MyRecord(String string, Integer number) {}

but not for the following classes because allStrings() would match more than one string value:

record MyRecord(String string1, String string2, Integer number) {}

record MyRecord(List<String> string, Integer number) {}

Convenience primitive/wrapper selectors, such as allInts(), are not accepted by assignments as they are a shorthand for Select.all(all(int.class). all(Integer.class)). Assignment expressions must specify either the primitive, or the wrapper type explicitly: Assign.given(all(Integer.class)).

Collection restrictions¶

Assignments have an additional restriction when used with collections. If the origin selector of an assignment targets a collection element, then destination selector(s) must be within the collection. Assuming we have the following data model:

class Person {
    String name;
    String countryOfCitizenship;
    List<Address> addresses;
}

class Address {
    String street;
    String city;
    String country;
}

It is possible to create an assignment based on address city and fields country:

1
2
3
4
5
6
7

Person person = Instancio.of(Person.class)
    .generate(field(Address::getCountry), gen -> gen.oneOf("France", "Italy", "Spain"))
    .assign(given(field(Address::getCountry), field(Address::getCity))
        .set(When.is("France"), "Paris")
        .set(When.is("Italy"), "Rome")
        .set(When.is("Spain"), "Madrid"))
    .create();

Since Address is a collection element, the assignment is scoped to each Address instance. The following usage, on the other hand, is invalid:

1
2
3
4

Person person = Instancio.of(Person.class)
    .generate(field(Address::getCountry), gen -> gen.oneOf("France", "Italy", "Spain"))
    .assign(valueOf(Address::getCountry).to(Person::getCountryOfCitizenship))
    .create();

This is because Address is a collection element, therefore, valueOf(Address::getCountry) matches multiple values. For this reason, no guarantee is made as to the value that will be assigned to Person.countryOfCitizenship field.

Using onComplete()¶

Another option for customising generated data is using the OnCompleteCallback, a functional interface with the following signature:

1
2
3

interface OnCompleteCallback<T> {
    void onComplete(T object);
}

The OnCompleteCallback is invoked after the generated object has been fully populated. Callbacks can only be invoked on objects:

• created internally by the engine
• created by custom generators via supply(TargetSelector, Generator) or generators registered via GeneratorProvider
• created by internal generators using generate(TargetSelector, Function)

Callbacks are never invoked on objects provided using:

• supply(TargetSelector, Supplier)
• set(TargetSelector, Object)

The following example shows how the Address can be modified using a callback. If the Person has a List<Address>, the callback will be invoked for every instance of the Address class that was generated.

1
2
3
4
5
6
7

Person person = Instancio.of(Person.class)
    .onComplete(all(Address.class), (Address address) -> {
        address.setCity("Vancouver");
        address.setProvince("BC");
        address.setCountry("Canada");
    })
    .create();

If the object is mutable, callbacks allow modifying multiple fields at once. However, callbacks cannot be used to modify immutable types.

Another property of callbacks is that they are only invoked on non-null objects. In the following example, all address instances are nullable. Therefore, a generated address instance may either be null or a fully-populated object. However, if a null was generated, the callback will not be invoked.

1
2
3
4
5
6

Person person = Instancio.of(Person.class)
    .withNullable(all(Address.class))
    .onComplete(all(Address.class), (Address address) -> {
        // only-called if the generated address is not null
    })
    .create();

Summary of methods for customising objects¶

Methods set(TargetSelector, Object) and supply(TargetSelector, Supplier) are for supplying objects as is. The provided objects are treated as read-only by the engine. The behaviour of these methods cannot be customised.

• matching selectors will not be applied
• the engine will not modify or populate any fields of the supplied object
• callbacks are not invoked on objects provided by these methods

Method supply(TargetSelector, Generator) is for creating objects using custom Generator implementations. This method offers configurable behaviour via the AfterGenerate hint. By default, the hint is set to POPULATE_NULLS_AND_DEFAULT_PRIMITIVES, which implies:

• matching selectors will be applied
• the engine will populate null fields and primitive fields containing default values

The default value of the AfterGenerate hint can be overridden using instancio.properties and Settings.

Method generate(TargetSelector, GeneratorSpecProvider) is for customising objects created by internal generators. Such objects include value types (numbers, strings, dates) and data structures (collections, arrays).

• matching selectors are always applied
• matching callbacks are always invoked

By default, the engine generates non-null values, unless specified otherwise.

Ignoring Fields or Classes¶

By default, Instancio will attempt to populate every non-static field value. The ignore method can be used where this is not desirable:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

Person person = Instancio.of(Person.class)
    .ignore(field(Person::getPets))
    .ignore(all(LocalDateTime.class))
    .create();

// Or combining the selectors
Person person = Instancio.of(Person.class)
    .ignore(all(
        field(Person::getPets),
        all(LocalDateTime.class)))
    .create();

Precedence of ignore()¶

The ignore() method has higher precedence than other methods. For example, in the following snippet specifying ignore(all(LocalDateTime.class)) but supplying a value for the lastModified field will actually generate a lastModified with a null value.

1
2
3
4

Person person = Instancio.of(Person.class)
    .ignore(all(LocalDateTime.class))
    .supply(field(Person::getLastModified), () -> LocalDateTime.now())
    .create();

Usage of ignore() with Java records¶

When ignore() is used to target one of the required arguments of a record constructor, then a default value for the ignored type will be generated.

1
2
3
4
5
6
7
8

record PersonRecord(String name, int age) {}

PersonRecord person = Instancio.of(PersonRecord.class)
    .ignore(allInts())
    .ignore(allStrings())
    .create();

// will produce: PersonRecord[name=null, age=0]

Nullable Values¶

By default, Instancio generates non-null values. There are cases where this behaviour may need to be relaxed, for example, to verify that a piece of code does not fail in the presence of certain null values. There are a few ways to specify that values can be nullable which can broadly be grouped into two categories:

• field nullability
• array/collection element and map key/value nullability

Field nullability¶

Field declarations can be made nullable using:

• withNullable(TargetSelector) method of the builder API
• generator spec nullable() method (for generators that support it)
• Settings

For example, the following marks Person.address and all String fields as nullable:

1
2
3
4

Person person = Instancio.of(Person.class)
    .withNullable(field(Person::getAddress))
    .withNullable(allStrings())
    .create();

Some built-in generators also support marking values as nullable using the nullable() method. As in the previous example, this also applies only to string fields, and not, for example, List<String>:

1
2
3

Person person = Instancio.of(Person.class)
    .generate(allStrings(), gen -> gen.string().nullable())
    .create();

The final example, using Settings, follows the same principle:

1
2
3
4
5
6

Settings settings = Settings.create()
    .set(Keys.STRING_NULLABLE, true);

Person person = Instancio.of(Person.class)
    .withSettings(settings)
    .create();

Element nullability¶

Data structure elements can be made nullable using:

• array generator: nullableElements()
• collection generator: nullableElements()
• map generator: nullableKeys(), nullableValues()
• Settings keys
  • Keys.ARRAY_ELEMENTS_NULLABLE
  • Keys.COLLECTION_ELEMENTS_NULLABLE
  • Keys.MAP_KEYS_NULLABLE
  • Keys.MAP_VALUES_NULLABLE

1
2
3
4
5

Person person = Instancio.of(Person.class)
    .generate(field("phoneNumbers"), gen -> gen.collection()
            .nullable()
            .nullableElements())
    .create();

Assuming the Person class contains a Map, nullability can be specified for keys and values:

1
2
3

Person person = Instancio.of(Person.class)
    .generate(all(Map.class), gen -> gen.map().nullableKeys().nullableValues())
    .create();

Lastly, element nullability can be specified using Settings as follows:

1
2
3
4
5
6

Settings settings = Settings.create()
    .set(Keys.COLLECTION_ELEMENTS_NULLABLE, true);

Person person = Instancio.of(Person.class)
    .withSettings(settings)
    .create();

Subtype Mapping¶

Subtype mapping allows mapping a type to its subtype. This can be used for:

• specifying an implementation class for an abstract class or interface
• testing behaviour using different implementations

By default, Instancio does not resolve the implementation class of an abstract type. The only exceptions to this are JDK classes, such List, Map, CharSequence, etc, which default to ArrayList, HashMap, and String, respectively.

For user-defined abstract types, the implementation class must be specified via the API. If not specified:

• a null value will be generated where the abstract type is a field
• an empty collection will be generated where the abstract type is collection element
• an exception will be thrown if root type is abstract and no subtype is specified

Specifying Subtypes¶

The mapping can be specified using the subtype() method provided by InstancioApi:

subtype(TargetSelector selector, Class<?> subtype)

or the mapType() method declared by the Settings class:

mapType(Class<?> type, Class<?> subtype)

Functionally, the two methods are equivalent. However, one may be preferable over another depending on the use case.

The subtype() method

• has higher precedence than the one offered by Settings
• provides more flexibility as it can be applied to any selector target, such as fields

The Settings.mapType() method, on the other hand

• can only be mapped based on class
• is reusable since an instance of Settings can be shared across multiple test methods
• allows subtypes to be specified via instancio.properties and applied automatically

The following is an example of using the subtype() method:

1
2
3
4
5

Person person = Instancio.of(Person.class)
    .subtype(all(all(Collection.class), all(Set.class)), TreeSet.class)
    .subtype(field(Person::getPet), Cat.class)
    .subtype(all(Address.class), AddressImpl.class)
    .create();

The same can be specified using Settings:

1
2
3
4
5
6
7
8
9

Settings settings = Settings.create()
    .mapType(Pet.class, Cat.class)
    .mapType(Collection.class, TreeSet.class)
    .mapType(Set.class, TreeSet.class)
    .mapType(Address.class, AddressImpl.class);

Person person = Instancio.of(Person.class)
    .withSettings(settings)
    .create();

Finally, when specifying the mapping via instancio.properties:

1
2
3
4

subtype.java.util.Collection=java.util.TreeSet
subtype.java.util.Set=java.util.TreeSet
subtype.com.example.Pet=com.example.Cat
subtype.com.example.Address=com.example.AddressImpl

subtypes are resolved automatically:

1
2
3

Person person = Instancio.create(Person.class);

assertThat(person.getPet()).isExactlyInstanceOf(Cat.class)