What is it?

Instancio is a Java library that automatically creates and populates objects for your unit tests.

Instead of manually setting up test data:

Address address  = new Address();
address.setStreet("street");
address.setCity("city");
//...

Person person = new Person();
person.setFirstName("first-name");
person.setLastName("last-name");
person.setAge(22);
person.setGender(Gender.MALE);
person.setAddress(address);
//...

You can simply do the following:

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

This one-liner returns a fully-populated person, including nested objects and collections.

The object is populated with random data that can be reproduced in case of test failure.

What else can Instancio do?

Create collections of objects:

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

Create streams of objects:

Stream<Person> persons = Instancio.stream(Person.class);

Create generic types:

Pair<List<Foo>, List<Bar>> pairOfLists = Instancio.create(new TypeToken<Pair<List<Foo>, List<Bar>>>() {});

Customise generated values:

Person person = Instancio.of(Person.class)
    .generate(field(Person::getDateOfBirth), gen -> gen.temporal().localDate().past())
    .generate(field(Phone::getAreaCode), gen -> gen.oneOf("604", "778"))
    .generate(field(Phone::getNumber), gen -> gen.text().pattern("#d#d#d-#d#d-#d#d"))
    .subtype(all(AbstractAddress.class), AddressImpl.class)
    .supply(all(LocalDateTime.class), () -> LocalDateTime.now())
    .onComplete(all(Person.class), (Person p) -> p.setName(p.getGender() == Gender.MALE ? "John" : "Jane"))
    .create();

Create reusable templates (Models) of objects:

Model<Person> simpsons = Instancio.of(Person.class)
    .set(field(Person::getLastName), "Simpson")
    .set(field(Address::getCity), "Springfield")
    .generate(field(Person::getAge), gen -> gen.ints().range(40, 50))
    .toModel();

Person homer = Instancio.of(simpsons)
    .set(field(Person::getFirstName), "Homer")
    .set(all(Gender.class), Gender.MALE)
    .create();

Person marge = Instancio.of(simpsons)
    .set(field(Person::getFirstName), "Marge")
    .set(all(Gender.class), Gender.FEMALE)
    .create();

Main Features

Fully reproducible data in case of test failures.
Support for generics, record and sealed classes.
Support for defining custom generators.
Support for generating data based on Bean Validation annotations.
Flexible configuration options.
InstancioExtension for Junit 5 @ExtendWith.

Documentation

Quickstart

Instancio Quickstart is the best way to get started. It is a sample (Maven) project that provides an overview of all the main features.

git clone https://github.com/instancio/instancio-quickstart.git

Latest Release

Version 2.10.0 is now available. A summary of new features is available in the release notes.

Maven coordinates

If you have JUnit 5 on the classpath, use the instancio-junit dependency.

<dependency>
    <groupId>org.instancio</groupId>
    <artifactId>instancio-junit</artifactId>
    <version>2.10.0</version>
    <scope>test</scope>
</dependency>

To use Instancio with JUnit 4, TestNG, or standalone, use instancio-core:

<dependency>
    <groupId>org.instancio</groupId>
    <artifactId>instancio-core</artifactId>
    <version>2.10.0</version>
    <scope>test</scope>
</dependency>

Feedback

Feedback and bug reports are greatly appreciated. Please submit an issue to report a bug, or if you have a question or a suggestion.

Special thanks to

JetBrains and YourKit for supporting this project.

pydawan/instancio