fiktion

0.5.0indexed

Fake-data generator for tests that builds realistic object graphs with scoped overrides, deterministic seeds, nested targeting, collection/map handling, null/default control, and extensible add-ons.

JSJVMNativeWasm·sya-ri/fiktion

Stars

—

Used by

dependents

Health

/ 100

Fiktion

Fiktion is a Kotlin Multiplatform fake data library for tests that should read like intent, not fixture setup.

It creates complete, realistic-enough object graphs from your Kotlin types, then lets each test override only the values that matter. No annotations in production code. No builders for every model. No fixture files drifting away from the domain.

@Test
fun `paid orders are shipped`() {
    val order = fake<Order> {
        Order::status generates OrderStatus.Paid
        // Other values are filled in automatically.
    }

    shippingService.ship(order)

    assertEquals(
        ShipmentStatus.Created,
        shipmentRepository.findByOrderId(order.id).status
    )
}

Fiktion is built for the common testing problem where the object shape matters, but most individual values do not:

val user = fake<User> {
    User::id generates "user-1"
}

You get:

object graph generation for ordinary Kotlin classes
scoped overrides for the fields a test actually asserts
deterministic output with seeds
collection, map, nullable, default-value, enum, sealed, object, class, data class, and value class support
add-ons for external libraries, including common Java/JVM standard library types

Status

Fiktion is pre-release. The core behavior is usable, but API names and compiler-generated metadata internals may change before 1.0.

The everyday test DSL is the compatibility priority: fake<T>(), property and name rules, generator configuration, add-on installation, and built-in generator helpers are intended to stay source-compatible across ordinary 0.x patch releases. APIs marked with @ExperimentalFiktionApi are lower-level integration points for compiler-generated metadata, automatic add-on registration, and runtime metadata construction. They may change more freely before 1.0 as the compiler plugin and metadata model settle.

The repository currently contains:

fiktion-core: runtime APIs and built-in generators

Install

Apply the Gradle plugin and add the runtime to your test dependencies:

plugins {
    kotlin("jvm") version "2.4.0"
    id("dev.s7a.fiktion") version "0.5.1"
}

dependencies {
    testImplementation("dev.s7a:fiktion-core:0.5.1")

    // Optional: Arrow Core types such as Option, Either, Ior, NonEmptyList, and NonEmptySet.
    testImplementation("dev.s7a:fiktion-addon-arrow-core:0.5.1")

    // Optional: common JVM types such as Instant, UUID, URI, and Java collections.
    testImplementation("dev.s7a:fiktion-addon-java:0.5.1")

    
    testImplementation()

    
    detektPlugins()
}

If detekt is not configured yet, follow the official detekt Gradle setup before adding fiktion-detekt-rules.

Fiktion is enabled for test source sets by default, including JVM test and Multiplatform source sets such as commonTest and jvmTest.

Kotlin Compatibility

Fiktion 0.5.1 is built with Kotlin 2.4.0 and supports consumer projects using Kotlin 2.4.x. The repository is tested with a consumer project using Kotlin 2.4.0.

The compiler plugin uses Kotlin compiler APIs, so compatibility is verified per consumer Kotlin version instead of assuming all future compiler releases work automatically. Maintainers can run the same check locally with:

./gradlew publishToMavenLocal
./gradlew -p compatibility/jvm-consumer test -Pconsumer.kotlin.version=2.4.0

Kotlin 2.3.x and 2.2.x are not supported by artifacts built with Kotlin 2.4.0. Kotlin 2.3.0 fails to load the compiler plugin because the Kotlin compiler API is not binary-compatible with the 2.4.0-built plugin. Supporting multiple Kotlin compiler lines requires publishing compiler-plugin artifacts per Kotlin version and selecting the matching artifact from the Gradle plugin.

Runnable sample projects live in examples/.

Basic Usage

Generate a value with fake<T>():

val text = fake<String>()
val count = fake<Int>()
val user = fake<User>()

Use a seed when a test needs repeatable data:

