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.
- 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).limit(5);- 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")
.create();
Person marge = Instancio.of(simpsons)
.set(field(Person::getFirstName), "Marge")
.create();- Use data feeds for data defined in external sources (e.g. CSV or JSON):
List<Person> person = Instancio.ofList(Person.class)
.size(10)
.applyFeed(all(Person.class), feed -> feed.ofResource("persons.csv"))
.create();- Define custom feeds for reuse across tests:
@Feed.Source(resource = "persons.csv")
interface PersonFeed extends Feed {
@TemplateSpec("${firstName} ${lastName}")
FeedSpec<String> fullName();
@FunctionSpec(params = {"fullName", "dateOfBirth"}, provider = BioProvider.class)
FeedSpec<String> bio();
class BioProvider implements FunctionProvider {
String describePerson(String fullName, LocalDate dateOfBirth) {
int age = Period.between(dateOfBirth, LocalDate.now()).getYears();
return String.format("%s is %d years old", fullName, age);
}
}
}
// Usage:
List<Person> person = Instancio.ofList(Person.class)
.applyFeed(all(Person.class), feed -> feed.of(PersonFeed.class))
.create();- Inject arguments into fields and parameters with JUnit 5:
@ExtendWith(InstancioExtension.class)
class ExampleTest {
@Given
private List<String> randomList;
@Test
void example1(@Given String randomSting, @Given(SomeCustomProvider.class) customString) {
//...
}
@ValueSource(strings = {"foo", "bar"})
@ParameterizedTest
void example2(String fooOrBar, @Given long randomLong) {
// ...
}
}- Run parameterized tests against many samples of generated inputs:
@ExtendWith(InstancioExtension.class)
class ExampleTest {
@InstancioSource(samples = 1000)
@ParameterizedTest
void example(UUID randomUuid, Foo randomFoo, @Given(BarProvider.class) Bar customBar) {
// runs the test method 1000 times against generated inputs
}
}- Fully reproducible data in case of test failures.
- Support for generics,
recordandsealedclasses, Java 21 sequenced collections. - Data generation based on JPA and Bean Validation annotations (Hibernate, jakarta, javax).
- Flexible configuration options and SPIs.
- Support for defining custom generators.
InstancioExtensionfor Junit 5@ExtendWith.- Object population via fields and setters.
-
User guide (instancio.org)
-
Javadocs (javadoc.io)
-
Quickstart (github.com) sample Maven project with usage examples
git clone https://github.com/instancio/instancio-quickstart.git
If you have JUnit 5 on the classpath, use the instancio-junit dependency.
<dependency>
<groupId>org.instancio</groupId>
<artifactId>instancio-junit</artifactId>
<version>LATEST</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>LATEST</version>
<scope>test</scope>
</dependency>Feedback and bug reports are greatly appreciated!
- Please submit an issue for bug reports and feature requests.
- For general feedback or questions, please create a post in the Discussions.
Please check the User Guide, previous issues and discussions before creating a new one.
- instancio-jpa created by Moritz Becker
Instancio-jpa is an extension on top of the Instancio library that enables the creation and population of JPA entities including the subsequent persistence of these entities using JPA for the purpose of test data generation in integration tests.
If you like Instancio, please consider supporting its maintenance and development by becoming a sponsor.
A big thank you to the current project sponsors:
Thanks to JetBrains and YourKit for supporting this project with their open source licenses.
Available as part of the Tidelift Subscription
The maintainers of Instancio and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.