AutoParams

AutoParams is a JUnit 5 extension for automatic test data generation, inspired by AutoFixture.

Manually creating test data is often repetitive and distracts from the core logic of the test. AutoParams eliminates this boilerplate by supplying automatically generated values to your test method parameters, allowing you to write concise and focused tests.

Getting started is simple: annotate your @Test method with @AutoParams, and the parameters will be populated with generated data.

@Test
@AutoParams
void testMethod(int a, int b) {
    Calculator sut = new Calculator();
    int actual = sut.add(a, b);
    assertEquals(a + b, actual);
}

In the example above, a and b are automatically generated, making the test cleaner and reducing the need for manual setup or value triangulation.

AutoParams also supports more advanced scenarios. When multiple generated values need to share a reference—such as reviews referring to the same product—you can use the @Freeze annotation to ensure consistency.

@AllArgsConstructor
@Getter
public class Product {

    private final UUID id;
    private final String name;
    private final BigDecimal priceAmount;
}

@AllArgsConstructor
@Getter
public class Review {

    private final UUID id;
    private final UUID reviewerId;
    private final Product product;
    private final int rating;
    private final String comment;
}

@Test
@AutoParams
void testMethod(@Freeze Product product, Review[] reviews) {
    for (Review review : reviews) {
        assertSame(product, review.getProduct());
    }
}

This ensures that all generated Review instances refer to the same frozen Product, simplifying test setup in scenarios involving shared dependencies.

Requirements

• JDK 1.8 or higher

Install

Maven

For Maven, you can add the following dependency to your pom.xml:

<dependency>
  <groupId>io.github.autoparams</groupId>
  <artifactId>autoparams</artifactId>
  <version>11.3.2</version>
</dependency>

Gradle

For Gradle, use:

testImplementation 'io.github.autoparams:autoparams:11.3.2'

Features

AutoParams provides a set of features designed to make your tests more expressive and reduce repetitive setup. Here are some of its key capabilities:

@FreezeBy Annotation

The @FreezeBy annotation enables fine-grained control over value freezing in tests. It allows you to freeze a single value and reuse it across multiple generation targets that match specific conditions, such as type or name. This helps improve test readability and ensures consistency among generated values.

Matching Strategies

AutoParams provides several matching strategies that determine which targets should receive the frozen value during object generation. The following examples illustrate some strategies:

• EXACT_TYPE

  Reuses the frozen value for all targets with the exact same type.

  @AllArgsConstructor
  @Getter
  public class StringContainer {
  
      private final String value;
  }
  

  import static autoparams.customization.Matching.EXACT_TYPE;
  
  public class TestClass {
  
      @Test
      @AutoParams
      void testMethod(
          @FreezeBy(EXACT_TYPE) String s1,
          String s2,
          StringContainer container
      ) {
          assertSame(s1, s2);
          assertSame(s1, container.getValue());
      }
  }
  

  In this example, all String targets—including the String field inside StringContainer—are generated with the same frozen value.

• IMPLEMENTED_INTERFACES

  Reuses the frozen value for targets whose types are interfaces that the frozen value's type implements.

  import static autoparams.customization.Matching.IMPLEMENTED_INTERFACES;
  
  public class TestClass {
  
      @Test
      @AutoParams
      void testMethod(
          @FreezeBy(IMPLEMENTED_INTERFACES) String s1,
          CharSequence chars,
          StringContainer container
      ) {
          assertSame(s1, chars);
          assertNotSame(s1, container.getValue());
      }
  }
  

  In this example, String implements CharSequence, so the same value is reused for both s1 and chars. StringContainer is not affected because its type is not an interface.

• PARAMETER_NAME

  Reuses the frozen value for other targets with matching names.

  import static autoparams.customization.Matching.PARAMETER_NAME;
  
  public class TestClass {
  
      @Test
      @AutoParams
      void testMethod(
          @FreezeBy(PARAMETER_NAME) UUID reviewerId,
          Review review
      ) {
          assertNotSame(reviewerId, review.getId());
          assertSame(reviewerId, review.getReviewerId());
      }
  }
  

  This strategy is useful when names follow a consistent convention that reflects their role.

