Skip to main content

Setup

Gradle plugin​

The recommended way to work with Mokkery is to use the Mokkery Gradle plugin. If you can’t use it, see the alternative setups section.

  1. Apply Gradle plugin:
plugins {
    kotlin("multiplatform") version "2.3.10" // ...or any other Kotlin plugin
    id("dev.mokkery") version "3.2.0"
}

  1. Ensure that your Mokkery version is compatible with your Kotlin version. Refer to the compatibility section.

  2. Check the source sets section to make sure that Mokkery is properly applied in your project.

  3. Check the targets section to make sure that all targets from you multiplatform project are supported.

  4. At this point everything should be fine. In case of Gradle being unable to find dependencies, check missing repositories.

// for runtime dependencies
repositories {
    mavenCentral()
}
// for plugin dependencies
pluginManagement {
    repositories {
        gradlePluginPortal() // required only before Mokkery 2.3.0
        mavenCentral()
    }
}

Convention plugins​

tip

Since Mokkery 2.3.0, it's no longer required to add this repository, because Mokkery Gradle plugin is also published to Maven Central.

For those using convention plugins, make sure that the dependencies configuration includes the path to the required repository, which can be added using gradlePluginPortal().

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        // required to download Mokkery Gradle plugin before version 2.3.0
        gradlePluginPortal()
    }
}

Once the required repository is connected, you will be able to successfully download the Mokkery plugin dependency.

dependencies {
    implementation("dev.mokkery:mokkery-gradle:$mokkeryVersion")
}

Source sets​

By default, Mokkery is applied to all Kotlin source sets whose names either contain the word 'Test' or begin with 'test'. As a result, Mokkery is correctly applied to the default test source sets in Android, JVM, or Multiplatform projects. However, this default behavior might need adjustments if any of your main custom source sets contain the word 'Test'.

warning

Before version 2.1.0, Mokkery was applied by default only to source sets whose names contained the phrase 'Test'. In result it was not applied in JVM projects.

Apply for main​

If you need to use Mokkery in the main source set (e.g., when mocks need to be extracted to a separate subproject), use the ApplicationRule.All:

mokkery {
   rule.set(ApplicationRule.All)
}

This applies Mokkery to all source sets within the current subproject.

Customization​

If neither ApplicationRule.AllTests nor ApplicationRule.All meets your requirements, you can manually specify the source sets. The following options are available:

  • ApplicationRule.Listed("fooMain", "barMain") - applies Mokkery only to the explicitly listed source sets.
  • ApplicationRule.MatchesName(Regex(".+Main")) - applies Mokkery to all source sets whose names match the given regular expression.
  • Provide a custom rule to suit your needs.

When selecting source sets manually, ensure that you include all source sets within a subtree. The Mokkery plugin does not automatically detect dependencies between source sets, as these dependencies may not always be present.

Targets​

✅ Supported:

You can refer to this file for more details.

Compatibility​

warning

Mokkery 2.* and 3.* versions aren't tied to specific Kotlin 2.* versions, assuming the compiler API will stay stable. However, breaking changes can cause compile-time errors that require updating Mokkery. Track compiler API stability here.

Mokkery versionSupported Kotlin versions
3.1.0 - 3.2.02.3.0 - 2.3.10
3.0.02.2.0 - 2.2.21
2.10.0 - 2.10.22.2.0 - 2.2.21
2.9.02.2.0 - 2.2.10
2.8.02.1.20 - 2.1.21
2.7.2 - 2.7.32.1.0 - 2.1.21
2.6.0 - 2.7.12.1.0 - 2.1.10
2.3.0 - 2.5.12.0.0 - 2.0.21
2.0.0 – 2.2.02.0.0 - 2.0.10

Alternative setups​

Since version 3.2.0, it should be easier to use Mokkery without the Gradle plugin.

In general, you should follow these steps:

  1. Add a compatible compiler plugin artifact. For the command-line compiler, use -XPlugin=path/to/mokkery-plugin.jar flag.
  2. Add the runtime dependency with the same version adequately for your platform. For the command-line Kotlin/JVM compiler, add -classpath with the mokkery-runtime-jvm and its dependency JARs.
  3. Optionally, specify compiler plugin options. For the command-line compiler, use -P plugin:dev.mokkery:option=value
info

Before Mokkery 3.2.0 it should also be possible to use, but it might be less convenient. Version 3.2.0 introduces:

  • Mokkery plugin is published as a fat JAR
  • Improved compiler options syntax

Compiler plugin options​

When using other build systems or the command-line compiler, additional Mokkery configuration can be specified via compiler plugin options. Available options include:

  • defaultVerifyMode - verify mode expression, e.g. inRange(2..5), exhaustive.
  • defaultMockMode - name of the mock mode, e.g. strict, autoUnit.
  • ignoreInlineMembers - true or false.
  • ignoreFinalMembers - true or false.
  • enableFirDiagnostics - true or false.
  • stubs.allowClassInheritance - true or false.
  • stubs.allowConcreteClassInstantiation - true or false.
  • annotations.copyToMock - annotation selector expression, e.g. all - named("annotation.A"|"annotation.B"). Note that usage of , was replaced by |. Mokkery can parse both, but currently commas must not be a part of a plugin option.)