or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

collections.mdconcurrency.mdcore-dsl.mddatetime.mdfilesystem.mdindex.mdnondeterministic.mdprimitives.mdreflection.mdresult.mdstrings.mdthrowable.mdtuples.mdtypes.md
tile.json

tessl/maven-io-kotest--kotest-assertions-core-jvm

Core assertion and matcher library for Kotest testing framework

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.kotest/kotest-assertions-core-jvm@5.9.x

To install, run

npx @tessl/cli install tessl/maven-io-kotest--kotest-assertions-core-jvm@5.9.0

index.mddocs/

Kotest Assertions Core JVM

Kotest Assertions Core JVM provides comprehensive testing assertion and matcher functionality for the Kotest testing framework. It offers a fluent DSL with type-safe assertions for Kotlin multiplatform projects, with specific JVM enhancements for files, reflection, concurrency, and date/time operations.

Package Information

  • Package Name: io.kotest:kotest-assertions-core-jvm
  • Package Type: maven
  • Language: Kotlin
  • Installation: implementation("io.kotest:kotest-assertions-core-jvm:5.9.1")

Core Imports

import io.kotest.matchers.shouldBe
import io.kotest.matchers.shouldNotBe
import io.kotest.matchers.should
import io.kotest.matchers.shouldNot

For specific matcher types:

import io.kotest.matchers.string.*
import io.kotest.matchers.collections.*
import io.kotest.matchers.ints.*
import io.kotest.assertions.nondeterministic.eventually

Basic Usage

import io.kotest.matchers.shouldBe
import io.kotest.matchers.collections.shouldContain
import io.kotest.matchers.string.shouldStartWith
import io.kotest.assertions.nondeterministic.eventually

// Basic assertions using shouldBe
val result = "Hello World"
result shouldBe "Hello World"
result.length shouldBe 11

// Collection assertions
val numbers = listOf(1, 2, 3, 4, 5)
numbers shouldContain 3
numbers.size shouldBe 5

// String assertions
result shouldStartWith "Hello"

// Nondeterministic testing
eventually {
    // Code that might fail initially but should eventually succeed
    remoteService.isHealthy() shouldBe true
}

Architecture

Kotest Assertions is built around several key components:

  • Core DSL: Fluent assertion syntax using infix functions (shouldBe, shouldNotBe, should, shouldNot)
  • Matcher Interface: Matcher<T> abstraction that enables composable and reusable assertion logic
  • Type-Safe API: Full Kotlin type safety with extensive support for nullable types
  • Cross-Platform: Common implementations for all Kotlin targets with JVM-specific extensions
  • Nondeterministic Testing: Support for eventual consistency and time-based assertions
  • Extensible Design: Easy creation of custom matchers and assertion extensions

Capabilities

Core Assertion DSL

Primary assertion functions and matcher infrastructure that form the foundation of all other matchers.

infix fun <T, U : T> T.shouldBe(expected: U?): T
infix fun <T> T.shouldNotBe(any: Any?): T
infix fun <T> T.should(matcher: Matcher<T>): T
infix fun <T> T.shouldNot(matcher: Matcher<T>): T

interface Matcher<T> {
    fun test(value: T): MatcherResult
    infix fun <U> contramap(f: (U) -> T): Matcher<U>
    fun invert(): Matcher<T>
}

interface MatcherResult {
    fun passed(): Boolean
    fun failureMessage(): String
    fun negatedFailureMessage(): String
}

Core DSL

Nondeterministic Testing

Support for testing asynchronous and eventually consistent systems with configurable retry strategies.

suspend fun <T> eventually(test: suspend () -> T): T
suspend fun <T> eventually(duration: Duration, test: suspend () -> T): T
suspend fun <T> eventually(config: EventuallyConfiguration, test: suspend () -> T): T
suspend fun <T> continually(test: suspend () -> T): T
suspend fun <T> until(test: suspend () -> T): T

data class EventuallyConfiguration(
    val duration: Duration,
    val interval: Duration,
    val initialDelay: Duration,
    val listener: EventuallyListener
)

Nondeterministic Testing

Primitive Type Matchers

Comprehensive matchers for all Kotlin primitive types including numeric comparisons, ranges, and type-specific validations.

// Boolean matchers
fun Boolean.shouldBeTrue(): Boolean
fun Boolean.shouldBeFalse(): Boolean

// Integer matchers
fun Int.shouldBeBetween(a: Int, b: Int): Int
infix fun Int.shouldBeInRange(range: IntRange): Int
fun Int.shouldBeWithinPercentageOf(other: Int, percentage: Double): Int

// String content matchers
fun String?.shouldContainOnlyDigits(): String?
fun String?.shouldBeEmpty(): String?
fun String?.shouldBeBlank(): String?

Primitive Matchers

String Matchers

Extensive string validation including content checks, pattern matching, case sensitivity, and multi-line operations.

infix fun String?.shouldContainOnlyOnce(substr: String): String?
fun String?.shouldStartWith(prefix: String): String?
fun String?.shouldEndWith(suffix: String): String?
fun String?.shouldMatch(regex: Regex): String?
fun String?.shouldHaveLength(length: Int): String?

String Matchers

Collection Matchers

Comprehensive collection assertions for lists, sets, maps, and sequences including element access, ordering, uniqueness, and containment.