val first = fake<User>(seed = 123)
val second = fake<User>(seed = 123)

check(first == second)

Override only what the test cares about:

val user = fake<User> {
    User::id generates "user-1"
    User::displayName generates "Test User"
}

Rules inside fake<T> { ... } apply to that generated object graph only, so one test does not accidentally configure another model.

Nested Properties

Nested objects can be configured inline:

val user = fake<User> {
    User::profile {
        Profile::nickname generates "example"
    }
}

You can also target a nested path directly:

val user = fake<User> {
    (User::profile / Profile::nickname) generates "example"
}

Name rules are useful when the same convention appears across several types:

val user = fake<User> {
    name("id") generates "user-1"
    name(".*Name".toRegex()) generatesBy { "generated-name" }
}

Collections And Maps

Collections can generate each element automatically:

val catalog = fake<Catalog> {
    Catalog::items {
        this using FiktionConfig.Collection.size(3)
    }
}

Or you can provide element rules:

val catalog = fake<Catalog> {
    Catalog::tags {
        this using FiktionConfig.Collection.size(1..5)
        element generatesBy { string(length = 8) }
    }
}

Maps support key and value targets:

val index = fake<SearchIndex> {
    SearchIndex::entries {
        key generatesBy { string(length = 8) }
        value generatesBy { fake<Entry>() }
    }

    SearchIndex::aliases generatesOneOf listOf("primary", "secondary")
}

Nulls And Defaults

Automatic nullable values generate either a non-null value or null with 50% probability. Explicit generated values stay fixed unless you opt into nulls with a probability:

val user = fake<User> {
    User::nickname generates "nickname" orNullAt 0.3
}

Defaultable constructor arguments generate either an automatic value or the constructor default with 50% probability. Explicit generated values stay fixed unless you opt into defaults with a probability:

val user = fake<User> {
    User::profile generates Profile(nickname = "generated") orDefaultAt 30.percent
    User::profile generates default
}

Double probabilities use 0.0..1.0. Percentage helpers are available with percent.

When a name rule intentionally generates null, declare the value type explicitly:

name<String?>("nickname") generates null
name<String?>("nickname") generatesBy { null }

Reusable Configuration

Use Fiktion { ... } when a test suite needs a local generator configuration:

val fiktion = Fiktion {
    type<User>() generatesBy {
        User(id = "api-user-${random.nextLong()}")
    }
}

val user = fiktion.fake<User>()

Use Fiktion.configure for process-wide test configuration. It returns a snapshot so the previous configuration can be restored:

val snapshot = Fiktion.configure {
    name<String>("email") generatesBy {
        "test-${random.nextInt()}@example.test"
    }
}

try {
    val user = fake<User>()
} finally {
    check(snapshot.restore())
}

Fiktion.configure is useful when the same defaults should apply to top-level fake<T>() calls across a test project or framework-managed test context:

val snapshot = Fiktion.configure {
    name<String>("email") generatesBy {
        "user-${random.nextLong()}@example.test"
    }
    name<String>("id") generatesBy {
        "id-${random.nextLong()}"
    }
}

Because the configuration is global, prefer fake<T> { ... } or Fiktion { ... } for rules that only one test needs. When global configuration is installed by a test hook, restore the snapshot in the matching teardown hook. restore() returns false if another Fiktion.configure call has installed a newer global configuration; use restore(force = true) only from cleanup code that owns the whole test process or project-level configuration.

Rule precedence is:

Per-call rules
Fiktion instance rules
Global rules
Add-on rules
Built-in rules

Within the same precedence level, more specific targets win before registration order. When two matching rules have the same specificity, the later registration wins.

Generator Defaults

Use typed generator configuration when you want to keep Fiktion's default generators but adjust their ranges, sizes, or formats:

import dev.s7a.fiktion.FiktionConfig
import dev.s7a.fiktion.Fiktion
import dev.s7a.fiktion.fake
import dev.s7a.fiktion.invoke

