Instantiator

Tired of manually setup test data of Kotlin data classes or POJOs? Instantiator creates Instances of any class for you so that you can focus on writing tests instead of spending time and effort to set up test data.

This is not a mocking library. When saying that Instantiator can create an instance of any class for you, I'm referring to data classes or POJOs, not mock functionality.

It doesn't use any black magic. It uses reflection and invokes the public primary constructors. If there is no public primary constructor available, then Instantiator cannot instantiate it.

Dependencies

testImplementation 'com.hannesdorfmann.instantiator:instantiator:1.0.0'

or SNAPSHOT (directly built from main branch):

testImplementation 'com.hannesdorfmann.instantiator:instantiator:1.0.1-SNAPSHOT'

Usage

Assuming you have some data structures like this

data class Person(
    val id: String,
    val firstname: String,
    val lastname: String,
    val age: Int,
    val gender: Gender
)

enum class Gender {
    MALE,
    FEMALE,
    UNDEFINED
}

fun computeFullname(p: Person): String {
    return "${p.firstname} ${p.lastname}"
}

And you want to write some (unit) tests to test some functionality you often have to manually set up some object instances just for testing. This is where Instantiator comes in: it creates such instances for you.

@Test
fun someTest() {
    val person: Person =
        instance() // instance() is Instantiator's API. It creates a new instance of Person with random values. 

    // Now that you have some random Person object 
    // you can do with it whatever you want
    val expected = "${person.firstname} ${person.lastname}"
    val fullname = computeFullname(person)
    assertEquals(expected, fullname)
}

Bonus: if you want to get an instance for each subclass of a sealed class hierarchy use instantiateSealedSubclasses() like this:

sealed class Root
data class A(i: Int) : Root()
data class B(i: Int) : Root()


sealed class NestedRoot : Root()
data class N1(i: Int) : NestedRoot()


val subclassesInstances: List<Root> = instantiateSealedSubclasses()
println(subclasses) // contains 3 instances and prints  "A, B, N1"

Supported use cases

Configuration

You can configure Instantiator by passing a InstantiatorConfig instance as parameter to instance(config : InstantiatorConfig) or instantiateSealedSubclasses(config : InstantiatorConfig).

Some settings that you can set:

• InstantiatorConfig.useDefaultArguments: Set it to true if you want that the default arguments of constructor parameters are used if provided. For example, given data class MyClass(val id : Int, val name : String = "Barbra"), if config.useDefaultArguments = true then the parametername of any instance will be name="Barbra" and only id which has no default argument set will be filled with random value. Default value of the default config is that InstantiatorConfig.useDefaultArguments = true.
• InstantiatorConfig.useNull: Set it to true if for constructor parameters that can be null, null is actually the value without even asking an InstanceFactory to create an instance. This is a shortcut that ensures always null, for example: given data class MyClass(val id : Int?), if config.useNull = true then instance will look like MyClass( id = null). If config.useNull = false then InstanceFactor will be called to decide if a null or non-null value is returned. Default value of default config is InstantiatorConfig.useNull = true
• InstantiatorConfig.random: This random is passed to all InstanceFactories and is used by them to randomly create values. Pass a seeded Random, i.e. Random(0), to ensure always the same random values are generated.

As you see there are multiple configuration that impact value creation: config.useDefaultArguments, config.useNull and InstanceFactory. The order and priority internally in Instantiator is the following:

1. config.useDefaultArguments = true is used first. So if set to true, then default values are used.
2. config.useNull = true is used as second. So if useDefaultArguments = false and useNull = true then all optional parameters are filled with null.
3. InstanceFactory is used as last. So if useDefaultArguments = false and useNull = false then InstanceFactory for the given type then is asked to instantiate a value.

class Foo(val i: Int? = 42)

val foo = instance<Foo>()

println(foo.i) // prints 42

Custom InstanceFactory

InstantiatorConfig takes as a constructor parameter vararg factories: InstanceFactory. An InstanceFactory is used to create an instance in case an unsupported build-in type needs to be instantiated (see supported types table above) or if you want to override how primitive types are instantiated.

The way how Kotlin's reflection and type system work is that there is a difference between i.e Int and Int? (so null and non-null types). That is the reason why two different InstanceFactory exist:

1. interface NonNullableInstanceFactory<T> : InstanceFactory: This factory returns a non-null value.
2. interface NullableInstanceFactory<T> : InstanceFactory: This factory can return a non-null or null value. It's up to the instance factory to decide (i.e. by using the Random).

class MyIntInstanceFactory : InstantiatorConfig.NonNullableInstanceFactory<Int> {
    override val type: KType = Int::class.createType()
    override fun createInstance(random: Random): Int = 42
}

class MyDateInstanceFactory : InstantiatorConfig.NullableInstanceFactory<Calendar> {
  override val type: KType = Calendar::class.createType(nullable = true)
  override fun createInstance(random: Random): Date? = if (random.nextBoolean()) null else Date()
}

data class Foo(val i : Int, val date : Date?)

val config = InstantiatorConfig(useNull = false, MyIntInstanceFactory(), MyCalendarInstanceFactory())
val foo = instance<Foo>(config)

println(foo.i) // i == 42
println(foo.date) // can be null or current Date 

Please note that unless you explicitly need a very custom behavior for null values of a specific type there is no need to create a subclass of NullableInstanceFactory. Just create a NonNullableInstanceFactory, add it to your InstantiatorConfig and Instantiator does automatically create a NullableInstanceFactory out of it under the hood (uses NonNullableInstanceFactory.toNullableInstanceFactory()).

InstantiatorConfig is immutable. You can add an InstanceFactory with the val newConfig : InstantiatorConfig = existingInstantiatorConfig.add(myCustomFactoy)