Skip to content

A Java API for Atrium

May 6th, 2025

Atrium is a multi-platform assertion library for Kotlin. During Tegonal's Open Source Week, we worked on a generator based on a Kotlin compiler plugin that produces a Java API, so that Atrium can be used from Java too.


We set ourselves the following goals:

  • The available expectations should be exposed through a type hierarchy, similar to AssertJ
  • Unlike with AssertJ, as little type information as possible should be lost
  • Wherever possible, it should offer the same patterns as the Kotlin fluent API, especially for exceptions/throwables and soft assertions

Here's a small example of how expectations can be written in a Java test using the extension we built:

We didn't manage to open a pull request for Atrium by the end of the week, but we learned a lot that will help if we ever need to use Atrium in Java projects. Right now we don't, as we mainly build our applications in Scala or Kotlin.

We also picked up know-how on building a Kotlin compiler plugin.


Still, we'd like to share some of what we learned in the sections below.


Takeaways – Java API

  1. Providing a complete Java API is awkward, given the lack of strong typing and the existence of «extension functions».
  2. IntelliJ handles Kotlin code called from a Java environment poorly:
    1. It wrongly reports compiler errors involving «functional interfaces» and «wildcard types», both of which are very common in Kotlin bytecode. Here's an example of such a compiler error
    2. IntelliJ missed some compiler errors, especially with self-referencing parameter types.


Takeaways – Kotlin compiler plugin

We think a compiler plugin is a good way to generate code, even though the approach still feels experimental in the following respects:

  • There's no official documentation on kotlinlang.org
  • There are no official example projects with up-to-date dependencies
  • The current de facto standard for testing (https://github.com/tschuchortdev/kotlin-compile-testing) is still based on Kotlin 1.9.24 (e.g. no support for Kotlin 2.x)

Because the tooling integration is poor, we had to fall back on plain debug output when debugging the compiler plugin. Worth knowing: debug output that a compiler plugin writes to the console with println only shows up if the flag ‹kotlin.compiler.execution.strategy=in-process› is set in the relevant Gradle configuration.


What next?

As we don't currently see a direct need for a Java API for Atrium, we won't take this work further. All the changes are published on a feature branch in Atrium, though, and give a good starting point if a concrete need comes up.


You can see all the changes here:

https://github.com/robstoll/atrium/compare/main...feature/java-api