0
# Throwable Matchers
1

2
Comprehensive throwable and exception validation including message checks, cause analysis, stack trace validation, and type assertions for robust error testing capabilities.
3

4
## Capabilities
5

6
### Message Validation
7

8
Assert that throwables have specific message content.
9

10
```kotlin { .api }
11
/**
12
 * Assert that this throwable has the expected message (exact match)
13
 * @param message The expected exact message content
14
 * @return The original Throwable for chaining
15
 */
16
infix fun Throwable.shouldHaveMessage(message: String): Throwable
17

18
/**
19
 * Assert that this throwable does not have the specified message
20
 * @param message The message that should not be present
21
 * @return The original Throwable for chaining
22
 */
23
infix fun Throwable.shouldNotHaveMessage(message: String): Throwable
24

25
/**
26
 * Assert that this throwable has a message matching the regex pattern
27
 * @param message The regex pattern to match against the message
28
 * @return The original Throwable for chaining
29
 */
30
infix fun Throwable.shouldHaveMessage(message: Regex): Throwable
31

32
/**
33
 * Assert that this throwable does not have a message matching the regex
34
 * @param message The regex pattern that should not match
35
 * @return The original Throwable for chaining
36
 */
37
infix fun Throwable.shouldNotHaveMessage(message: Regex): Throwable
38
```
39

40
**Usage Examples:**
41

42
```kotlin
43
import io.kotest.matchers.throwable.shouldHaveMessage
44
import io.kotest.matchers.throwable.shouldNotHaveMessage
45

46
// Exact message validation
47
val exception = IllegalArgumentException("Invalid input provided")
48
exception shouldHaveMessage "Invalid input provided"
49
exception shouldNotHaveMessage "Different message"
50

51
// Regex message validation
52
exception shouldHaveMessage Regex("Invalid .* provided")
53
exception shouldNotHaveMessage Regex("Valid .*")
54

55
// Testing caught exceptions
56
shouldThrow<IllegalArgumentException> {
57
    processInput("")
58
} shouldHaveMessage "Input cannot be empty"
59
```
60

61
### Cause Analysis
62

63
Assert and validate exception causes in the throwable chain.
64

65
```kotlin { .api }
66
/**
67
 * Assert that this throwable has a cause and optionally validate it
68
 * @param block Optional validation block for the cause
69
 * @return The original Throwable for chaining
70
 */
71
fun Throwable.shouldHaveCause(block: (Throwable) -> Unit = {}): Throwable
72

73
/**
74
 * Assert that this throwable does not have a cause
75
 * @return The original Throwable for chaining
76
 */
77
fun Throwable.shouldNotHaveCause(): Throwable
78

79
/**
80
 * Assert that this throwable has a cause of the specified type or subtype
81
 * @return The original Throwable for chaining
82
 */
83
inline fun <reified T : Throwable> Throwable.shouldHaveCauseInstanceOf(): Throwable
84

85
/**
86
 * Assert that this throwable does not have a cause of the specified type
87
 * @return The original Throwable for chaining
88
 */
89
inline fun <reified T : Throwable> Throwable.shouldNotHaveCauseInstanceOf(): Throwable
90

91
/**
92
 * Assert that this throwable has a cause of exactly the specified type
93
 * @return The original Throwable for chaining
94
 */
95
inline fun <reified T : Throwable> Throwable.shouldHaveCauseOfType(): Throwable
96

97
/**
98
 * Assert that this throwable does not have a cause of exactly the specified type
99
 * @return The original Throwable for chaining
100
 */
101
inline fun <reified T : Throwable> Throwable.shouldNotHaveCauseOfType(): Throwable
102
```
103

104
**Usage Examples:**
105

106
```kotlin
107
import io.kotest.matchers.throwable.shouldHaveCause
108
import io.kotest.matchers.throwable.shouldNotHaveCause
109
import io.kotest.matchers.throwable.shouldHaveCauseInstanceOf
110
import io.kotest.matchers.throwable.shouldHaveCauseOfType
111

112
// Basic cause validation
113
val cause = IOException("Network error")
114
val wrapper = RuntimeException("Operation failed", cause)
115

116
wrapper.shouldHaveCause()
117
wrapper.shouldHaveCause { it shouldHaveMessage "Network error" }
118

119
// Type-specific cause validation  
120
wrapper.shouldHaveCauseInstanceOf<IOException>()
121
wrapper.shouldHaveCauseOfType<IOException>()
122

123
// Exception without cause
124
val simple = IllegalStateException("Simple error")
125
simple.shouldNotHaveCause()
126
```
127