val fiktion = Fiktion {
    this using FiktionConfig.Int.range(-200..200)
    this using FiktionConfig.String.length(8)
    this using FiktionConfig.Collection.size(3)
}

val users = fiktion.fake<List<User>>()

Per-call configuration is scoped to the generated root type:

val names = fake<List<String>> {
    this using FiktionConfig.Collection.size(5)
}

this using ... is a member inside the lambda, so it does not need a separate import. The shorthand uses Fiktion's operator extension, so import or use . Use for , , and other collection types, and for maps.

Sets use normal set semantics by default, so duplicate generated elements can collapse and make the final set smaller than FiktionConfig.Collection.size. Use UniqueElementStrategy.Exact when a set must contain the configured number of distinct values:

val labels = fake<Set<String>> {
    this using FiktionConfig.Collection.size(3)
    this using FiktionConfig.Collection.uniqueElementStrategy(UniqueElementStrategy.Exact(maxAttemptsPerElement = 16))
}

Exact set generation retries candidate values up to size * maxAttemptsPerElement. If Fiktion cannot produce enough distinct values within that bound, generation fails instead of silently returning a smaller set.

Custom collection converters can opt into the same distinct-element generation:

val fiktion = Fiktion {
    configureCollection<CustomSet<*>>(unique = true) { elements ->
        CustomSet(elements)
    }
}

Container target configuration narrows defaults to values generated below collection and map roots:

Use key and value targets when defining map key or value generation, including nested configuration blocks.

Property configuration narrows a generator default to one property:

val user = fake<User> {
    User::id using FiktionConfig.String.length(12)
}

Configuration keys are grouped under FiktionConfig, with add-on specific keys under add-on config objects such as JavaFiktionConfig and KotlinxDatetimeFiktionConfig.

Detekt Rules

Fiktion often has several equivalent DSL forms. fiktion-detekt-rules helps teams keep those choices consistent by recommending the narrower or more direct form when two forms express the same intent. This is useful for shared test code because the rule feedback appears during normal linting, before the style spreads through fixtures and helpers.

Add it as a detekt plugin dependency. If detekt is not configured in the project yet, follow the official detekt Gradle setup first. The rules are published under the fiktion rule set.

dependencies {
    detektPlugins("dev.s7a:fiktion-detekt-rules:0.5.1")
}

See fiktion-detekt-rules for rule details.

Test Framework Integration

With kotlin.test, prefer an isolated Fiktion { ... } instance from @BeforeTest when each test should start from the same defaults. Use Fiktion.configure with @BeforeTest / @AfterTest only when the test intentionally needs top-level fake<T>() calls to see global rules:

import dev.s7a.fiktion.Fiktion
import dev.s7a.fiktion.fake
import kotlin.test.BeforeTest
import kotlin.test.Test

  {
       fiktion: Fiktion

    
     {
        fiktion = Fiktion {
            name<String>() generatesBy {
                
            }
        }
    }

    
     {
         user = fiktion.fake<User>()

        
    }
}

With JUnit 5, @TestInstance(TestInstance.Lifecycle.PER_CLASS) only shares one test class instance across methods in that class. Prefer an isolated instance for class-scoped defaults:

Use Fiktion.configure when the rules intentionally need to affect global fake<T>() calls, for example project-wide test helpers or framework hooks that do not receive a Fiktion instance. Since this mutates process-wide state, keep it at project-level setup when tests may run in parallel.

For JUnit 5, put process-wide defaults in an extension and store the snapshot in the root extension store:

With Kotest, prefer an isolated instance for spec-scoped defaults. Kotest specs are SingleInstance by default, so a property initialized in the spec body is shared by tests in that spec:

The same pattern works with other Kotest spec styles such as FunSpec, DescribeSpec, FreeSpec, ShouldSpec, and BehaviorSpec; keep the Fiktion { ... } instance at the spec scope and call fiktion.fake<T>() from tests.

import dev.s7a.fiktion.Fiktion
import dev.s7a.fiktion.fake
import io.kotest.core.spec.style.StringSpec