You can also combine multiple matching strategies to broaden the scope of freezing.

import static autoparams.customization.Matching.EXACT_TYPE;
import static autoparams.customization.Matching.IMPLEMENTED_INTERFACES;

public class TestClass {

    @Test
    @AutoParams
    void testMethod(
        @FreezeBy({ EXACT_TYPE, IMPLEMENTED_INTERFACES }) String s1,
        String s2,
        CharSequence chars
    ) {
        assertSame(s1, s2);
        assertSame(s1, chars);
    }
}

In this example, the frozen value s1 is reused for both s2 (same type) and chars (interface implemented by String).

Shorthand for EXACT_TYPE

Using @Freeze is equivalent to @FreezeBy(EXACT_TYPE). It's a convenient shorthand for the most common matching strategy.

@Test
@AutoParams
void testMethod(@Freeze String s1, String s2) {
    assertSame(s1, s2);
}

Setting the Range of Values

You can constrain the range of automatically generated values using the @Min and @Max annotations. These let you define minimum and maximum bounds for numeric parameters, ensuring that generated values fall within a specified range.

To apply a range, annotate the parameter with @Min and/or @Max as needed.

Here's an example:

@Test
@AutoParams
void testMethod(@Min(1) @Max(10) int value) {
    assertTrue(value >= 1);
    assertTrue(value <= 10);
}

In this test, the value parameter will always be an integer between 1 and 10, inclusive.

The @Min and @Max annotations are compatible with the following types:

• byte
• java.lang.Byte
• short
• java.lang.Short
• int
• java.lang.Integer
• long
• java.lang.Long
• float
• java.lang.Float
• double
• java.lang.Double

By combining @Min and @Max with @AutoParams, you can strike a balance between randomness and control, making your parameterized tests more robust and predictable.

ResolutionContext class

The ResolutionContext class provides the core mechanism for generating test data. While it is used internally by AutoParams, you can also instantiate and use it directly in your own test code when needed.

Here's an example:

@Test
void testMethod() {
    ResolutionContext context = new ResolutionContext();
    Product product = context.resolve();
    Review review = context.resolve();
}

In this example, ResolutionContext is used to manually generate instances of Product and Review outside of the @AutoParams annotation. This offers more control and flexibility for writing custom test logic or handling special cases.

Factory<T> class

The Factory<T> class is useful when you need to generate multiple instances of the same type. It allows you to create single instances or collections of generated objects on demand.

Here's an example:

@Test
void testMethod() {
    Factory<Product> factory = Factory.create(Product.class);
    Product product = factory.get();
    List<Product> products = factory.getRange(10);
}

In this example, a Factory<Product> is created to produce Product instances. The get() method creates a single instance, while getRange(n) returns a list of n instances. This approach is particularly helpful when you need bulk data generation in your tests.

Collections and Arrays

AutoParams can generate collections and arrays automatically. By default, the size of generated collections and arrays is 3, but you can override this using annotations such as @Size.

For example, the following tests verify that AutoParams generates an ArrayList<String> and a String[] with exactly 5 elements when the @Size(min = 5) constraint is applied:

@Test
@AutoParams
void testMethod(@Size(min = 5) ArrayList<String> arrayList) {
    assertThat(arrayList).hasSize(5);
}

@Test
@AutoParams
void testMethod(@Size(min = 5) String[] array) {
    assertThat(array).hasSize(5);
}

This allows you to work with realistic data sizes while keeping your test code clean and concise.

Customization

Customization is one of the most powerful features offered by AutoParams. It gives you full control over how test data is generated, allowing you to enforce business rules or tailor the data to meet specific testing needs.

For example, suppose the Product entity must follow these business rules:

• priceAmount must be greater than or equal to 10
• priceAmount must be less than or equal to 10000

You can implement these rules using a custom generator by extending ObjectGeneratorBase<T>:

public class ProductGenerator extends ObjectGeneratorBase<Product> {

    @Override
    protected Product generateObject(ObjectQuery query, ResolutionContext context) {
        UUID id = context.resolve();
        String name = context.resolve();

        ThreadLocalRandom r