Skip to content

Commit db8d0b9

Browse files
rcardinrcardin
authored
Merge pull request #62 from rcardin/32-add-a-readme-with-examples-of-available-assertions
Add a readme with examples of available assertions
2 parents e2e2dd0 + 5647f19 commit db8d0b9

File tree

2 files changed

+74
-6
lines changed

2 files changed

+74
-6
lines changed

‎README.md‎

Lines changed: 69 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,86 @@
77

88
# assertj-arrow-core
99

10-
This project provides a set of [AssertJ](https://assertj.github.io/doc/) assertions for the [Arrow](https://arrow-kt.io/) library. In detail, the project provides assertions for the following Arrow types:
10+
This project provides a set of [AssertJ](https://assertj.github.io/doc/) assertions for
11+
the [Arrow](https://arrow-kt.io/) library. In detail, the project provides assertions for the following Arrow types:
1112

1213
- [x] `Either<E, A>`
1314
- [x] `Option<A>`
1415
- [x] `Raise<E>.() -> A`
1516

16-
Maybe you're asking yourself: "Why do we need AssertJ assertions for Arrow types?". The answer is simple: We often use Kotlin and Arrow Kt inside a Java project using Spring Boot. In this case, we already have AssertJ in the classpath as an assertion library. So, why not use it to assert Arrow types?
17+
Maybe you're asking yourself: "Why do we need AssertJ assertions for Arrow types?". The answer is simple: We often use
18+
Kotlin and Arrow Kt inside a Java project using Spring Boot. In this case, we already have AssertJ in the classpath as
19+
an assertion library. So, why not use it to assert Arrow types?
1720

1821
## Usage
1922

2023
The library is available on Maven Central. To use it, add the following dependency to your `pom.xml` file:
2124

2225
```xml
26+
2327
<dependency>
24-
<groupId>in.rcard</groupId>
25-
<artifactId>assertj-arrow-core</artifactId>
26-
<version>1.1.0</version>
27-
<scope>test</scope>
28+
<groupId>in.rcard</groupId>
29+
<artifactId>assertj-arrow-core</artifactId>
30+
<version>1.1.0</version>
31+
<scope>test</scope>
2832
</dependency>
2933
```
34+
35+
Otherwise, if you're using Gradle, add the following dependency to your `build.gradle.kts` file:
36+
37+
```kotlin
38+
testImplementation("in.rcard:assertj-arrow-core:1.1.0")
39+
```
40+
41+
## Assertions Guide
42+
43+
This section describes the assertions provided by the `assertj-arrow-core` library.
44+
45+
### `Option<A>`
46+
47+
Use the `in.rcard.assertj.arrowcore.OptionAssert` class as an entry point to assert `Option<A>` instances.
48+
49+
| Assertions | Description |
50+
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
51+
| `isEmpty` | Verifies that the actual `Option` is empty. |
52+
| `contains` | Verifies that the actual `Option` contains the given value. |
53+
| `containsInstanceOf` | Verifies that the actual `Option` contains a value that is an instance of the argument. |
54+
| `get` | Verifies that the actual Option is not null and not empty and returns an Object assertion that allows chaining (object) assertions on the optional value. |
55+
| `isDefined` | Verifies that there is a value present in the actual `Option`. |
56+
57+
### `Either<E, A>`
58+
59+
Use the `in.rcard.assertj.arrowcore.EitherAssert` class as an entry point to assert `Either<E, A>` instances.
60+
61+
| Assertions | Description |
62+
|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
63+
| `isRight` | Verifies that the actual `Either` is right. |
64+
| `isLeft` | Verifies that the actual `Either` is left. |
65+
| `containsOnRight` | Verifies that the actual `Either` is `Either.Right` and contains the given value. |
66+
| `containsRightInstanceOf` | Verifies that the actual right-sided `Either` contains a value that is an instance of the argument. |
67+
| `asRight` | Verifies that the actual `Either` is not `null` and contains a right-sided value and returns an `Object` assertion that allows chaining (object) assertions on the value. |
68+
| `containsOnLeft` | Verifies that the actual `Either` is `Either.Left` and contains the given value. |
69+
| `containsLeftInstanceOf` | Verifies that the actual left-sided `Either` contains a value that is an instance of the argument. |
70+
| `asLeft` | Verifies that the actual `Either` is not `null` and contains a left-sided value and returns an `Object` assertion that allows chaining (object) assertions on the value. |
71+
72+
### `Raise<E>.() -> A`
73+
74+
Use the `in.rcard.assertj.arrowcore.RaiseAssert` class as an entry point to assert `Raise<E>.() -> A` instances. There
75+
are many different entry points, all of them available boh for regular and `suspend` functions:
76+
77+
| Entry Point | Description |
78+
|----------------------|-----------------------------------------------------------------------------------------------------------------------------|
79+
| `assertThat` | Entry point to assert a `Raise<E>.() -> A` instance. |
80+
| `assertThatThrownBy` | Verifies that the function in the `Raise` context throws an exception and let chaining assertion on the thrown exception |
81+
| `assertThatRaisedBy` | Verifies that the function in the `Raise` context raises a logic-typed error and let chaining assertion on the raised error |
82+
83+
The available assertions are:
84+
85+
| Assertions | Description |
86+
|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
87+
| `succeedsWith` | Verifies that the function in the `Raise` context succeeds with the given value. |
88+
| `succeeds` | Verifies that the function in the `Raise` context succeeded. No check on the value returned by the function is performed. |
89+
| `raises` | Verifies that the function in the Raise context fails with the given error. |
90+
| `fails` | Verifies that the function in the Raise context fails, no matter the type of the logical error. |
91+
| `result` | Verifies that the actual function in the `Raise` context succeeds and returns an `Object` assertion that allows chaining (object) assertions on the returned value. |
92+
| `error` | Verifies that the actual function in the Raise context fails and returns an Object assertion that allows chaining (object) assertions on the raised error. |

‎src/main/kotlin/in/rcard/assertj/arrowcore/RaiseAssert.kt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,11 @@ class RaiseAssert<ERROR : Any, VALUE : Any>(
6161
.failure(Assertions.assertThat(throwable).writableAssertionInfo, shouldThrowAnException())
6262
}
6363

64+
/**
65+
* Verifies that the function in the [Raise] context raises an error.
66+
* @param shouldRaiseError the function to be executed in the [Raise] context.
67+
* @return the [AbstractObjectAssert] to be used to verify the error.
68+
*/
6469
inline fun <ERROR : Any, VALUE : Any> assertThatRaisedBy(
6570
@BuilderInference shouldRaiseError: Raise<ERROR>.() -> VALUE,
6671
): AbstractObjectAssert<*, out ERROR> {

0 commit comments

Comments
 (0)