README.md

xemantic-kotlin-test

Kotlin multiplatform testing library providing power-assert compatible DSL and assertions

Why?

I am mostly using kotest library for writing test assertions in my projects. When power-assert became the official Kotlin compiler plugin, I also realized that most of the kotest assertions can be replaced with something which suits my needs much better. Instead of writing:

x shouldBeGreaterThanOrEqualTo 42

I could write:

assert(x >= 42)

Next to this, I am quite often asserting the state of hierarchical data structures, therefore I came up with such a syntax:

message should {
  have(id == 42)
  have(content.size == 2)
  content[0] should {
    be<Text>()
    have(type == "text")
    have("Hello" in text)
  }
  content[1] should {
    be<Image>()
    have(type == "image")
    have(width >= 800)
    have(height >= 600)
    mediaType should {
      have(type == "image/png")
    }
  }
}

Now, if the image mediaType.type is not PNG, it will show:

Message(id=42, content=[Text(text=Hello there), Image(path=image.png, width=1024, height=768, mediaType=MediaType(type=image/jpeg))])
 containing:
Image(path=image.png, width=1024, height=768, mediaType=MediaType(type=image/jpeg))
 containing:
MediaType(type=image/jpeg)
 should:
have(type == "image/png")
     |    |
     |    false
     image/jpeg

Usage

Setting up Gradle

Setting up Gradle for Kotlin Multiplatform project

In your build.gradle.kts:

plugins {
  kotlin("multiplatform") version "2.1.0"
  kotlin("plugin.power-assert") version "2.1.0" // replace with the latest kotlin version
}

kotlin {
  
  sourceSets {
    
    commonTest {
      depencencies {
        implementation("com.xemantic.kotlin:xemantic-kotlin-test:1.0")
      }
    }

  }
}

powerAssert {
  functions = listOf(
    "com.xemantic.kotlin.test.have"
  )
}

Setting up Gradle for Kotlin JVM project

In your build.gradle.kts:

plugins {
  kotlin("jvm") version "2.1.0"
  kotlin("plugin.power-assert") version "2.1.0" // replace with the latest kotlin version
}

dependencies {
  testImplementation("com.xemantic.kotlin:xemantic-kotlin-test:1.0")
}

powerAssert {
  functions = listOf(
    "com.xemantic.kotlin.test.have"
  )
}

Basic Assertions

assert(2 + 2 == 4)

Note

The assert function in Kotlin stdlib is providing assert only for JVM and Native out of all the Kotlin multiplatform targets. The multiplatform assert function can be imported from com.xemantic.kotlin.test.assert

Asserting object properties

The library introduces the should infix function, which allows you to chain assertions on an object:

someObject should {
  // assertions go here
}

Type Assertions

You can assert the type of object using the be function:

someObject should {
  be<ExpectedType>()
}

Tip

After calling be function with expected type, all the subsequent calls within should {} will have access to the properties of the expected type, like if this, representing someObject, was cast to the expected type.

Condition Assertions

Use the have function to assert conditions:

someObject should {
  have(someProperty == expectedValue)
}

Nested Assertions

You can nest assertions for complex objects:

complexObject should {
  have(property1 == expectedValue1)
  nestedObject should {
    have(nestedProperty == expectedValue2)
  }
}

Development

Clone this project, and then run:

./gradlew build