fun <T> List<T>.shouldHaveElementAt(index: Int, element: T): List<T>
infix fun <T> Collection<T>.shouldExist(p: (T) -> Boolean): Collection<T>
fun <T> List<T>.shouldMatchInOrder(vararg assertions: (T) -> Unit): List<T>
fun <T> Collection<T>.shouldContainAnyOf(vararg ts: T): Collection<T>
fun <T> Collection<T>.shouldBeEmpty(): Collection<T>
fun <T> Collection<T>.shouldHaveSize(size: Int): Collection<T>

Collection Matchers

JVM File System

File system operations including existence checks, permissions, content validation, and directory structure comparisons.

fun File.shouldExist(): File
fun File.shouldBeADirectory(): File
fun File.shouldBeAFile(): File
fun File.shouldBeEmpty(): File
infix fun File.shouldHaveFileSize(size: Long): File
infix fun File.shouldContainFile(name: String): File
fun File.shouldBeReadable(): File
infix fun File.shouldHaveSameStructureAs(file: File): File

File System Matchers

JVM Reflection

Reflection-based matchers for classes, annotations, properties, and method validation.

fun KClass<*>.shouldHaveAnnotations(): KClass<*>
infix fun KClass<*>.shouldHaveAnnotations(count: Int): KClass<*>
inline fun <reified T : Annotation> KClass<*>.shouldBeAnnotatedWith(
    noinline block: (T) -> Unit = {}
): KClass<*>

Reflection Matchers

JVM Date and Time

Comprehensive date and time assertions for Java time API including temporal comparisons and duration validation.

infix fun LocalDate.shouldBeBefore(other: LocalDate): LocalDate
infix fun LocalDateTime.shouldBeAfter(other: LocalDateTime): LocalDateTime
fun LocalDate.shouldBeToday(): LocalDate
fun Instant.shouldBeWithin(duration: Duration, other: Instant): Instant

Date and Time Matchers

JVM Concurrency

Testing support for concurrent operations including futures, atomic types, and thread-safe collections.

fun <T> CompletableFuture<T>.shouldCompleteWithin(duration: Duration): CompletableFuture<T>
fun <T> AtomicReference<T>.shouldHaveValue(expected: T): AtomicReference<T>
suspend fun <T> Channel<T>.shouldReceiveWithin(duration: Duration): T

Concurrency Matchers

Result Type Validation

Comprehensive testing support for Kotlin's Result<T> type, enabling precise validation of both successful values and failure exceptions.

fun <T> Result<T>.shouldBeSuccess(): T
infix fun <T> Result<T>.shouldBeSuccess(expected: T): T
infix fun <T> Result<T>.shouldBeSuccess(block: ((T) -> Unit)): T
fun Result<*>.shouldBeFailure(): Throwable
inline fun <reified T : Throwable> Result<*>.shouldBeFailure(): T

Result Matchers

Exception and Error Testing

Comprehensive throwable and exception validation including message checks, cause analysis, and stack trace validation.

infix fun Throwable.shouldHaveMessage(message: String): Throwable
infix fun Throwable.shouldHaveMessage(message: Regex): Throwable
fun Throwable.shouldHaveCause(block: (Throwable) -> Unit = {}): Throwable
inline fun <reified T : Throwable> Throwable.shouldHaveCauseInstanceOf(): Throwable
infix fun Throwable.shouldHaveStackTraceContaining(substr: String): Throwable

Throwable Matchers

Tuple Validation

Validation matchers for Kotlin's Pair and Triple tuple types, enabling precise assertion of individual components.

fun <A> Pair<A, *>.shouldHaveFirst(a: A): Pair<A, *>
fun <B> Pair<*, B>.shouldHaveSecond(b: B): Pair<*, B>
fun <A> Triple<A, *, *>.shouldHaveFirst(a: A): Triple<A, *, *>
fun <B> Triple<*, B, *>.shouldHaveSecond(b: B): Triple<*, B, *>
fun <C> Triple<*, *, C>.shouldHaveThird(c: C): Triple<*, *, C>

Tuple Matchers

Type System Validation

Comprehensive type validation including instance checking, exact type matching, and reference equality testing.

inline fun <reified T : Any> Any?.shouldBeInstanceOf(): T
inline fun <reified T : Any> Any?.shouldBeTypeOf(): T
infix fun Any?.shouldBeSameInstanceAs(ref: Any?): Any?
inline fun <reified T : Any> Any?.shouldNotBeInstanceOf(): Any?

Type System Matchers

Types

interface Matcher<T> {
    fun test(value: T): MatcherResult
    infix fun <U> contramap(f: (U) -> T): Matcher<U>
    fun invert(): Matcher<T>
}

interface MatcherResult {
    fun passed(): Boolean
    fun failureMessage(): String
    fun negatedFailureMessage(): String
}

interface ComparableMatcherResult : MatcherResult {
    fun actual(): String
    fun expected(): String
}

interface EqualityMatcherResult : MatcherResult {
    fun actual(): Any?
    fun expected(): Any?
}

data class EventuallyConfiguration(
    val duration: Duration = 5.seconds,
    val interval: Duration = 25.milliseconds,
    val initialDelay: Duration = Duration.ZERO,
    val listener: EventuallyListener = NoopEventuallyListener
)

typealias EventuallyListener = suspend (Int, Throwable) -> Unit