Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/instancio/instancio
A library that creates fully populated objects for your unit tests.
https://github.com/instancio/instancio
data-generator java junit junit-jupiter random random-generation test-automation test-data-generator testing unit-testing
Last synced: about 2 months ago
JSON representation
A library that creates fully populated objects for your unit tests.
- Host: GitHub
- URL: https://github.com/instancio/instancio
- Owner: instancio
- License: apache-2.0
- Created: 2022-03-03T06:42:29.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-12T14:25:55.000Z (2 months ago)
- Last Synced: 2024-04-14T03:00:04.685Z (2 months ago)
- Topics: data-generator, java, junit, junit-jupiter, random, random-generation, test-automation, test-data-generator, testing, unit-testing
- Language: Java
- Homepage: https://www.instancio.org
- Size: 8.16 MB
- Stars: 741
- Watchers: 9
- Forks: 45
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
Lists
- awesome-java - Instancio - Automates data setup in unit tests by generating fully-populated, reproducible objects. Includes JUnit 5 extension. (Projects / Testing)
- awesome-java-zh - Instancio - 通过生成完全填充的，可重现的对象来自动执行单元测试中的数据设置。包括JUnit 5扩展。 (项目 / 测试)
README
[](https://search.maven.org/artifact/org.instancio/instancio-core/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://sonarcloud.io/summary/new_code?id=instancio_instancio)
[](https://sonarcloud.io/summary/new_code?id=instancio_instancio)
---
# 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:
```java
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:
```java
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?
1. Create collections of objects:
```java
List persons = Instancio.ofList(Person.class).size(10).create();
```
2. Create streams of objects:
```java
Stream persons = Instancio.stream(Person.class).limit(5);
```
3. Create generic types:
```java
Pair, List> pairOfLists = Instancio.create(new TypeToken, List>>() {});
```
4. Customise generated values:
```java
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();
```
5. Create reusable templates (Models) of objects:
```java
Model 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();
```
## Main Features
- Fully reproducible data in case of test failures.
- Support for generics, `record` and `sealed` classes, Java 21 sequenced collections.
- Support for defining custom generators.
- Support for generating data based on Bean Validation annotations.
- Flexible configuration options.
- `InstancioExtension` for Junit 5 `@ExtendWith`.
- Support for Guava via `instancio-guava` module (experimental)
- Support for property-based testing via `instancio-quickcheck` module (experimental)
## Documentation
- [User guide](https://www.instancio.org/user-guide) (instancio.org)
- [Javadocs](https://javadoc.io/doc/org.instancio/instancio-core/latest/) (javadoc.io)
## Quickstart
[Instancio Quickstart](https://github.com/instancio/instancio-quickstart) is the best way to get started.
It is a sample (Maven) project that provides an overview of all the main features.
```sh
git clone https://github.com/instancio/instancio-quickstart.git
```
## Latest Release
Version `4.1.0` is now available.
A summary of new features is available in the [release notes](https://github.com/instancio/instancio/releases).
# Maven Coordinates
If you have JUnit 5 on the classpath, use the `instancio-junit` dependency.
```xml
org.instancio
instancio-junit
4.1.0
test
```
To use Instancio with JUnit 4, TestNG, or standalone, use `instancio-core`:
```xml
org.instancio
instancio-core
4.1.0
test
```
# Feedback
Feedback and bug reports are greatly appreciated!
- Please submit an [issue](https://github.com/instancio/instancio/issues) for bug reports and feature requests.
- For general feedback or questions, please create a post in the [Discussions](https://github.com/instancio/instancio/discussions).
Please check the [User Guide](https://www.instancio.org/user-guide), previous issues and discussions before creating a new one.
# Third-party Extensions
- [instancio-jpa](https://github.com/Mobe91/instancio-jpa) created by [Moritz Becker](https://github.com/Mobe91)
> 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.
# Credits
Thanks to [JetBrains](https://www.jetbrains.com/opensource) and [YourKit](https://www.yourkit.com)
for supporting this project with their open source licenses.
