0
# Core Matchers
1

2
The core matcher system provides the foundation for all Kotest assertions through a natural language DSL. The primary functions `shouldBe`, `should`, and `shouldNot` enable fluent, readable test assertions with comprehensive error reporting.
3

4
## Capabilities
5

6
### Basic Assertion Functions
7

8
The fundamental assertion functions that form the basis of all Kotest testing.
9

10
```kotlin { .api }
11
/**
12
 * Basic equality assertion - most commonly used assertion in Kotest
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
 * Basic inequality assertion
20
 * @param any The value that should not equal this value
21
 * @return The original value for chaining
22
 */
23
infix fun <T> T.shouldNotBe(any: Any?): T
24

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

32
/**
33
 * Apply a negative matcher to this value
34
 * @param matcher The matcher to apply (result will be negated)
35
 * @return The original value for chaining
36
 */
37
infix fun <T> T.shouldNot(matcher: Matcher<T>): T
38

39
/**
40
 * Semantic alias for should() - use when it reads better
41
 * @param matcher The matcher to apply
42
 * @return The original value for chaining
43
 */
44
infix fun <T> T.shouldHave(matcher: Matcher<T>): T
45

46
/**
47
 * Semantic alias for shouldNot() - use when it reads better
48
 * @param matcher The matcher to apply (result will be negated)
49
 * @return The original value for chaining
50
 */
51
infix fun <T> T.shouldNotHave(matcher: Matcher<T>): T
52

53
/**
54
 * Apply an assertion function directly to this value (lambda-based matcher)
55
 * @param matcher Assertion function to apply
56
 * @return The original value for chaining
57
 */
58
infix fun <T> T.should(matcher: (T) -> Unit): T
59
```
60

61
**Usage Examples:**
62

63
```kotlin
64
import io.kotest.matchers.*
65

66
// Basic equality
67
"hello" shouldBe "hello"
68
42 shouldBe 42
69
listOf(1, 2, 3) shouldBe listOf(1, 2, 3)
70

71
// Basic inequality  
72
"hello" shouldNotBe "world"
73
42 shouldNotBe 43
74

75
// Using custom matchers (examples with hypothetical matchers)
76
"hello" should startWith("he")
77
"hello" shouldNot endWith("lo")
78
"hello" shouldHave length(5)
79
"hello" shouldNotHave length(6)
80

81
// Chaining assertions
82
val result = "hello world"
83
result shouldBe "hello world" shouldHave length(11)
84
```
85

86
### Matcher Interface
87

88
The core interface for creating custom matchers.
89

90
```kotlin { .api }
91
/**
92
 * Interface for creating custom matchers
93
 * @param T The type of value this matcher can test
94
 */
95
interface Matcher<T> {
96
    /**
97
     * Test the given value against this matcher's criteria
98
     * @param value The value to test
99
     * @return MatcherResult indicating pass/fail and error messages
100
     */
101
    fun test(value: T): MatcherResult
102
}
103

104
/**
105
 * Result of a matcher evaluation
106
 */
107
interface MatcherResult {
108
    /** Whether the matcher passed */
109
    val passed: Boolean
110
    /** Error message to show when the matcher fails */
111
    val failureMessage: String
112
    /** Error message to show when the negated matcher fails */
113
    val negatedFailureMessage: String
114
}
115
```
116

117
### Matcher Factory Functions
118

119
Utility functions for creating common matchers.
120

121
```kotlin { .api }
122
/**
123
 * Create an equality matcher
124
 * @param expected The expected value
125
 * @return Matcher that tests for equality
126
 */
127
fun <T> be(expected: T): Matcher<T>
128

129
/**
130
 * Create an equality matcher with type information
131
 * @param expected The expected value
132
 * @return Matcher that tests for equality
133
 */
134
fun <T> equalityMatcher(expected: T): Matcher<T>
135

136
/**
137
 * Execute a matcher against a value and return the value
138
 * @param t The value to test
139
 * @param matcher The matcher to apply
140
 * @return The original value for chaining
141
 */
142
fun <T> invokeMatcher(t: T, matcher: Matcher<T>): T
143
```
144

145
**Usage Examples:**
146

147
```kotlin
148
import io.kotest.matchers.*
149

150
// Using factory functions
151
"hello" should be("hello")
152
"hello" should equalityMatcher("hello")
153

154
// Custom matcher example
155
val customMatcher = object : Matcher<String> {
156
    override fun test(value: String): MatcherResult {
157
        val passed = value.length == 5
158
        return object : MatcherResult {
159
            override val passed = passed
160
            override val failureMessage = "Expected string length 5, but was ${value.length}"
161
            override val negatedFailureMessage = "Expected string length not to be 5"
162
        }
163
    }
164
}
165

166
"hello" should customMatcher
167
"hello" shouldNot customMatcher
168
```
169

170

171
## Common Patterns
172

173
### Chaining Assertions
174

175
All assertion functions return the original value, enabling fluent chaining:
176

177
```kotlin
178
val user = User("Alice", 25, "alice@example.com")
179

180
user.name shouldBe "Alice" 
181
user.age shouldBe 25
182
user.email shouldBe "alice@example.com"
183

184
// Or chain multiple assertions on the same value
185
user.name shouldBe "Alice" shouldHave length(5)
186
```
187

188
### Null Safety
189

190
The matcher system handles null values appropriately:
191

192
```kotlin
193
val nullable: String? = null
194
nullable shouldBe null
195

196
val nonNull: String? = "hello"  
197
nonNull shouldNotBe null
198
nonNull shouldBe "hello"
199
```
200

201
### Type Safety
202

203
The generic type system preserves type information:
204

205
```kotlin
206
val numbers: List<Int> = listOf(1, 2, 3)
207
val result: List<Int> = numbers shouldBe listOf(1, 2, 3)
208
// result is still typed as List<Int>
209
```