0
# Core DSL
1

2
The Core DSL provides the fundamental assertion functions and matcher infrastructure that form the foundation of all other matchers in Kotest Assertions.
3

4
## Capabilities
5

6
### Primary Assertion Functions
7

8
The core assertion functions provide the main entry points for testing values.
9

10
```kotlin { .api }
11
/**
12
 * Assert that this value should be equal to the expected value
13
 * @param expected The expected value to compare against
14
 * @return The original value for chaining
15
 */
16
infix fun <T, U : T> T.shouldBe(expected: U?): T
17

18
/**
19
 * Assert that this value should not be equal to the given value
20
 * @param any The value that this should not equal
21
 * @return The original value for chaining
22
 */
23
infix fun <T> T.shouldNotBe(any: Any?): T
24

25
/**
26
 * Assert that this value should match the given matcher
27
 * @param matcher The matcher to apply to this value
28
 * @return The original value for chaining
29
 */
30
infix fun <T> T.should(matcher: Matcher<T>): T
31

32
/**
33
 * Assert that this value should not match the given matcher
34
 * @param matcher The matcher that this value should not match
35
 * @return The original value for chaining
36
 */
37
infix fun <T> T.shouldNot(matcher: Matcher<T>): T
38
```
39

40
**Usage Examples:**
41

42
```kotlin
43
import io.kotest.matchers.shouldBe
44
import io.kotest.matchers.shouldNotBe
45
import io.kotest.matchers.should
46
import io.kotest.matchers.shouldNot
47
import io.kotest.matchers.string.startWith
48

49
// Basic equality assertions
50
val name = "Alice"
51
name shouldBe "Alice"
52
name shouldNotBe "Bob"
53

54
// Using matchers
55
name should startWith("Al")
56
name shouldNot startWith("Bo")
57

58
// Chaining assertions
59
val result = processData()
60
result shouldBe "processed" shouldBe "processed"
61
```
62

63
### Matcher Interface
64

65
The core abstraction that enables composable and reusable assertion logic.
66

67
```kotlin { .api }
68
/**
69
 * Core matcher interface that defines how values are tested
70
 */
71
interface Matcher<T> {
72
    /**
73
     * Test a value against this matcher
74
     * @param value The value to test
75
     * @return Result containing pass/fail status and messages
76
     */
77
    fun test(value: T): MatcherResult
78
    
79
    /**
80
     * Transform this matcher to work with a different input type
81
     * @param f Function to convert from U to T
82
     * @return New matcher that accepts type U
83
     */
84
    infix fun <U> contramap(f: (U) -> T): Matcher<U>
85
    
86
    /**
87
     * Create a matcher with inverted logic
88
     * @return Matcher that passes when this matcher fails
89
     */
90
    fun invert(): Matcher<T>
91
}
92
```
93

94
### Matcher Results
95

96
Result types that provide detailed information about assertion outcomes.
97

98
```kotlin { .api }
99
/**
100
 * Base result interface for matcher operations
101
 */
102
interface MatcherResult {
103
    /**
104
     * Whether the matcher test passed
105
     */
106
    fun passed(): Boolean
107
    
108
    /**
109
     * Message shown when the test fails
110
     */
111
    fun failureMessage(): String
112
    
113
    /**
114
     * Message shown when the negated test fails
115
     */
116
    fun negatedFailureMessage(): String
117
}
118

119
/**
120
 * Enhanced result with comparison details for ordered types
121
 */
122
interface ComparableMatcherResult : MatcherResult {
123
    /**
124
     * String representation of the actual value
125
     */
126
    fun actual(): String
127
    
128
    /**
129
     * String representation of the expected value
130
     */
131
    fun expected(): String
132
}
133

134
/**
135
 * Enhanced result for equality-based assertions
136
 */
137
interface EqualityMatcherResult : MatcherResult {
138
    /**
139
     * The actual value being tested
140
     */
141
    fun actual(): Any?
142
    
143
    /**
144
     * The expected value for comparison
145
     */
146
    fun expected(): Any?
147
}
148
```
149

150
### Matcher Factory Functions
151

152
Core utility functions for creating common matchers.
153

154
```kotlin { .api }
155
/**
156
 * Create an equality matcher
157
 * @param expected The value to match against
158
 * @return Matcher that checks for equality
159
 */
160
fun <T> be(expected: T): Matcher<T>
161

162
/**
163
 * Create a matcher that always passes
164
 * @return Matcher that never fails
165
 */
166
fun <T> any(): Matcher<T>
167

168
/**
169
 * Combine multiple matchers with AND logic
170
 * @param matchers Variable number of matchers to combine
171
 * @return Matcher that passes only if all input matchers pass
172
 */
173
fun <T> allOf(vararg matchers: Matcher<T>): Matcher<T>
174

175
/**
176
 * Combine multiple matchers with OR logic
177
 * @param matchers Variable number of matchers to combine  
178
 * @return Matcher that passes if any input matcher passes
179
 */
180
fun <T> anyOf(vararg matchers: Matcher<T>): Matcher<T>
181
```
182

183
**Usage Examples:**
184

185
```kotlin
186
import io.kotest.matchers.*
187
import io.kotest.matchers.string.*
188

189
// Using matcher factories
190
val value = "Hello World"
191
value should be("Hello World")
192
value should anyOf(startWith("Hi"), startWith("Hello"))
193

194
// Creating custom matchers
195
fun <T> beOneOf(vararg options: T): Matcher<T> = object : Matcher<T> {
196
    override fun test(value: T): MatcherResult = 
197
        if (value in options) MatcherResult.Success
198
        else MatcherResult.failure("$value should be one of ${options.toList()}")
199
}
200

201
// Using custom matcher
202
val status = "active"
203
status should beOneOf("active", "inactive", "pending")
204
```
205

206
### Matcher Composition
207

208
Advanced patterns for combining and transforming matchers.
209

210
```kotlin { .api }
211
/**
212
 * Transform a matcher to work with nullable types
213
 * @param matcher The base matcher for non-null values
214
 * @return Matcher that handles null values appropriately
215
 */
216
fun <T> Matcher<T>.orNull(): Matcher<T?>
217

218
/**
219
 * Transform a matcher to work with collection elements
220
 * @param matcher The matcher to apply to each element
221
 * @return Matcher that tests all collection elements
222
 */
223
fun <T> Matcher<T>.forAll(): Matcher<Collection<T>>
224

225
/**
226
 * Transform a matcher to work with at least one collection element
227
 * @param matcher The matcher to apply to elements
228
 * @return Matcher that passes if any element matches
229
 */
230
fun <T> Matcher<T>.forAny(): Matcher<Collection<T>>
231
```
232

233
## Error Handling
234

235
The core DSL provides detailed error messages that help identify assertion failures:
236

237
- **Equality failures**: Show expected vs actual values with type information
238
- **Matcher failures**: Include specific failure reasons from the matcher
239
- **Collection failures**: Highlight which elements or indices failed
240
- **Null safety**: Clear messages for null/non-null mismatches
241

242
All assertion functions throw `AssertionError` on failure, which integrates seamlessly with testing frameworks.