-
Notifications
You must be signed in to change notification settings - Fork 232
Key APIs
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);
}
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:
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.
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
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
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.
Easy Random is created by Mahmoud Ben Hassine with the help of some awesome contributors!