class UserRepositorySpec : StringSpec({
    val fiktion = Fiktion {
        name<String>("email") generatesBy {
            "user-${random.nextLong()}@example.test"
        }
    }

    "finds user by email" {
        val user = fiktion.fake<User>()

        // test body
    }
})

Kotest project configuration is useful only when global defaults should affect top-level fake<T>() across the whole test project:

Rule Targets

Configuration scopes support type, property, path, and name targets:

type<User>() generatesBy { /* any User */ }
property<User, String>() generatesBy { /* any String property owned by User */ }
property<User, String>("id") generates "user-1"
name<String>("id") generates "shared-id"
name("email") generatesBy { "test-${random.nextInt()}@example.test" }
property(User::profile / Profile::nickname) generates "example"
User::id generates "user-1"

Property references such as User::id generates "user-1" are the concise form for owner-specific property rules. property<User, String>("id") is the equivalent explicit form when the owner and value type should be spelled out.

Compiler Plugin

The compiler plugin generates runtime metadata for Kotlin types in enabled source sets. This is what lets Fiktion create objects without annotations.

Supported shapes include:

regular classes and data classes with supported primary constructors
local classes with supported primary constructors
value classes with one constructor value
enum classes
sealed classes and sealed interfaces
singleton objects and companion objects

Shapes that should be configured explicitly are skipped:

abstract classes and interfaces
fun interfaces and annotation classes
inner classes
classes without a primary constructor
private or protected primary constructors
vararg or otherwise unsupported constructor parameters

Value class overrides depend on what the test wants to control. For a public underlying property, target that property:

@JvmInline
value class UserId(val value: String)

val userId = fake<UserId> {
    UserId::value generates "user-1"
}

For a private underlying property, use a name rule because Kotlin code outside the class cannot reference the property:

@JvmInline
value class UserId(private val value: String)

val userId = fake<UserId> {
    name("value") generates "user-1"
}

When the whole value object should be fixed, prefer a type rule in shared configuration:

val fiktion = Fiktion {
    type<UserId>() generates UserId("user-1")
}

Skipped types can still be generated with explicit rules:

val fiktion = Fiktion {
    type<PrivateUser>() generates PrivateUser.create("user-1")
}

Gradle Configuration

Test source sets are enabled by default. Main/runtime source sets are opt-in:

fiktion {
    sourceSet("commonMain") {
        enabled.set(true)
    }
}

Project-wide controls are also available:

fiktion {
    // Enable every Kotlin source set.
    enabled.set(true)

    // Disable the default test-source-set behavior.
    testEnabled.set(false)

    sourceSet("jvmTest") {
        enabled.set(true)
    }
}

Java Add-On

Add fiktion-addon-java when tests need common JVM types such as java.time, java.util, java.net, java.nio, java.sql, or java.util.concurrent types:

dependencies {
    testImplementation("dev.s7a:fiktion-addon-java:0.5.1")
}

With the Gradle plugin enabled, add-ons on the compilation classpath are registered automatically before fake<T>() calls:

import java.time.Instant
import java.util.UUID

val instant = fake<Instant>()
val uuid = fake<UUID>()

Add-ons can still be installed explicitly when the compiler plugin is not enabled for that source set:

val fiktion = Fiktion {
    install(JavaFiktionAddon)
}

Arrow Core Add-On

Add fiktion-addon-arrow-core when tests need Arrow Core types such as Option, Either, Ior, NonEmptyList, or NonEmptySet:

dependencies {
    testImplementation("dev.s7a:fiktion-addon-arrow-core:0.5.1")
}

With the Gradle plugin enabled, the add-on is registered automatically before fake<T>() calls:

import arrow.core.Either
import arrow.core.NonEmptyList
import arrow.core.Option

val option = fake<Option<Int>>()
val either = fake<Either<String, Int>>()
val items = fake<NonEmptyList<String>>()

