Instancio

A library that creates fully populated objects for your unit tests.

Programming language: Java

License: Apache License 2.0

Tags: Testing     Projects     Fixtures    

README

---

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.

If you require specific values, generated data can be customised using the builder API. The following example is a little over the top just to show some of the API capabilities.

Person person = Instancio.of(Person.class)
    .generate(field("age"), gen -> gen.ints().range(18, 65))
    .generate(field(Phone.class, "areaCode"), gen -> gen.oneOf("604", "778"))
    .generate(field(Phone.class, "number"), gen -> gen.text().pattern("#d#d#d-#d#d-#d#d"))
    .generate(all(List.class).within(scope(Address.class)), gen -> gen.collection().size(4))
    .set(field(Address.class, "city"), "Vancouver")
    .ignore(field(Address.class, "postalCode"))
    .supply(all(LocalDateTime.class), () -> LocalDateTime.now())
    .onComplete(all(Person.class), (Person p) -> p.setName(p.getGender() == Gender.MALE ? "John" : "Jane"))
    .create();

Main Features

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

Documentation

• The official user guide
• Sample projects
• An introductory article on Medium.

Getting Started

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

    <dependency>
        <groupId>org.instancio</groupId>
        <artifactId>instancio-junit</artifactId>
        <version>1.5.4</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>1.5.4</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 for supporting this project with their Open Source Licenses.