How to install Atrium in a Kotlin multiplatform project?

Add the dependency 'ch.tutteli.atrium:atrium-fluent:1.2.0' to your commonTest source set in build.gradle.kts, as shown in the README. For Kotlin 1.5+, it automatically targets platforms, but pre-1.5 requires platform-specific artifacts.

Atrium vs Kotest assertions: which is better?

Atrium focuses on fluent, multiplatform expectations with detailed failure reporting, while Kotest offers a broader testing framework including property-based testing. Atrium is ideal if you need expressive assertions across JVM, JS, and Android.

How to write a custom expectation function in Atrium?

Use the extensibility API to define functions based on boolean checks or throwables. The README provides examples under 'Write own Expectation Functions', such as using _logic.extractFeature for safe feature extraction.

Does Atrium support soft assertions like AssertJ?

Yes, Atrium provides expectation groups via the 'expect' block syntax, evaluating multiple expectations together and reporting all failures, similar to AssertJ's soft assertions, as explained in the soft-expectations section.

How to test exception throwing with Atrium?

Use the 'toThrow' function on a lambda, e.g., 'expect { ... }.toThrow ()'. You can add sub-expectations on exception properties like message, as shown in the exception expectations examples.

What are the minimum Kotlin and JVM versions for Atrium?

Atrium requires Kotlin 1.4 or higher, JVM 11, and the JS IR backend. Support for legacy JS backend was dropped in version 1.2.0, so ensure your project meets these requirements.

Atrium — Kotlin Expectation Library

What is Atrium?

Atrium is a multiplatform expectation library for Kotlin that provides a fluent API for writing assertions in tests. It helps developers write expressive and readable test expectations with detailed failure messages, making it easier to understand why a test failed. The library supports JVM, JS, and Android, and is designed to be extensible, allowing customizations and integrations.

Target Audience

Kotlin developers writing tests for multiplatform projects (JVM, JS, Android) who want expressive assertion syntax and clear failure reporting. It's especially useful for teams adopting Kotlin for cross-platform development.

Value Proposition

Developers choose Atrium for its detailed failure messages, multiplatform support, and extensible design. Unlike other assertion libraries, it offers both fluent and infix APIs, sophisticated collection expectations, and the ability to customize or extend core functionality.

Overview

A multiplatform expectation library for Kotlin

Use Cases

Best For

Writing expressive and readable assertions in Kotlin tests
Multiplatform Kotlin projects targeting JVM, JS, and Android
Tests requiring detailed failure messages to debug issues quickly
Projects needing custom assertion functions or reporting
Data-driven testing with grouped expectations
Testing collections with complex containment or ordering rules

Not Ideal For

Projects stuck on Kotlin versions below 1.4 or JVM below 11, due to Atrium's strict minimum requirements.
Teams writing tests primarily in Java, as nullable type handling and Kotlin interoperability can be cumbersome.
Simple test suites where basic assertion libraries like JUnit 5 or kotlin-test suffice, avoiding Atrium's builder pattern complexity.

Pros & Cons

Pros

Multiplatform Kotlin Support

Works on JVM, JS, and Android with a single codebase, enabling consistent testing across platforms, as stated in the GitHub description and installation guide.

Clear Failure Reporting

Provides structured error messages that show the subject, expected values, and mismatches explicitly, making debugging easier, demonstrated throughout the README examples.

Extensible Architecture

Allows adding custom expectation functions or replacing core components, offering flexibility for advanced use cases, per the project's philosophy and extensibility sections.

Sophisticated Collection Testing

Includes builders for complex containment checks with options like inOrder and inAnyOrder, enabling detailed collection assertions, as shown in the collection expectations examples.

Cons

Steep Learning Curve

The fluent API and builder patterns, while expressive, require significant time to master and can overwhelm new users, evident from the extensive documentation and multiple API styles.

Kotlin Version Lock-in

Requires Kotlin 1.4+ and drops support for legacy JS backends, potentially blocking adoption in projects with older toolchains, as noted in the installation requirements.

Reflection Ambiguity Issues

Users may encounter Kotlin bugs causing ambiguous overloads when using feature extraction with reflection, admitted in the FAQ under 'ambiguity problems', leading to compile-time errors.

Open Source Alternative To

Atrium is an open-source alternative to the following products:

A

AssertJ

AssertJ is a Java library providing fluent assertions for testing, making test code more readable and easier to write.

Atrium

What is Atrium?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Open Source Alternative To

Frequently Asked Questions

Related Projects

Found a gem we're missing?

Atrium

What is Atrium?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Open Source Alternative To

Frequently Asked Questions

Related Projects

Found a gem we're missing?