<!-- for main -->

<!-- for a specific release --> <!-- [](https://central.sonatype.com/artifact/ch.tutteli.atrium/atrium-fluent/1.2.0) [](https://joinup.ec.europa.eu/collection/eupl/eupl-text-11-12 "License") [](https://kotlinlang.slack.com/messages/C887ZKGCQ "See invitation link under section FAQ") [](https://github.com/robstoll/atrium/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22 "Ask in slack for help") -->

<img src="https://raw.githubusercontent.com/robstoll/atrium/gh-pages/images/logo.svg?sanitize=true" alt="Atrium" title="Atrium"/>

Atrium is an open-source multiplatform expectation/assertion library for Kotlin with support for JVM, JS and Android. It is designed to support multiple APIs, focuses on helping developers to understand what went wrong and prevents common pitfalls. The project was inspired by AssertJ at first but moved on and provides now more flexibility, features and hints to its users (so to you 😉).

Atrium is designed to be extensible as well as configurable and allows you to extend it with your own expectation functions, customise reporting or even replace core components with your own implementation easily.

See Examples below to get a feel for how you could benefit from Atrium.

---

❗ You are taking a sneak peek at the next version. It could be that some features you find on this page are not released yet.
Please have a look at the README of the corresponding release/git tag. Latest version: README of v1.2.0.

---

Table of Contents

• Installation
  • Sample Projects
• Examples
  • Your First Expectation
  • Define Single Expectations or an Expectation-Group
    • Soft-Expectations
  • Expect an Exception
  • Feature Extractors
    • Property and Method
    • Arbitrary Features
    • Extract Subject
  • Type Expectations
  • Nullable Types
  • Collection Expectations
    • Shortcut Functions
    • Sophisticated Expectation Builders
  • Map Expectations
    • Shortcut Functions
    • Sophisticated Expectation Builders
    • Others
  • Path Expectations
  • Attaching a Reason
  • Integrate other Assertion/Expectation Libraries
  • Data Driven Testing
  • Further Examples
• How is Atrium different from other Expectation/Assertion Libraries
• Write own Expectation Functions
  • Boolean based Expectation Functions
  • Throwable based Expectation Functions
  • Compose Functions
  • Enhanced Reporting
  • Own Sophisticated Expectation Builders
• Use own Expectation Verb
  • Use own Components
• API Styles
• Java Interoperability
• KDoc - Code Documentation
• FAQ
  • My expectation function is not available for subtypes
  • I have problems in conjunction with feature
  • Does Atrium provide something like AssertJ's soft assertion?
  • Are there toContain/toHaveElementsAndAll/None/Any expectation functions for Sequence/Array?
  • Where are the expectation functions for java.io.File?
  • Where are the expectation functions for java.util.Date?
  • Where do I find a list of all available functions?
• Roadmap
• Contributors and contribute
• Sponsors
• License

Installation

Atrium is published to mavenCentral. It has the following minimum requirement:

• Kotlin: 1.4
• JVM: 11
• JS: IR-Backend (LEGACY support was dropped with Atrium 1.2.0)

In case you use Kotlin 1.5 or newer, then regardless of the target platform, you can use the following group and artifactId

build.gradle.kts:

repositories {
    mavenCentral()
}
dependencies {
    testImplementation("ch.tutteli.atrium:atrium-fluent:1.2.0")
}

And in case of an MPP project accordingly:

repositories {
    mavenCentral()
}
kotlin {
    sourceSets {
        val commonTest by getting {
            implementation("ch.tutteli.atrium:atrium-fluent:1.2.0")
        }
        // no need to add it to specific targets such as jvmTest, is done automatically starting with Kotlin 1.5
    }
}

Exchange fluent with infix depending on your taste (see API styles for more information).

That is all, you are all set. Jump to Examples which shows how to use Atrium.

<a name="installation-prior-to-kotlin-1.5"></a>

<details> <summary>I use a version prior to Kotlin 1.5</summary>

In case you use a version prior to Kotlin 1.5, then use the following depending on the target platform:

• common: atrium-fluent
• jvm: atrium-fluent-jvm
• android: atrium-fluent-jvm
• js: atrium-fluent-js

</details>

I have other problems: please take a look at the Sample Projects for further guidance.

Sample Projects

Have a look into the samples folder, it currently contains sample projects for

• js - kotlin-test
• jvm -- junit5
• jvm -- maven
• jvm -- kotest
• jvm -- TestNG
• multiplatform project

Are you using a different runner? A PR would be appreciated 😊.

Examples

We are using the API provided by the bundle module atrium-fluent in the following examples. It provides a pure fluent API for the JVM platform. Have a look at apis/differences.md to see how the infix API looks like, how they differ respectively.

Your First Expectation

See also AnyExpectationSamples for further examples.

We start off with a simple example:

<ex-first>

import ch.tutteli.atrium.api.fluent.en_GB.*
import ch.tutteli.atrium.api.verbs.expect

val x = 10
expect(x).toEqual(9)

↑ _Example ↓ _Output <a name="ex-first"></a>

I expected subject: 10        (kotlin.Int <1234789>)
◆ to equal: 9        (kotlin.Int <1234789>)

</ex-first>

The statement can be read as "I expect x to equal nine" where an equality check is used (for an identity check, you would have to use toBeTheSameInstace). Since this is false, an AssertionError is thrown with a corresponding message as shown in the Output where on the first line the actual subject (10 in the above example) is shown and on following lines which start with, ◆ ... (here only