0
# Kotest Assertions Core JVM
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: io.kotest:kotest-assertions-core-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: `implementation("io.kotest:kotest-assertions-core-jvm:5.9.1")`
10

11
## Core Imports
12

13
```kotlin
14
import io.kotest.matchers.shouldBe
15
import io.kotest.matchers.shouldNotBe
16
import io.kotest.matchers.should
17
import io.kotest.matchers.shouldNot
18
```
19

20
For specific matcher types:
21

22
```kotlin
23
import io.kotest.matchers.string.*
24
import io.kotest.matchers.collections.*
25
import io.kotest.matchers.ints.*
26
import io.kotest.assertions.nondeterministic.eventually
27
```
28

29
## Basic Usage
30

31
```kotlin
32
import io.kotest.matchers.shouldBe
33
import io.kotest.matchers.collections.shouldContain
34
import io.kotest.matchers.string.shouldStartWith
35
import io.kotest.assertions.nondeterministic.eventually
36

37
// Basic assertions using shouldBe
38
val result = "Hello World"
39
result shouldBe "Hello World"
40
result.length shouldBe 11
41

42
// Collection assertions
43
val numbers = listOf(1, 2, 3, 4, 5)
44
numbers shouldContain 3
45
numbers.size shouldBe 5
46

47
// String assertions
48
result shouldStartWith "Hello"
49

50
// Nondeterministic testing
51
eventually {
52
    // Code that might fail initially but should eventually succeed
53
    remoteService.isHealthy() shouldBe true
54
}
55
```
56

57
## Architecture
58

59
Kotest Assertions is built around several key components:
60

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

68
## Capabilities
69

70
### Core Assertion DSL
71

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

74
```kotlin { .api }
75
infix fun <T, U : T> T.shouldBe(expected: U?): T
76
infix fun <T> T.shouldNotBe(any: Any?): T
77
infix fun <T> T.should(matcher: Matcher<T>): T
78
infix fun <T> T.shouldNot(matcher: Matcher<T>): T
79

80
interface Matcher<T> {
81
    fun test(value: T): MatcherResult
82
    infix fun <U> contramap(f: (U) -> T): Matcher<U>
83
    fun invert(): Matcher<T>
84
}
85

86
interface MatcherResult {
87
    fun passed(): Boolean
88
    fun failureMessage(): String
89
    fun negatedFailureMessage(): String
90
}
91
```
92

93
[Core DSL](./core-dsl.md)
94

95
### Nondeterministic Testing
96

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

99
```kotlin { .api }
100
suspend fun <T> eventually(test: suspend () -> T): T
101
suspend fun <T> eventually(duration: Duration, test: suspend () -> T): T
102
suspend fun <T> eventually(config: EventuallyConfiguration, test: suspend () -> T): T
103
suspend fun <T> continually(test: suspend () -> T): T
104
suspend fun <T> until(test: suspend () -> T): T
105

106
data class EventuallyConfiguration(
107
    val duration: Duration,
108
    val interval: Duration,
109
    val initialDelay: Duration,
110
    val listener: EventuallyListener
111
)
112
```
113

114
[Nondeterministic Testing](./nondeterministic.md)
115

116
### Primitive Type Matchers
117

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

120
```kotlin { .api }
121
// Boolean matchers
122
fun Boolean.shouldBeTrue(): Boolean
123
fun Boolean.shouldBeFalse(): Boolean
124

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

130
// String content matchers
131
fun String?.shouldContainOnlyDigits(): String?
132
fun String?.shouldBeEmpty(): String?
133
fun String?.shouldBeBlank(): String?
134
```
135

136
[Primitive Matchers](./primitives.md)
137

138
### String Matchers
139

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

142
```kotlin { .api }
143
infix fun String?.shouldContainOnlyOnce(substr: String): String?
144
fun String?.shouldStartWith(prefix: String): String?
145
fun String?.shouldEndWith(suffix: String): String?
146
fun String?.shouldMatch(regex: Regex): String?
147
fun String?.shouldHaveLength(length: Int): String?
148
```
149

150
[String Matchers](./strings.md)
151

152
### Collection Matchers
153

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

156
```kotlin { .api }
157
fun <T> List<T>.shouldHaveElementAt(index: Int, element: T): List<T>
158
infix fun <T> Collection<T>.shouldExist(p: (T) -> Boolean): Collection<T>
159
fun <T> List<T>.shouldMatchInOrder(vararg assertions: (T) -> Unit): List<T>
160
fun <T> Collection<T>.shouldContainAnyOf(vararg ts: T): Collection<T>
161
fun <T> Collection<T>.shouldBeEmpty(): Collection<T>
162
fun <T> Collection<T>.shouldHaveSize(size: Int): Collection<T>
163
```
164

165
[Collection Matchers](./collections.md)
166

167
### JVM File System
168

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

