Quick Start - naver/fixture-monkey

Source Files

This page is generated from the following source files:

Introduction to Fixture Monkey

Fixture Monkey is a test fixture generation library designed to simplify the creation of test objects in both Java and Kotlin environments. The library automatically generates random test data, eliminating the need for manual test object construction and reducing boilerplate code in test suites.

The library supports multiple environments including Java with Lombok, Java without Lombok, and Kotlin, with dedicated configuration options for each scenario (docs/docs/get-started/creating-objects.md:7-10). At its core, Fixture Monkey provides a straightforward API that allows developers to generate complex object graphs with minimal setup.

The simplest way to get started involves creating a FixtureMonkey instance and calling the giveMeOne() method with the desired class type. The following example demonstrates this basic usage pattern:

java
1@Test
2void test() {
3    // given
4    FixtureMonkey sut = FixtureMonkey.create();
5
6    // when
7    Order actual = sut.giveMeOne(Order.class);
8
9    // then
10    then(actual).isNotNull();
11}

This test creates a Fixture Monkey instance using the default factory method and generates a random Order object (fixture-monkey-starter/src/test/java/com/navercorp/fixturemonkey/starter/FixtureMonkeyStarterTest.java:53-64). The generated object contains random values for all fields, enabling quick test data generation without manual setup.

Environment Requirements

Java Environment

Fixture Monkey requires Java 8 or higher and integrates seamlessly with popular testing frameworks including JUnit 5 and AssertJ. The library provides dedicated modules for different use cases:

Module	Purpose
`fixture-monkey-starter`	Core Java functionality with Lombok support
`fixture-monkey-starter-kotlin`	Kotlin-specific extensions and introspectors
`fixture-monkey-jackson`	Jackson annotation support (via plugin)

The starter module includes dependencies for basic fixture generation and works with standard Java beans and Lombok-annotated classes (fixture-monkey-starter/src/test/java/com/navercorp/fixturemonkey/starter/FixtureMonkeyStarterTest.java:1-64).

Kotlin Environment

For Kotlin projects, the library provides a dedicated Kotlin module that includes PrimaryConstructorArbitraryIntrospector specifically designed for Kotlin data classes (docs/docs/get-started/creating-objects.md:59). The Kotlin module builds upon the Java starter module and adds Kotlin-specific functionality.

The Gradle configuration for Kotlin projects shows the module dependencies:

kotlin
1dependencies {
2    api(projects.fixtureMonkeyStarter)
3    api(projects.fixtureMonkeyKotlin)
4    
5    testImplementation(libs.junit.jupiter.api)
6    testImplementation(libs.junit.jupiter.engine)
7    testImplementation(libs.assertj.core)
8}

This configuration demonstrates that the Kotlin module extends the base starter functionality while adding Kotlin-specific introspection capabilities (fixture-monkey-starter-kotlin/build.gradle.kts:7-14).

Installation

Gradle Configuration (Recommended)

Add the Fixture Monkey dependency to the project's build.gradle file. For standard Java projects with Lombok support:

groovy
1dependencies {
2    testImplementation("com.navercorp.fixturemonkey:fixture-monkey-starter:1.0.0")
3}

For Kotlin projects, include the Kotlin module:

groovy
1dependencies {
2    testImplementation("com.navercorp.fixturemonkey:fixture-monkey-starter-kotlin:1.0.0")
3}

The Kotlin module automatically includes the base starter module as a transitive dependency (fixture-monkey-starter-kotlin/build.gradle.kts:7-9).

Maven Configuration

Add the dependency to pom.xml:

xml
1<dependency>
2    <groupId>com.navercorp.fixturemonkey</groupId>
3    <artifactId>fixture-monkey-starter</artifactId>
4    <version>1.0.0</version>
5    <scope>test</scope>
6</dependency>

Lombok Configuration

When using Lombok @Value or @AllArgsConstructor annotations, add the following configuration to lombok.config:

