Test builders (experimental)

⚠️ Test builders are response based and may generate a lot of code. Moving forward, we recommend to use data builders instead, which are simpler to use. This page is kept as reference only.

Apollo Kotlin provides test builders that enable you to instantiate your GraphQL model classes with default values. Test builders are especially helpful for testing models with a large number of fields or a deeply nested hierarchy. They automatically populate the __typename field and deduplicate merged fields whenever possible.

Enabling test builders

Test builders are not enabled by default, because they aren't useful for every application and they generate additional code. To enable them, set the generateTestBuilders option to true:

1apollo {
2  service("service") {
3    // ...
4
5    // Enable test builder generation
6    generateTestBuilders.set(true)
7  }
8}

This generates a builder DSL for each model used by your operations. These DSLs are based on each model's fields. Using the DSLs, you can set the values of fields you require for a particular test, and mocked values are set automatically for other fields.

Example usage

Let's say we're building a test that uses a mocked result of the following query:

1query HeroForEpisode($ep: Episode!) {
2  hero(episode: $ep) {
3    firstName
4    lastName
5    age
6    
7    ship {
8      model
9      speed
10    }
11
12    friends {
13      firstName
14      lastName
15    }
16
17    ... on Droid {
18      primaryFunction
19    }
20
21    ... on Human {
22      height
23    }
24  }
25}

Here's how we can use the corresponding test builder for that mocked result:

1// Import the query's test builder
2import com.example.test.HeroForEpisodeQuery_TestBuilder.Data
3
4@Test
5fun test() {
6  val data = HeroForEpisodeQuery.Data {
7    // Set values for particular fields of the query
8    hero = humanHero {
9      firstName = "John"
10      age = 42
11      friends = listOf(
12        humanFriend {
13          firstName = "Jane"
14        },
15        humanFriend {
16          lastName = "Doe"
17        }
18      )
19      ship = ship {
20        model = "X-Wing"
21      }
22    }
23  }
24
25  assertEquals("John", data.hero.firstName)
26  assertEquals(42, data.hero.age)
27}

In this example, the hero field is a Human object with specified values for firstName and age. The values for lastNameand height are automatically populated with mock values. Similarly, values for the ship's speed, the 1st friend's last name and 2nd friend's first name are automatically populated.

You can replace humanHero above with droidHero to create a Droid object instead, or specify otherHero to create an object that is neither a Human nor a Droid.

Configuring default field values

To assign default values to fields, test builders use an implementation of the TestResolver interface. By default, they use an instance of DefaultTestResolver.

The DefaultTestResolver gives each String field the field's name as its default value, and it increments a counter as it assigns default values for Int fields. It defines similar default behavior for other types.

You can create your own TestResolver implementation (optionally extending DefaultTestResolver for a head start). You then pass this implementation as a parameter to the Data function, like so:

1// A TestResolver implementation that assigns -1 to all Int fields
2val myTestResolver = object : DefaultTestResolver() {
3  override fun resolveInt(path: List<Any>): Int {
4    return -1
5  }
6}
7
8@Test
9fun test() {
10  val data = HeroForEpisodeQuery.Data(testResolver = myTestResolver) {
11    hero = humanHero {
12      firstName = "John"
13    }
14  }
15
16  // Unspecified Int field is -1
17  assertEquals(-1, data.hero.age)
18}