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

Core assertion and matcher library for Kotest testing framework

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Kotest Assertions Core JVM

Name: tessl/maven-io-kotest--kotest-assertions-core-jvm
Author: tessl

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