Data builders
Data builders are currently experimental in Apollo Kotlin. If you have feedback on them, please let us know via GitHub issues or in the Kotlin Slack community.
Apollo Kotlin generates models for your operations and parsers that create instances of these models from your network responses. Sometimes though, during tests or in other occasions, it is useful to instantiate models manually with known values.
Doing so is not as straightforward as it may seem, especially when fragments are used. Creating operationBased
models requires instantiating every fragment as well as choosing an appropriate __typename
for each composite type.
Data builders make this easier by providing builders that match the structure of the Json document.
Enabling data builders
To enable data builders, set the generateDataBuilders
option to true
:
apollo {service("service") {// ...// Enable data builder generationgenerateDataBuilders.set(true)}}
This generates a builder for each composite type in your schema as well as a helper Data {}
function for each of your operations.
Example usage
Let's say we're building a test that uses a mocked result of the following query:
query HeroForEpisode($ep: Episode!) {hero(episode: $ep) {firstNamelastNameageship {modelspeed}friends {firstNamelastName}... on Droid {primaryFunction}... on Human {height}}}
Here's how we can use the corresponding data builder for that mocked result:
@Testfun test() {val data = HeroForEpisodeQuery.Data {// Set values for particular fields of the queryhero = buildHuman {firstName = "John"age = 42friends = listOf(buildHuman {firstName = "Jane"},buildHuman {lastName = "Doe"})ship = buildStarship {model = "X-Wing"}}}assertEquals("John", data.hero.firstName)assertEquals(42, data.hero.age)}
In this example, the hero
field is a Human
object with specified values for firstName
and age
. The values for lastName
and 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 buildHuman
above with buildDroid
to create a Droid
object instead.
Aliases
Because data builders are schema-based and aliases are defined in your queries, there is no way for the codegen to generate builder fields for them. Instead, you'll need to specify them explicitly.
Given a query like this:
query GetHeroes {luke: hero(id: "1002") {name}leia: hero(id: "1003") {name}}
You can generate a fake data model like so:
val data = GetHeroes.Data {this["luke"] = buildHumanHero {name = "Luke"}this["leia"] = buildHumanHero {name = "Leia"}}
@skip
and @include
directives
By default, the data builders match the types in your schema. If a field is non-null you will either have to provide a value or let the default resolver provide one. This is an issue for @skip
and @include
directives where a field might be absent even if it is non-nullable. To account for this case, use the same syntax as for aliases and set the value to Optional.Absent
.
query Skip($skip: Boolean!) {nonNullableInt @skip(if: $skip)}
You can generate a fake data model like so:
val data = SkipQuery.Data {this["nonNullableInt"] = Optional.Absent}assertNull(data.nonNullableInt)
Configuring default field values
To assign default values to fields, data builders use an implementation of the FakeResolver
interface. By default, they use an instance of DefaultFakeResolver
.
The DefaultFakeResolver
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 FakeResolver
implementation (optionally delegating to DefaultFakeResolver
for a head start). You then pass this implementation as a parameter to the Data
function, like so:
// A FakeResolver implementation that assigns -1 to all Int fieldsclass MyFakeResolver : FakeResolver {private val delegate = DefaultFakeResolver(__Schema.all)override fun resolveLeaf(context: FakeResolverContext): Any {return when (context.mergedField.type.leafType().name) {"Int" -> -1 // Always use -1 for Intselse -> delegate.resolveLeaf(context)}}override fun resolveListSize(context: FakeResolverContext): Int {// Delegate to the default behaviourreturn delegate.resolveListSize(context)}override fun resolveMaybeNull(context: FakeResolverContext): Boolean {// Neverreturn false}override fun resolveTypename(context: FakeResolverContext): String {// Delegate to the default behaviourreturn delegate.resolveTypename(context)}}@Testfun test() {val data = HeroForEpisodeQuery.Data(resolver = MyFakeResolver()) {hero = buildHuman {firstName = "John"}}// Unspecified Int field is -1assertEquals(-1, data.hero.age)}