# Mockito-Kotlin: the small helper layer that makes Mockito read like Kotlin

> A library of helper functions that remove the Kotlin rough edges from Mockito: inline lambda stubbing, argument matchers that accept nulls, and a test suite pinned to its own module so it can run on several Kotlin versions at once.

**mockito/mockito-kotlin** — Using Mockito with Kotlin

- Repository: https://github.com/mockito/mockito-kotlin
- Stars: 3,160 · Forks: 208
- Language: Kotlin
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/mockito-mockito-kotlin

## A DSL over Mockito, not a replacement for it

The README states the scope in one line: a small library that provides helper functions to work with Mockito in Kotlin. That is the whole product. There is no engine here, no byte-code agent, no matching algorithm. Every mock still comes from Mockito itself, and every verification still goes through Mockito's own machinery.

What changes is the call syntax. The README's example stubs a method inside a lambda passed to `mock`, and returns a value from that lambda with an infix function:

```kotlin
@Test
fun doAction_doesSomething(){
  val mock = mock<MyClass> {
    on { getText() } doReturn "text"
  }
  val classUnderTest = ClassUnderTest(mock)
  classUnderTest.doAction()
  verify(mock).doSomething(any())
}
```

That block is worth reading closely, because every line is solving a Kotlin-specific problem. The `on { getText() }` lambda exists so the stubbed call can be typed: inside it, `getText()` is resolved by the compiler rather than by a runtime matcher. The `doReturn "text"` form is not the Java-style `when(...).thenReturn(...)` chain, which reads awkwardly in Kotlin because every argument must be an expression, not a statement. And `any()` is used inside `verify` without a preceding `any()` capture call to store the matcher, because the helper handles that for you.

The result is that the Given, When, Then blocks in the example are recognisable to anyone who has written a Java Mockito test, while the Kotlin around them stays idiomatic. That is the entire pitch, and it is a small enough surface that you can learn the library in an afternoon.

## Installing from Maven Central in Groovy and Kotlin DSL

Mockito-Kotlin ships to Maven Central under the group `org.mockito.kotlin`, and the artifact name matches the repository name. The README gives two snippets because the build file syntax differs between Gradle's Groovy DSL and its Kotlin DSL.

```groovy
testImplementation "org.mockito.kotlin:mockito-kotlin:x.x.x"
```

```kotlin
testImplementation("org.mockito.kotlin:mockito-kotlin:x.x.x")
```

Replace the placeholder with a concrete version before the build will resolve. The README keeps `x.x.x` deliberately rather than pinning a number, which tells you the maintainers expect you to choose, and the versioning note says the project roughly follows SEMVER, so a major digit change is the signal that something moved.

Two practical points are worth knowing before you add this. First, the dependency is a `testImplementation` scope, which is correct: the library is compile-time sugar over Mockito and has no business in your production artifact. Second, this library assumes Mockito is already on your test classpath, either directly or through a test framework that brings it in. Nothing in the README adds Mockito for you, so a project without it will fail at compile time with unresolved references rather than at runtime.

The README does not document a snapshot repository, a Gradle plugin, or an Android-specific artifact. It points Android users at a separate Wiki page instead, which is the signal that mobile support needs more explanation than a version string.

## Why the tests live in their own Gradle module

The most interesting structural decision in this repository has nothing to do with mocking. The README explains that the test suite sits in a separate `tests` module rather than inside the library module, and gives the reason: it allows running the tests using several Kotlin versions whilst still keeping the base module at a recent version.

That separation solves a real problem. A library like this one is consumed by projects on different Kotlin releases, and helper functions that compile against one stdlib version can break against another. By keeping the tests out of the published module, the build can point the same test suite at a different compiler and stdlib without touching the library's own build configuration.

The repository tree shows how much scaffolding that requires. Alongside the `mockito-kotlin/` module you will find `tests/`, plus `build-logic/` for convention plugins and Gradle build logic, `benchmarks/` for performance work, `no-coroutine-tests/` as a separate verification target, and the usual `settings.gradle`, `build.gradle` and `gradle.properties` at the root. A wrapper is committed, with both `gradlew` and `gradlew.bat`, so builds do not depend on a locally installed Gradle.

Running a single Kotlin version locally takes one extra property:

```bash
./gradlew check -PtestKotlinVersion=1.2.3
```

The README is clear about expectations here: it is usually enough to test with the default Kotlin versions, because CI already covers the matrix. The property exists for the case where you need to reproduce a version-specific failure on your own machine.

## What version 6.4.0 added, published 2026-09-23

The release notes for v6.4.0 list five pull requests, which is a small and readable change set. `spyObject` arrives in pull request 593, giving the library a Kotlin-shaped entry point for creating spies rather than only mocks. That matters because `spy` is the other half of the framework's usage: a mock has no real behaviour, a spy calls through to the real implementation while letting you stub and verify individual calls.

The second feature is InOrder verification for static mocks, in pull request 592. Mockito's `MockedStatic` support lets you stub static methods, and verifying the order in which two static calls happened was previously more awkward than verifying instance calls. Adding the ordered form closes a gap that showed up once people started using static mocking with this library.