128
### Stack Trace Validation
129

130
Assert that stack traces contain specific content or patterns.
131

132
```kotlin { .api }
133
/**
134
 * Assert that this throwable's stack trace contains the substring
135
 * @param substr The substring to search for in the stack trace
136
 * @return The original Throwable for chaining
137
 */
138
infix fun Throwable.shouldHaveStackTraceContaining(substr: String): Throwable
139

140
/**
141
 * Assert that this throwable's stack trace does not contain the substring
142
 * @param substr The substring that should not be in the stack trace
143
 * @return The original Throwable for chaining
144
 */
145
infix fun Throwable.shouldNotHaveStackTraceContaining(substr: String): Throwable
146

147
/**
148
 * Assert that this throwable's stack trace matches the regex pattern
149
 * @param regex The regex pattern to match against the stack trace
150
 * @return The original Throwable for chaining
151
 */
152
infix fun Throwable.shouldHaveStackTraceContaining(regex: Regex): Throwable
153

154
/**
155
 * Assert that this throwable's stack trace does not match the regex
156
 * @param regex The regex pattern that should not match
157
 * @return The original Throwable for chaining
158
 */
159
infix fun Throwable.shouldNotHaveStackTraceContaining(regex: Regex): Throwable
160
```
161

162
**Usage Examples:**
163

164
```kotlin  
165
import io.kotest.matchers.throwable.shouldHaveStackTraceContaining
166
import io.kotest.matchers.throwable.shouldNotHaveStackTraceContaining
167

168
// Stack trace content validation
169
val exception = RuntimeException("Test error")
170
exception shouldHaveStackTraceContaining "RuntimeException"
171
exception shouldHaveStackTraceContaining "Test error"
172
exception shouldNotHaveStackTraceContaining "SomeOtherClass"
173

174
// Regex pattern matching in stack trace
175
exception shouldHaveStackTraceContaining Regex("at .*\\.kt:\\d+")
176
exception shouldNotHaveStackTraceContaining Regex("at some\\.non\\.existent")
177

178
// Testing for specific method calls in stack
179
shouldThrow<Exception> {
180
    someMethodThatThrows()
181
} shouldHaveStackTraceContaining "someMethodThatThrows"
182
```
183

184
### Common Exception Testing Patterns
185

186
```kotlin
187
import io.kotest.assertions.throwables.shouldThrow
188
import io.kotest.matchers.throwable.*
189

190
// Comprehensive exception validation
191
val exception = shouldThrow<IllegalArgumentException> {
192
    validateInput("")
193
}
194

195
exception shouldHaveMessage "Input cannot be empty"
196
exception.shouldNotHaveCause()
197
exception shouldHaveStackTraceContaining "validateInput"
198

199
// Nested exception validation
200
val nested = shouldThrow<ProcessingException> {
201
    processData("invalid")
202
}
203

204
nested shouldHaveMessage "Failed to process data"
205
nested.shouldHaveCause { cause ->
206
    cause shouldHaveMessage "Invalid data format"
207
    cause.shouldHaveCauseInstanceOf<IllegalArgumentException>()
208
}
209

210
// Regex-based message validation for dynamic content
211
val timestampException = shouldThrow<RuntimeException> {
212
    generateTimestampedError()
213
}
214

215
timestampException shouldHaveMessage Regex("Error at \\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}")
216
```
217

218
## Type Definitions
219

220
```kotlin { .api }
221
interface Matcher<T> {
222
    fun test(value: T): MatcherResult
223
}
224

225
data class MatcherResult(
226
    val passed: Boolean,
227
    val failureMessage: () -> String,
228
    val negatedFailureMessage: () -> String
229
)
230

231
data class ComparableMatcherResult(
232
    val passed: Boolean, 
233
    val failureMessage: () -> String,
234
    val negatedFailureMessage: () -> String,
235
    val actual: String,
236
    val expected: String
237
) : MatcherResult
238
```