Key APIs

The EasyRandom class

The key API of Easy Random is the EasyRandom class. You can generate a random instance of any Java type using the nextObject(Class type) method. Easy Random will introspect your object type hierarchy/graph, generate an instance of each nested object and populate it with random data. Easy Random is designed as an extension of java.util.Random with the additional nextObject method, which means you can use it as a java.util.Random (or a replacement of it) without the additional capabilities. Here is an example to show that:

@Test
void testRandomAndEasyRandom() {
    // given
    Random random = new Random(10L);
    EasyRandom easyRandom = new EasyRandom(new EasyRandomParameters().seed(10L));
    // when
    long long1 = random.nextLong();
    long long2 = easyRandom.nextLong();
    // then
    Assertions.assertThat(long1).isEqualTo(long2);
}

The Randomizer interface

By default, Easy Random generates random values according to field type. For example, if you have the following Person class:

class Person {
    private String name;
}

then the field name will be set to a random String, say dfrt0Xgyhu, which is completely meaningless since it is generated randomly.

You may want to generate random data that would be meaningful according to the field it is assigned to. For instance, how to tell Easy Random that the name field is actually a name and its value should be randomly generated from the list {"John","Brad","Tommy"} ?

This is where randomizers come to play. A randomizer is an implementation of the Randomizer<T> interface that controls how to generate random values for the type T :

@FunctionalInterface
public interface Randomizer<T> {

    /**
    * Generate a random value for the given type.
    *
    * @return a random value for the given type
    */
    public T getRandomValue();

}

Let's create a custom randomizer that generates random names:

public class NameRandomizer implements Randomizer<String> {

    private List<String> names = Arrays.asList("John", "Brad", "Tommy");

    @Override
    public String getRandomValue() {
        return names.get(new Random().nextInt(2));
    }

}

Now the question is how to tell Easy Random to use this randomizer to generate random names in the name field of the Person type?

You can do that in two ways:

Either declaratively using the @Randomizer annotation:

class Person {

    @Randomizer(NameRandomizer.class)
    private String name;
}

Note: @Randomizer annotation requires a randomizer with a default constructor. If the randomizer provides a constructor with arguments, you need to use the @RandomizerArgument annotation. You can find an example here.

Or programmatically by registering the randomizer like this:

EasyRandomParameters parameters = new EasyRandomParameters()
   .randomize(FieldPredicates.named("name").and(FieldPredicates.ofType(Integer.class)).and(FieldPredicates.inClass(Person.class)), new NameRandomizer())
   .build();

This snippet tells Easy Random to use the NameRandomizer to generate random values for the field named name of type String in the Person type.

Note: The field type is mandatory and must be specified otherwise an IllegalArgumentException will be thrown for the ambiguous field definition

Built-in randomizers

Easy Random comes with several built-in randomizers for commom attributes such as first name, last name, email, city, country, etc. These randomizers can be found in the org.jeasy.random.randomizers package of the easy-random-randomizers module. Of course, as we have just seen, you can provide your custom randomizers and use them with Easy Random.

The ContextAwareRandomizer interface

The ContextAwareRandomizer extends Randomizer by giving access to the RandomizerContext. The RandomizerContext provides information like:

• The target type being randomized
• The current object being randomized
• The current field being randomized
• etc

A ContextAwareRandomizer will get the randomization context injected during the process and will be able to generate random values depending on the context.