The remaining three entries are maintenance rather than surface area: a README update, benchmarks comparing mockito-kotlin against MockK, and an upgrade to Gradle 9.4.1. The benchmark comparison is the one worth noting, because it tells you the maintainers consider MockK a real alternative rather than an inconvenience, and they thought the trade-off was worth measuring.

Version 6.3.0 and 2.8.4-style tags do not appear in the same form here, so treat the `v` prefix as this project's convention. The project was created and developed by nhaarman and later integrated into the official Mockito GitHub organization, and the README credits Niek for the original idea. The last push was on 2026-09-23 and the repository is not archived, so it is being worked on.

## What the README deliberately does not document

Read this library's documentation as a front door rather than a reference. The README is under 2,400 characters. It covers what the library is, how to install it, one test example, where the Wiki lives, an Android Support pointer, three Gradle commands, a versioning note, a testing note, and acknowledgements. That is the entire document.

Everything substantial is delegated. The README says that for more info and samples, see the Wiki, and links Android users to a dedicated Android Support page in the same Wiki. So the questions you actually need answered, like which matcher variants exist, how argument captors work here, and what has to change for Android, are answered outside this repository.

The same applies to release process. A `RELEASING.md` in the tree holds the publishing procedure, and `.github/` holds the workflows, but neither is summarised in the README. If you want to know how a release gets cut, that file is where to look.

This is a reasonable division of labour for a library this narrow, and it is worth being honest about the tradeoff: adopting it means following two links to learn the parts that will actually come up. A new user reading only the README will be able to write the example test and little more.

## Benchmarks, licence, and how the project fits with Mockito

Two things make this project easier to place. The first is the licence. GitHub shows MIT for the licence, and there is a `LICENSE` file at the repository root, so there is no ambiguity to resolve here: add it to a commercial or closed-source test suite without a copyleft obligation.

The second is scope discipline. Mockito itself lives in the `mockito` organisation, which is where this repository now sits too, and the description in the repository metadata is simply `Using Mockito with Kotlin`. Mocking behaviour, matching semantics, and the inline mock maker all remain Mockito's responsibility. If a mock behaves unexpectedly, the answer is usually in Mockito's documentation or in your own stubbing, not here.

The benchmarks directory is the one place where this project argues a case rather than wrapping someone else's. The comparison against MockK added in 6.4.0 matters because MockK takes a different approach to the same problem, intercepting calls at the Kotlin level rather than layering helpers on top of a Java framework. Two reasonable readings follow: if you are starting a new Kotlin test suite, the choice between them is worth benchmarking on your own code. If your suite is already Java-flavoured Mockito with a mixed module, adding this library is the cheaper path.

The `no-coroutine-tests/` module is a second boundary marker. Coroutine-heavy testing needs its own conventions, and this repository keeps that verification separate rather than folding it into the main helper API.

## Conclusion

Mockito-Kotlin earns its place by being narrow. It does not replace Mockito, it does not add a second mocking framework, and it does not try to solve coroutine testing. It removes the specific friction that Kotlin developers hit when calling Java APIs: lambdas where Mockito wants an instance method, and matchers where the Kotlin type system says a value cannot be null. Add one dependency to your test configuration and your mocks start looking like the surrounding code. Version 6.4.0, published on 2026-09-23, is a good point to pin, since it added `spyObject` and InOrder verification on static mocks. Check the project's Wiki for the API surface the README does not list, and read the Android Support page before assuming it works unchanged on a device.

## FAQ

### What is Mockito vs JUnit?

JUnit is a test framework that runs tests and provides assertions. Mockito creates stand-in objects so you can control what a collaborator returns and then verify that it was called. This repository is not a test framework at all: it is a set of Kotlin helper functions layered on top of Mockito, published separately as `org.mockito.kotlin:mockito-kotlin`.

### Where do I add the Mockito-Kotlin dependency?

On Maven Central, as `testImplementation "org.mockito.kotlin:mockito-kotlin:x.x.x"` in Groovy DSL or `testImplementation("org.mockito.kotlin:mockito-kotlin:x.x.x")` in Kotlin DSL. Replace the placeholder with a real version. Mockito itself also has to be on your test classpath, since this library does not add it.

### Does Mockito-Kotlin work on Android?

The README points Android users to a dedicated Android Support page in the project Wiki rather than documenting it inline. No separate Android artifact or plugin is mentioned, so read that page before assuming the library behaves the same on a device as it does on the JVM.

### How do I test against a different Kotlin version locally?

Pass the Gradle property `-PtestKotlinVersion=1.2.3` when running the checks, for example `./gradlew check -PtestKotlinVersion=1.2.3`. The test suite lives in its own `tests` module specifically so several Kotlin versions can be exercised while the library module stays on a recent one, and CI already runs the matrix.

## Sources

- [Issues](https://github.com/mockito/mockito-kotlin/issues)
- [License: MIT](https://github.com/mockito/mockito-kotlin/blob/main/LICENSE)
- [mockito/mockito-kotlin on GitHub](https://github.com/mockito/mockito-kotlin)
- [README](https://github.com/mockito/mockito-kotlin/blob/main/README.md)
- [Releases](https://github.com/mockito/mockito-kotlin/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mockito-mockito-kotlin