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 Blank Objects¶

In addition to creating fully-populated objects, Instancio provides an API for creating blank objects using the following methods:

Instancio.createBlank(Class<T> type)

Instancio.ofBlank(Class<T> type).create()

Blank objects have value fields (such as strings, numbers, dates) set to null and nested POJO references initialised to blank POJOs. The following is a simple example that assumes a Person class with a name and address fields:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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

// Output:
// Person[name=null, address=Address[street=null, city=null, country=null]]

Person person = Instancio.ofBlank(Person.class)
    .set(field(Address::getCountry), "Canada")
    .create();

// Output:
// Person[name=null, address=Address[street=null, city=null, country=Canada]]

See the documentation for setBlank(TargetSelector) method for more details on blank objects.

Creating Simple Values¶

Instancio offers the Instancio.gen() method to generate simple value types like strings, numbers, and dates. This method serves as the entry point for accessing built-in generators. All generators available through Instancio.gen() implement the ValueSpec interface, which provides the following methods:

1
2
3
4
5
6
7
8
9

URL url = Instancio.gen().net().url().get();

URI uri = Instancio.gen().net().uri().nullable().get();

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

List<LocalDate> dates = Instancio.gen().temporal().localDate().future().list(5);

List<String> uuids = Instancio.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

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.

Select.all(
    Select.field(Address::getCity),
    Select.field(Address.class, "postalCode"),
    Select.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(Select.root(), gen -> gen.collection().size(outerListSize))
    .generate(Select.all(List.class), gen -> gen.collection().size(innerListSize))
    .create();

In this case, Select.all(List.class) matches all lists except the outer list, because Select.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(Select.allStrings(), "foo")
    .set(Select.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 Select.fields() selector has lower precedence than the regular Select.field() selector:

1
2
3
4

Address address = Instancio.of(Address.class)
    .set(Select.fields().named("city"), "foo")
    .set(Select.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(Select.field(Address.class, "city"), "foo")
    .set(Select.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(Select.fields().named("city"), "foo")
    .set(Select.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 = Select.field(Person::getHomeAddress).toScope();
Scope workAddress = Select.field(Person::getWorkAddress).toScope();

Person person = Instancio.of(Person.class)
    .set(Select.field(Address::getCity).within(homeAddress), "foo")
    .set(Select.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(Select.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.

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

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

Select.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.

Select.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:

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

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

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

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

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

Select.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(Select.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:

Select.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"]]]]]

Select.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!"]]]]]

Select.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(Select.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:

Select.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(Select.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 Select.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(Select.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(Select.fields().named("someFieldThatMayNotExist"), "some value")
    .set(Select.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.

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.

Callbacks are always invoked on objects created by generators regardless of AfterGenerate value.

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.

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 be triggered only for objects:

• created internally by the engine
• created by custom generators

Callbacks are never invoked on objects provided using:

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

The following example demonstrates how an Address object can be modified using a callback. If a 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();

Using filter()¶

This method can be used to filter generated values using a predicate. If the predicate evaluates to false for a given value, Instancio will generate a new value. The new value will also be tested against the predicate, and so on.

A simple example is to generate a list of even numbers:

1
2
3

List<Integer> evenNumbers = Instancio.ofList(Integer.class)
    .filter(allInts(), (Integer i) -> i % 2 == 0)
    .create();

A more realistic use case is to ensure that certain fields of a generated object have unique values. For instance, we may want to generate a list of Person objects with unique string and numeric values. If the Person contains numeric IDs, this will ensure that the generated ID values are distinct across all instances:

1
2
3
4
5
6

Set<?> generatedValues = new HashSet<>();

List<Person> persons = Instancio.ofList(Person.class)
    .size(100)
    .filter(all(allInts(), allLongs(), allStrings()), generatedValues::add)
    .create();

It should be noted that using the filter() method can be inefficient if the probability of generating a random value that would be rejected by the predicate is high. This is because a value that does not satisfy the predicate must be generated again. This results in many values being generated and discarded.

In addition. it is not recommended to use filter() with POJOs or collections. For example, if isActive() returns false in the following snippet, the entire User object will be generated from scratch:

1
2
3

List<User> users = Instancio.ofList(User.class)
    .filter(all(User.class), (User user) -> user.isActive())
    .create();

Therefore, customising objects using other APIs, such as generate() should be preferred over filter(), if possible.

Using withUnique()¶

This method can be used to generate unique values for a given selector's targets. Assuming the following class:

record Data(int foo, int bar) {}

The snippet below will generate a list of Data instances with unique foo values:

1
2
3
4

List<Data> results = Instancio.ofList(Data.class)
    .size(100)
    .withUnique(field(Data::foo))
    .create();

Note that the values will be unique across all targets that match the selector. For instance, the following usages:

• withUnique(allInts())
• withUnique(all(field(Data::foo), field(Data::bar))

would result in unique values for foo and bar with no overlap (i.e. foo and bar are disjoint). To generate unique values per field (with potential overlap), the withUnique()method must be specified per field:

1
2
3
4
5

List<Data> results = Instancio.ofList(Data.class)
    .size(100)
    .withUnique(field(Data::foo)) // e.g. { 601, 42, 573, ...}
    .withUnique(field(Data::bar)) // e.g. { 888, 251, 42, ...}
    .create();

If it is impossible to generate a sufficient number of unique values after a certain number of attempts, an exception will be thrown:

1
2
3
4

List<Boolean> results = Instancio.ofList(Boolean.class)
    .size(10)
    .withUnique(allBooleans())
    .create();

Using setBlank()¶

This method can be used to initialise certain parts of an object to be blank using selectors. Its behaviour is the same as the methods below (which can be used for creating a blank root object):

• Instancio.createBlank(Class<T>)
• Instancio.ofBlank(Class<T>)

Blank objects have the following properties:

• value fields (such as strings, numbers, dates) are null
• arrays, collections, and maps are empty
• references to POJOs are initialised to blank objects

For example, assuming the Person class below (getters and setters omitted):

1
2
3
4
5
6

class Person {
    String name;
    LocalDate dateOfBirth;
    List<Phone> phoneNumbers;
    Address address;
}

The following snippet

1
2
3
4

Person person = Instancio.of(Person.class)
    .setBlank(field(Person::getPhoneNumbers))
    .setBlank(all(Address.class))
    .create();

will produce a partially blank object, where only the name and dateOfBirth fields are populated with random values. The address field has been set to a blank object and phoneNumbers to an empty List:

// Person[
//   name=NOBXGV,
//   dateOfBirth=2022-03-18,
//   phoneNumbers=[]
//   address=Address[street=null, city=null, country=null]
// ]

Blank objects can be customised further if needed. For example, we can set the country field to "Canada", generate a collection of blank phones of size 2, and set the countryCode to +1 as shown below:

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

Person person = Instancio.of(Person.class)
    .setBlank(field(Person::getPhoneNumbers))
    .setBlank(all(Address.class))
    .generate(field(Person::getPhoneNumbers), gen -> gen.collection().size(2))
    .set(field(Phone::getCountryCode), "+1")
    .set(field(Address::getCountry), "Canada")
    .create();

// Sample output:
// Person[
//   name=GLTJXQM,
//   dateOfBirth=2029-04-06,
//   phoneNumbers=[
//       Phone[countryCode=+1,number=<null>],
//       Phone[countryCode=+1,number=<null>]]
//   address=Address[street=null, city=null, country=Canada]
// ]

Using ignore()¶

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