171
```kotlin { .api }
172
fun File.shouldExist(): File
173
fun File.shouldBeADirectory(): File
174
fun File.shouldBeAFile(): File
175
fun File.shouldBeEmpty(): File
176
infix fun File.shouldHaveFileSize(size: Long): File
177
infix fun File.shouldContainFile(name: String): File
178
fun File.shouldBeReadable(): File
179
infix fun File.shouldHaveSameStructureAs(file: File): File
180
```
181

182
[File System Matchers](./filesystem.md)
183

184
### JVM Reflection
185

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

188
```kotlin { .api }
189
fun KClass<*>.shouldHaveAnnotations(): KClass<*>
190
infix fun KClass<*>.shouldHaveAnnotations(count: Int): KClass<*>
191
inline fun <reified T : Annotation> KClass<*>.shouldBeAnnotatedWith(
192
    noinline block: (T) -> Unit = {}
193
): KClass<*>
194
```
195

196
[Reflection Matchers](./reflection.md)
197

198
### JVM Date and Time  
199

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

202
```kotlin { .api }
203
infix fun LocalDate.shouldBeBefore(other: LocalDate): LocalDate
204
infix fun LocalDateTime.shouldBeAfter(other: LocalDateTime): LocalDateTime
205
fun LocalDate.shouldBeToday(): LocalDate
206
fun Instant.shouldBeWithin(duration: Duration, other: Instant): Instant
207
```
208

209
[Date and Time Matchers](./datetime.md)
210

211
### JVM Concurrency
212

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

215
```kotlin { .api }
216
fun <T> CompletableFuture<T>.shouldCompleteWithin(duration: Duration): CompletableFuture<T>
217
fun <T> AtomicReference<T>.shouldHaveValue(expected: T): AtomicReference<T>
218
suspend fun <T> Channel<T>.shouldReceiveWithin(duration: Duration): T
219
```
220

221
[Concurrency Matchers](./concurrency.md)
222

223
### Result Type Validation
224

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

227
```kotlin { .api }
228
fun <T> Result<T>.shouldBeSuccess(): T
229
infix fun <T> Result<T>.shouldBeSuccess(expected: T): T
230
infix fun <T> Result<T>.shouldBeSuccess(block: ((T) -> Unit)): T
231
fun Result<*>.shouldBeFailure(): Throwable
232
inline fun <reified T : Throwable> Result<*>.shouldBeFailure(): T
233
```
234

235
[Result Matchers](./result.md)
236

237
### Exception and Error Testing
238

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

241
```kotlin { .api }
242
infix fun Throwable.shouldHaveMessage(message: String): Throwable
243
infix fun Throwable.shouldHaveMessage(message: Regex): Throwable
244
fun Throwable.shouldHaveCause(block: (Throwable) -> Unit = {}): Throwable
245
inline fun <reified T : Throwable> Throwable.shouldHaveCauseInstanceOf(): Throwable
246
infix fun Throwable.shouldHaveStackTraceContaining(substr: String): Throwable
247
```
248

249
[Throwable Matchers](./throwable.md)
250

251
### Tuple Validation
252

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

255
```kotlin { .api }
256
fun <A> Pair<A, *>.shouldHaveFirst(a: A): Pair<A, *>
257
fun <B> Pair<*, B>.shouldHaveSecond(b: B): Pair<*, B>
258
fun <A> Triple<A, *, *>.shouldHaveFirst(a: A): Triple<A, *, *>
259
fun <B> Triple<*, B, *>.shouldHaveSecond(b: B): Triple<*, B, *>
260
fun <C> Triple<*, *, C>.shouldHaveThird(c: C): Triple<*, *, C>
261
```
262

263
[Tuple Matchers](./tuples.md)
264

265
### Type System Validation
266

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

269
```kotlin { .api }
270
inline fun <reified T : Any> Any?.shouldBeInstanceOf(): T
271
inline fun <reified T : Any> Any?.shouldBeTypeOf(): T
272
infix fun Any?.shouldBeSameInstanceAs(ref: Any?): Any?
273
inline fun <reified T : Any> Any?.shouldNotBeInstanceOf(): Any?
274
```
275

276
[Type System Matchers](./types.md)
277

278
## Types
279

280
```kotlin { .api }
281
interface Matcher<T> {
282
    fun test(value: T): MatcherResult
283
    infix fun <U> contramap(f: (U) -> T): Matcher<U>
284
    fun invert(): Matcher<T>
285
}
286

287
interface MatcherResult {
288
    fun passed(): Boolean
289
    fun failureMessage(): String
290
    fun negatedFailureMessage(): String
291
}
292

293
interface ComparableMatcherResult : MatcherResult {
294
    fun actual(): String
295
    fun expected(): String
296
}
297

298
interface EqualityMatcherResult : MatcherResult {
299
    fun actual(): Any?
300
    fun expected(): Any?
301
}
302

303
data class EventuallyConfiguration(
304
    val duration: Duration = 5.seconds,
305
    val interval: Duration = 25.milliseconds,
306
    val initialDelay: Duration = Duration.ZERO,
307
    val listener: EventuallyListener = NoopEventuallyListener
308
)
309

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