lombok.anyConstructor.addConstructorProperties=true

This configuration is required for ConstructorPropertiesArbitraryIntrospector to work correctly with Lombok-annotated classes (docs/docs/get-started/creating-objects.md:67-70).

Basic Setup and Configuration

Creating FixtureMonkey Instance

The FixtureMonkey class serves as the primary entry point for generating test fixtures. Two approaches exist for creating an instance:

Simple Factory Method:

java
1FixtureMonkey fixtureMonkey = FixtureMonkey.create();

This approach uses default settings and is suitable for basic use cases (fixture-monkey-starter/src/test/java/com/navercorp/fixturemonkey/starter/FixtureMonkeyStarterTest.java:56).

Builder Pattern with Custom Introspector:

java
1FixtureMonkey fixtureMonkey = FixtureMonkey.builder()
2    .objectIntrospector(ConstructorPropertiesArbitraryIntrospector.INSTANCE)
3    .build();

The builder pattern allows customization of the object creation strategy through introspectors (docs/docs/get-started/creating-objects.md:18-20).

Choosing an Introspector

The introspector determines how Fixture Monkey creates objects. The appropriate choice depends on the class structure:

Class Structure	Recommended Introspector
Lombok `@Value` / `@AllArgsConstructor`	`ConstructorPropertiesArbitraryIntrospector`
No-args constructor + setters	`BeanArbitraryIntrospector` (default)
Jackson annotations	`JacksonObjectArbitraryIntrospector` (via Jackson Plugin)
Kotlin data class	`PrimaryConstructorArbitraryIntrospector` (via Kotlin Plugin)

This table guides introspector selection based on class design patterns (docs/docs/get-started/creating-objects.md:54-60).

Understanding Object Generation

When giveMeOne() is called, Fixture Monkey traverses the object graph and generates random values for each property. For a Product class defined as:

java
1@Value
2public class Product {
3    long id;
4    String productName;
5    long price;
6    List<String> options;
7    Instant createdAt;
8    ProductType productType;
9    Map<Integer, String> merchantInfo;
10}

The library generates an instance with random values similar to:

java
1Product(
2    id=42,
3    productName="product-value-1",
4    price=1000,
5    options=["option1", "option2"],
6    createdAt=2024-03-21T10:15:30Z,
7    productType=ELECTRONICS,
8    merchantInfo={1="merchant1", 2="merchant2"}
9)

The actual values differ on each execution, providing varied test data across test runs (docs/docs/get-started/creating-objects.md:30-43).

Minimal Runnable Example

Step 1: Define Test Object

Create a test object class with appropriate annotations. The following example uses Lombok's @Data annotation:

java
1@Data
2public static class Order {
3    private Long id;
4    private String orderNo;
5    private String productName;
6    private int quantity;
7    private long price;
8    private List<String> items = new ArrayList<>();
9    private Instant orderedAt;
10    private String sellerEmail;
11}

This class demonstrates common field types including primitives, wrapper objects, collections, and temporal types (fixture-monkey-starter/src/test/java/com/navercorp/fixturemonkey/starter/FixtureMonkeyStarterTest.java:34-51).

Step 2: Write Test

Create a test that generates and validates the fixture:

java
1@Test
2void test() {
3    // given
4    FixtureMonkey sut = FixtureMonkey.create();
5
6    // when
7    Order actual = sut.giveMeOne(Order.class);
8
9    // then
10    then(actual).isNotNull();
11}

This minimal test verifies that Fixture Monkey successfully generates a non-null Order instance (fixture-monkey-starter/src/test/java/com/navercorp/fixturemonkey/starter/FixtureMonkeyStarterTest.java:53-63).

Step 3: Run Test

Execute the test using Gradle:

bash
1./gradlew test --tests "com.navercorp.fixturemonkey.starter.FixtureMonkeyStarterTest"

Or with Maven:

