varabyte / truthish

A Kotlin multiplatform unit testing library inspired by / similar to Google Truth.

Truthish

A testing API inspired by Google Truth but rewritten in Kotlin from the ground up, so it can be used in Kotlin multiplatform projects.

For example, you can write assertThat checks in tests like this:

import com.varabyte.truthish.*

fun isEven(num: Int) = (num % 2) == 0
fun square(num: Int) = (num * num)

@Test
fun testEvenOdd() {
    assertThat(isEven(1234)).isTrue()
    assertThat(isEven(1235)).isFalse()
}

@Test
fun testSum() {
    val nums = listOf(1, 2, 3, 4, 5)
    assertThat(nums.sum()).isEqualTo(15)
}

@Test
fun testMap() {
    assertThat(listOf(1, 2, 3, 4, 5).map { square(it) })
        .containsExactly(1, 4, 9, 16, 25)
        .inOrder()
}

@Test
fun customMessage() {
    assertWithMessage("Unexpected list size")
        .that(listOf(1, 2, 3, 4, 5)).hasSize(5)
}

@Test
fun testDivideByZeroException() {
    val ex = assertThrows<ArithmeticException> {
        10 / 0
    }
    assertThat(ex.message).isEqualTo("/ by zero")
}

You can read the Google Truth documentation for why they believe their fluent approach to assertions is both more readable and produces cleaner error messages, but let's break one of the tests above to see a specific example error message:

@Test
fun testMapButIntentionallyBroken() {
    assertThat(listOf(1, 2, 3, 4, 5).map { square(it) })
        .containsExactly(1, 4, 9, 15, 26) // <-- Ooops, messed up 16 and 25 here
        .inOrder()
}

Output:

A collection did not contain element(s)

Expected exactly all elements from: [ 1, 4, 9, 15, 26 ]
But was                           : [ 1, 4, 9, 16, 25 ]
Missing                           : [ 15, 26 ]
Extraneous                        : [ 16, 25 ]

Using Truthish in Your Project

Multiplatform

To use Truthish in your multiplatform application, declare the following dependencies:

// build.gradle.kts
// Multiplatform

repositories {
    mavenCentral()
}

kotlin {
    jvm()
    js(IR) {
        browser()
    }

    linuxX64()
    macosArm64() // Mac M1+
    macosX64() // Mac Intel
    mingwX64() // Windows
    iosX64() // iOS Intel
    iosArm64() // iOS M1+
    iosSimulatorArm64()
    android()

    sourceSets {
        commonTest.dependencies {
            implementation("com.varabyte.truthish:truthish:1.0.1")
            implementation(kotlin("test"))
        }
    }
}

Single platform

You can also use Truthish in non-multiplatform projects as well:

JVM

// build.gradle.kts

repositories {
    mavenCentral()
}

dependencies {
    // ...

    testImplementation(kotlin("test"))
    testImplementation("com.varabyte.truthish:truthish:1.0.1")
}

Android

// build.gradle.kts

repositories {
    mavenCentral()
}

android { /* ... */ }

dependencies {
    // ...

    // If used in tests that are run on the host (i.e. your dev machine)
    testImplementation("com.varabyte.truthish:truthish:1.0.1")

    // If used in tests that are run on the device
    androidTestImplementation("com.varabyte.truthish:truthish:1.0.1")
}

truthish's Issues

Instance check contract

Hi,

Please add a contract such that if isInstanceOf succeeded, there'd be no need to cast the object for additional assertions.

Thanks.

Feature Request: Support assertThrows with a message

Currently, all the assertThat methods have assertWithMessage versions.

assertThrows is kind of special and I don't think we can do quite the same thing, but there should be some way to add support for a custom message.

I had a loop in some of my code that tested several inputs against an assertThrows check, but when one of them failed, I didn't have any idea of which one. It would have been nice to do something like

for (badInput in listOf(...)) {
   assertThrows<...>("Testing exceptions for input case $badInput...") { ... }
}

Unexpected inOrder success that should be failing

It seems like having a duplicate value in a list can confuse the inOrder asserter

    @Test
    fun uhOh() {
        assertThat(listOf("3", "2", "1", "30", "20", "10", "20")).containsExactly("3", "2", "1", "30", "20", "20", "10").inOrder()
    }

Sequence test is sometimes not getting consumed

Sequences are funky -- running foreach on it twice ends up consuming the sequence.

Everywhere we work with iterables, we probably need to convert them into lists first, e.g. containsExactly

Add support for Android / iOS targets

Technically shouldn't be challenging but I need to spend time figuring out how to set up the CI to build them.