0
# Kotest Assertions Shared
1

2
The Kotest Assertions Shared module provides the foundational assertion building blocks for the Kotest testing framework. This Kotlin multiplatform library includes core utilities like `shouldBe`, data-driven testing capabilities, collection inspection tools, and comprehensive error handling that are shared across the entire Kotest ecosystem.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```kotlin
14
import io.kotest.matchers.shouldBe
15
import io.kotest.matchers.should
16
import io.kotest.matchers.shouldNot
17
import io.kotest.data.*
18
import io.kotest.inspectors.*
19
import io.kotest.assertions.*
20
```
21

22
## Basic Usage
23

24
```kotlin
25
import io.kotest.matchers.shouldBe
26
import io.kotest.data.*
27
import io.kotest.inspectors.forAll
28

29
// Basic assertions
30
val result = "hello world"
31
result shouldBe "hello world"
32
result.length shouldBe 11
33

34
// Data-driven testing
35
val table = table(
36
    headers("input", "expected"),
37
    row("hello", 5),
38
    row("world", 5),
39
    row("kotlin", 6)
40
)
41

42
table.forAll { input, expected ->
43
    input.length shouldBe expected
44
}
45

46
// Collection inspection
47
listOf(2, 4, 6, 8).forAll { it % 2 shouldBe 0 }
48
```
49

50
## Architecture
51

52
Kotest Assertions Shared is built around several key components:
53

54
- **Matcher System**: Core `shouldBe`/`should`/`shouldNot` DSL with extensible `Matcher<T>` interface
55
- **Data-Driven Testing**: Table-based testing framework supporting up to 22-column tables with type safety
56
- **Collection Inspectors**: Comprehensive set of quantifier functions (`forAll`, `forOne`, `forExactly`, etc.)
57
- **Error Management**: Sophisticated error collection and reporting with contextual clues
58
- **Print System**: Extensible value printing and formatting system for test output
59
- **Multiplatform Support**: Consistent API across JVM, JavaScript, Native, and WebAssembly targets
60

61
## Capabilities
62

63
### Core Matchers
64

65
Basic assertion DSL providing natural language testing with `shouldBe`, `should`, and `shouldNot` functions. Forms the foundation of all Kotest assertions.
66

67
```kotlin { .api }
68
infix fun <T, U : T> T.shouldBe(expected: U?): T
69
infix fun <T> T.shouldNotBe(any: Any?): T  
70
infix fun <T> T.should(matcher: Matcher<T>): T
71
infix fun <T> T.shouldNot(matcher: Matcher<T>): T
72

73
interface Matcher<T> {
74
    fun test(value: T): MatcherResult
75
}
76
```
77

78
[Core Matchers](./core-matchers.md)
79

80
### Data-Driven Testing
81

82
Comprehensive table-based testing framework with type-safe row and table definitions supporting up to 22 columns. Perfect for parameterized tests and comprehensive test coverage.
83

84
```kotlin { .api }
85
fun <A> table(headers: Headers1, vararg rows: Row1<A>): Table1<A>
86
fun <A, B> table(headers: Headers2, vararg rows: Row2<A, B>): Table2<A, B>
87

88
suspend fun <A> Table1<A>.forAll(fn: suspend (A) -> Unit)
89
suspend fun <A, B> Table2<A, B>.forAll(fn: suspend (A, B) -> Unit)
90

91
data class Row1<out A>(val a: A)
92
data class Row2<out A, out B>(val a: A, val b: B)
93
```
94

95
[Data-Driven Testing](./data-driven-testing.md)
96

97
### Collection Inspectors
98

99
Powerful collection testing DSL with quantifier functions for asserting properties across collection elements. Supports collections, arrays, sequences, and maps.
100

101
```kotlin { .api }
102
inline fun <T, C : Collection<T>> C.forAll(fn: (T) -> Unit): C
103
inline fun <T, C : Collection<T>> C.forOne(fn: (T) -> Unit): C
104
inline fun <T, C : Collection<T>> C.forExactly(k: Int, fn: (T) -> Unit): C
105
inline fun <T, C : Collection<T>> C.forSome(fn: (T) -> Unit): C
106
inline fun <T, C : Collection<T>> C.forNone(fn: (T) -> Unit): C
107
```
108

109
[Collection Inspectors](./collection-inspectors.md)
110

111
### Error Handling & Context
112

113
Advanced error collection and reporting system with contextual clues for enhanced debugging. Supports both soft and hard error collection modes.
114

115
```kotlin { .api }
116
inline fun <R> withClue(clue: Any?, thunk: () -> R): R
117
inline fun <T : Any?, R> T.asClue(block: (T) -> R): R
118

119
fun failure(message: String): AssertionError
120
fun failure(expected: Expected, actual: Actual): Throwable
121
inline fun shouldFail(block: () -> Any?): AssertionError
122
```
123

124
[Error Handling](./error-handling.md)
125

126
## Common Types
127

128
```kotlin { .api }
129
interface MatcherResult {
130
    val passed: Boolean
131
    val failureMessage: String
132
    val negatedFailureMessage: String
133
}
134

135
data class Printed(val value: String)
136

137
enum class ErrorCollectionMode { Soft, Hard }
138

139
interface Row {
140
    fun values(): List<Any?>
141
}
142
```