bash
1mvn test -Dtest=FixtureMonkeyStarterTest

Verification and Expected Output

Successful Test Execution

When the test runs successfully, the assertion passes without throwing any exceptions. The generated Order object contains:

Non-null object reference
Random values for all primitive and wrapper fields
Non-empty or empty collections (depending on configuration)
Valid timestamp for Instant fields

The test assertion then(actual).isNotNull() confirms successful object generation (fixture-monkey-starter/src/test/java/com/navercorp/fixturemonkey/starter/FixtureMonkeyStarterTest.java:62).

Debugging Generated Values

To inspect generated values during development, add logging or print statements:

java
1@Test
2void test() {
3    FixtureMonkey sut = FixtureMonkey.create();
4    Order actual = sut.giveMeOne(Order.class);
5    
6    System.out.println("Generated Order: " + actual);
7    System.out.println("Order ID: " + actual.getId());
8    System.out.println("Product Name: " + actual.getProductName());
9    
10    then(actual).isNotNull();
11}

This approach helps verify that the library generates appropriate random values for testing scenarios.

Common Issues and Troubleshooting

Issue 1: NullPointerException on Generated Object

Symptom: The generated object or its nested properties are null when non-null values are expected.

Cause: The default introspector may not match the class structure, or the class lacks appropriate constructors or setters.

Solution: Verify the introspector configuration matches the class design. For classes with no-args constructors and setters, use BeanArbitraryIntrospector (default). For immutable classes with all-args constructors, use ConstructorPropertiesArbitraryIntrospector (docs/docs/get-started/creating-objects.md:52-58).

Issue 2: Lombok Classes Not Working with ConstructorPropertiesArbitraryIntrospector

Symptom: ConstructorPropertiesArbitraryIntrospector fails to instantiate Lombok @Value classes.

Cause: Lombok does not add constructor parameter metadata by default.

Solution: Add lombok.anyConstructor.addConstructorProperties=true to the lombok.config file in the project root directory (docs/docs/get-started/creating-objects.md:67-70). This configuration enables Lombok to generate the necessary metadata for reflection-based instantiation.

Issue 3: Kotlin Data Class Instantiation Fails

Symptom: Fixture Monkey cannot instantiate Kotlin data classes.

Cause: Using the default Java introspector instead of the Kotlin-specific introspector.

Solution: Ensure the fixture-monkey-starter-kotlin module is included as a dependency (fixture-monkey-starter-kotlin/build.gradle.kts:7-10) and use PrimaryConstructorArbitraryIntrospector for Kotlin data classes (docs/docs/get-started/creating-objects.md:59).

Issue 4: Collection Fields Remain Empty

Symptom: List, Set, or Map fields are generated as empty collections.

Cause: Default configuration may limit collection size to zero for performance.

Solution: Customize the fixture generation to specify minimum collection sizes. Refer to the customization documentation for detailed configuration options.

Next Steps

After successfully setting up Fixture Monkey and generating basic test objects, explore the following capabilities:

Customizing Generated Objects

Learn how to customize generated values to match specific test scenarios. The customization features allow setting specific values, applying constraints, and modifying generated data programmatically (docs/docs/get-started/creating-objects.md:87-89).

Advanced Introspector Configuration

Explore additional introspectors for specialized use cases:

JacksonObjectArbitraryIntrospector for classes with Jackson annotations
Custom introspectors for domain-specific object creation patterns

Plugin Integration

Extend Fixture Monkey functionality through plugins:

Jackson Plugin for JSON-related object generation
Kotlin Plugin for idiomatic Kotlin support
Custom plugins for project-specific requirements

Best Practices

Create one FixtureMonkey instance per test class or test suite for performance
Use appropriate introspectors based on class design patterns
Combine Fixture Monkey with assertion libraries like AssertJ for comprehensive testing
Consider using @RepeatedTest to verify behavior across multiple random generated values