0
# Result Matchers
1

2
Result matchers provide comprehensive testing support for Kotlin's `Result<T>` type, enabling precise validation of both successful values and failure exceptions with type-safe assertions.
3

4
## Capabilities
5

6
### Success Validation
7

8
Assert that a Result contains a successful value.
9

10
```kotlin { .api }
11
/**
12
 * Assert that this result is a success and return the wrapped value
13
 * @return The success value for further assertions
14
 */
15
fun <T> Result<T>.shouldBeSuccess(): T
16

17
/**
18
 * Assert that this result is a success containing the expected value
19
 * @param expected The expected success value to validate against
20
 * @return The success value for chaining
21
 */
22
infix fun <T> Result<T>.shouldBeSuccess(expected: T): T
23

24
/**
25
 * Assert that this result is a success and execute block with the value
26
 * @param block Function to execute with the success value
27
 * @return The success value for chaining
28
 */
29
infix fun <T> Result<T>.shouldBeSuccess(block: ((T) -> Unit)): T
30

31
/**
32
 * Assert that this result is not a success
33
 * @return The original Result for chaining
34
 */
35
fun <T> Result<T>.shouldNotBeSuccess(): Result<T>
36
```
37

38
**Usage Examples:**
39

40
```kotlin
41
import io.kotest.matchers.result.shouldBeSuccess
42
import io.kotest.matchers.result.shouldNotBeSuccess
43
import io.kotest.matchers.string.shouldStartWith
44

45
// Basic success validation
46
val successResult = Result.success("Hello World")
47
successResult.shouldBeSuccess() // Returns "Hello World"
48

49
// Success with expected value
50
successResult shouldBeSuccess "Hello World"
51

52
// Success with validation block
53
successResult shouldBeSuccess { value ->
54
    value shouldStartWith "Hello"
55
    value.length shouldBe 11
56
}
57

58
// Failure should not be success
59
val failureResult = Result.failure<String>(Exception("Error"))
60
failureResult.shouldNotBeSuccess()
61
```
62

63
### Failure Validation
64

65
Assert that a Result contains a failure exception.
66

67
```kotlin { .api }
68
/**
69
 * Assert that this result is a failure and return the exception
70
 * @return The failure exception for further assertions
71
 */
72
fun Result<*>.shouldBeFailure(): Throwable
73

74
/**
75
 * Assert that this result is a failure with the expected exception
76
 * @param expected The expected exception to validate against
77
 * @return The failure exception for chaining
78
 */
79
infix fun Result<*>.shouldBeFailure(expected: Throwable): Throwable
80

81
/**
82
 * Assert that this result is a failure and execute block with the exception
83
 * @param block Function to execute with the failure exception
84
 * @return The failure exception for chaining
85
 */
86
infix fun Result<*>.shouldBeFailure(block: ((Throwable) -> Unit)): Throwable
87

88
/**
89
 * Assert that this result is a failure of specific exception type
90
 * @return The typed failure exception for chaining
91
 */
92
inline fun <reified T : Throwable> Result<*>.shouldBeFailure(): T
93

94
/**
95
 * Assert that this result is not a failure
96
 * @return The original Result for chaining
97
 */
98
fun Result<*>.shouldNotBeFailure(): Result<*>
99
```
100

101
**Usage Examples:**
102

103
```kotlin
104
import io.kotest.matchers.result.shouldBeFailure
105
import io.kotest.matchers.result.shouldNotBeFailure
106
import io.kotest.matchers.throwable.shouldHaveMessage
107

108
// Basic failure validation
109
val failureResult = Result.failure<String>(IllegalArgumentException("Invalid input"))
110
val exception = failureResult.shouldBeFailure()
111

112
// Failure with expected exception
113
val specificException = IllegalArgumentException("Invalid input")
114
failureResult shouldBeFailure specificException
115

116
// Failure with validation block
117
failureResult shouldBeFailure { error ->
118
    error shouldHaveMessage "Invalid input"
119
    error shouldBeInstanceOf<IllegalArgumentException>()
120
}
121

122
// Typed failure validation
123
val typedException = failureResult.shouldBeFailure<IllegalArgumentException>()
124

125
// Success should not be failure
126
val successResult = Result.success("Hello")
127
successResult.shouldNotBeFailure()
128
```
129

130
### Common Patterns
131

132
```kotlin
133
import io.kotest.matchers.result.shouldBeSuccess
134
import io.kotest.matchers.result.shouldBeFailure
135
import io.kotest.matchers.string.shouldContain
136

137
// Testing function that returns Result<String>
138
fun parseData(input: String): Result<String> {
139
    return if (input.isNotBlank()) {
140
        Result.success(input.uppercase())
141
    } else {
142
        Result.failure(IllegalArgumentException("Input cannot be blank"))
143
    }
144
}
145

146
// Validate successful parsing
147
val result = parseData("hello")
148
result shouldBeSuccess { value ->
149
    value shouldContain "HELLO"
150
}
151

152
// Validate failure cases
153
val emptyResult = parseData("")
154
emptyResult.shouldBeFailure<IllegalArgumentException>()
155

156
// Chain further assertions on unwrapped values
157
val unwrapped = parseData("test").shouldBeSuccess()
158
unwrapped shouldBe "TEST"
159
```
160

161
## Type Definitions
162

163
```kotlin { .api }
164
class SuccessMatcher<T>(val expected: T?) : Matcher<Result<T?>> {
165
    override fun test(value: Result<T?>): MatcherResult
166
}
167

168
class FailureMatcher<T : Throwable>(val expected: T) : Matcher<Result<*>> {
169
    override fun test(value: Result<*>): MatcherResult
170
}
171

172
class FailureTypeMatcher<T : Throwable>(val clazz: KClass<T>) : Matcher<Result<*>> {
173
    override fun test(value: Result<*>): MatcherResult
174
}
175
```