NonEmptyList and NonEmptySet use collection converters with a minimum size of 1. NonEmptySet also follows normal set semantics by default: duplicate generated values collapse, so the final set size can be smaller than FiktionConfig.Collection.size. Use FiktionConfig.Collection.uniqueElementStrategy when exact distinct sizes are required.

It can also be installed explicitly:

val fiktion = Fiktion {
    install(ArrowCoreFiktionAddon)
}

kotlinx-datetime Add-On

Add fiktion-addon-kotlinx-datetime when tests need kotlinx-datetime types such as Instant, LocalDate, LocalTime, , , , , or :

dependencies {
    testImplementation("dev.s7a:fiktion-addon-kotlinx-datetime:0.5.1")
}

With the Gradle plugin enabled, the add-on is registered automatically before fake<T>() calls:

import kotlinx.datetime.LocalDate
import kotlinx.datetime.TimeZone

val date = fake<LocalDate>()
val timeZone = fake<TimeZone>()

It can also be installed explicitly:

val fiktion = Fiktion {
    install(KotlinxDatetimeFiktionAddon)
}

Custom Add-Ons

Add-ons are reusable bundles of rules:

public object CustomFiktionAddon : FiktionAddon {
    override val id: String = "custom"

    override fun install(builder: FiktionAddonBuilder) {
        with(builder) {
            type<Token>() generatesBy {
                Token(value = string(length = 32))
            }

            typeFamily<CustomList<*>>() generatesBy {
                CustomList(List(int(config(FiktionConfig.Collection.size))) { index -> fakeElement(index) })
            }
        }
    }
}

When writing generic collection-like or map-like add-on generators, prefer fakeElement(index), fakeKey(index), and fakeValue(index) in TypeFamilyGenerationContext. These helpers keep element, key, and value target configuration working for users of the add-on.

To make a third-party add-on auto-registerable, include a resource file named META-INF/fiktion/addons in the add-on artifact. Each non-empty line should contain one add-on object class name:

com.example.fiktion.ExampleFiktionAddon

Installed add-ons sit below explicit per-call, instance, and global rules in precedence.

Realistic Data

Fiktion core focuses on object graph generation, rule resolution, and Kotlin metadata. Strict domain data such as names, email addresses, postal addresses, or localized text can come from custom rules, add-ons, or libraries such as Datafaker.

val faker = Faker()

val user = fake<User> {
    User::email generatesBy {
        faker.internet().emailAddress()
    }
}

Development

Run ./gradlew build locally to execute the same JVM, Node.js, Wasm Node.js, and native checks used by CI.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

burst★ 319

cashappUnit testing library facilitates parameterization of tests using enums, specializing test cases for each enum value and combination, enhancing test coverage with minimal code changes.Shared: test, kotlin-compiler-plugin

fakt★ 55

rsicarelliGenerates compile-time type-safe test fakes with zero runtime overhead, no reflection, thread-safe call tracking, smart defaults and compiler-plugin code generation for comprehensive test doubles.Shared: test, kotlin-compiler-plugin

ksrpc★ 15

MonkopediaEnables JSON-like RPCs with simple service declarations, supporting various connection mechanisms. Integrates annotations for service mapping, and provides a flexible environment setup for hosting services.Shared: kotlin-native, kotlin-compiler-plugin

Introspekt★ 9

karmakraftsOffers a positional code API and introspection framework with features like `SourceLocation`, `FunctionInfo`, `ClassInfo`, and `AnnotationInfo` for enhanced introspection and compile-time evaluation.Shared: kotlin-native, kotlin-compiler-plugin

EzHook★ 48

XDMrWuAOP framework enabling method replacement at compile-time through custom hooks. Offers runtime support, original method invocation, and inlining for reduced dependency issues. Supports specific platforms.Shared: kotlin-native, kotlin-compiler-plugin

moko-widgets★ 390

icerockdevEnables declarative UI and application screen management in common code, ensuring compile-time safety and reactive data handling. Facilitates full application implementation from common code, adhering to platform rules.Shared: kotlin-native, kotlin-compiler-plugin