Skip to content

Commit

Permalink
Cutting docs for 5.9
Browse files Browse the repository at this point in the history
  • Loading branch information
@Kantis
Kantis committed May 9, 2024
1 parent 237d7f6 commit 879e562
Show file tree
Hide file tree
Showing 148 changed files with 13,816 additions and 0 deletions.
50 changes: 50 additions & 0 deletions documentation/versioned_docs/version-5.9/assertions/arrow.md
View file
@@ -0,0 +1,50 @@
---
title: Arrow
slug: arrow.html
sidebar_label: Arrow
---


[![Latest Release](https://img.shields.io/maven-central/v/io.kotest.extensions/kotest-assertions-arrow)](https://search.maven.org/artifact/io.kotest.extensions/kotest-assertions-arrow)

This page lists all current matchers in the Kotest arrow matchers extension library.

:::note
The following module is needed: `io.kotest.extensions:kotest-assertions-arrow` which is versioned independently of the main Kotest project.
Search maven central for latest version [here](https://central.sonatype.com/search?q=io.kotest.extensions:kotest-assertions-arrow).
:::

:::note
In the case `io.arrow-kt:arrow-core:arrow-version` is not in your classpath, please add it. To prevent Unresolved Reference errors.
:::

| Option | |
|--------------------------|-----------------------------------------------------------|
| `option.shouldBeSome()` | Asserts that the option is of type Some and returns value |
| `option.shouldBeSome(v)` | Asserts that the option is of type Some with value v |
| `option.shouldBeNone()` | Asserts that the option is of type None |

| Either | |
|---------------------------|----------------------------------------------------------------------|
| `either.shouldBeRight()` | Asserts that the either is of type Right and returns the Right value |
| `either.shouldBeRight(v)` | Asserts that the either is of type Right with specified value v |
| `either.shouldBeLeft()` | Asserts that the either is of type Left and returns the Left value |
| `either.shouldBeLeft(v)` | Asserts that the either is of type Left with specific value v |

| NonEmptyList | |
|--------------------------------------|----------------------------------------------------------------------------|
| `nel.shouldContain(e)` | Asserts that the NonEmptyList contains the given element e |
| `nel.shouldContainAll(e1,e2,...,en)` | Asserts that the NonEmptyList contains all the given elements e1,e2,...,en |
| `nel.shouldContainNull()` | Asserts that the NonEmptyList contains at least one null |
| `nel.shouldContainNoNulls()` | Asserts that the NonEmptyList contains no nulls |
| `nel.shouldContainOnlyNulls()` | Asserts that the NonEmptyList contains only nulls or is empty |
| `nel.shouldHaveDuplicates()` | Asserts that the NonEmptyList has at least one duplicate |
| `nel.shouldBeSingleElement(e)` | Asserts that the NonEmptyList has a single element which is e |
| `nel.shouldBeSorted()` | Asserts that the NonEmptyList is sorted |

| Validated | |
|--------------------------------|-----------------------------------------------------------------------------|
| `validated.shouldBeValid()` | Asserts that the validated is of type Valid and returns the Valid value |
| `validated.shouldBeValid(v)` | Asserts that the validated is of type Valid with specific value v |
| `validated.shouldBeInvalid()` | Asserts that the validated is of type Invalid and returns the Invalid value |
| `validated.shouldBeInvalid(v)` | Asserts that the validated is of type Invalid with specific value v |
37 changes: 37 additions & 0 deletions documentation/versioned_docs/version-5.9/assertions/assertion_mode.md
View file
@@ -0,0 +1,37 @@
---
id: assertion_mode
title: Assertion Mode
slug: assertion-mode.html
---



If you are using Kotest framework alongside Kotest assertions, you can ask Kotest to fail the build, or output a warning to stderr, if a test is executed that does not execute an assertion.

To do this, set `assertionMode` to `AssertionMode.Error` or `AssertionMode.Warn` inside a spec. For example.

```kotlin
class MySpec : FunSpec() {
init {
assertions = AssertionMode.Error
test("this test has no assertions") {
val name = "sam"
name.length == 3 // this isn't actually testing anything
}
}
}
```

Running this test will output something like:

```
Test 'this test has no assertions' did not invoke any assertions
```

If we want to set this globally, we can do so in [project config](../framework/project_config.md) or via the system property `kotest.framework.assertion.mode`.


:::note
Assertion mode only works for Kotest assertions and not other assertion libraries.
:::

141 changes: 141 additions & 0 deletions documentation/versioned_docs/version-5.9/assertions/clues.md
View file
@@ -0,0 +1,141 @@
---
title: Clues
slug: clues.html
---

:::note
Clues only work if you are using the Kotest assertions library
:::

A rule of thumb is that a failing test should look like a good bug report.
In other words, it should tell you what went wrong, and ideally why it went wrong.

Sometimes a failed assertion contains enough information in the error message to know what went wrong.

For example:

```kotlin
username shouldBe "sksamuel"
```

Might give an error like:

```
expected: "sksamuel" but was: "sam@myemailaddress.com"
```

In this case, it looks like the system populates the username field with an email address.

But let's say you had a test like this:

```kotlin
user.name shouldNotBe null
```

If this failed, you would simply get:

```
<null> should not equal <null>
```

Which isn't particularly helpful. This is where `withClue` comes into play.

The `withClue` and `asClue` helpers can add extra context to assertions so failures are self explanatory:

For example, we can use `withClue` with a string message

```kotlin
withClue("Name should be present") {
user.name shouldNotBe null
}
```

Would give an error like this:

```
Name should be present
<null> should not equal <null>
```

The error message became much better, however, it is still not as good as it could be.
For instance, it might be helpful to know the user's id to check the database.

We can use `asClue` to add the user's id to the error message:

```kotlin
withClue({ "Name should be present (user_id=${user.id})" }) {
user.name shouldNotBe null
}
```

We can also use the `asClue` extension function to turn any object into the clue message.

```kotlin
{ "Name should be present (user_id=${user.id})" }.asClue {
user.name shouldNotBe null
}
```

The message will be computed only in case the test fails, so it is safe to use it with expensive operations.

:::tip
Test failures include a failed assertion, test name, clues, and stacktrace.
Consider using them in such a way, so they answer both what has failed, and why it failed.
It will make the tests easier to maintain, especially when it comes to reverse-engineering the intention of the test author.
:::

:::tip
Every time you see a code comment above an assertion, consider using `asClue`, or `withClue` instead.
The comments are not visible in the test failures, especially on CI, while clues will be visible.
:::

You can use domain objects as clues as well:

```kotlin
data class HttpResponse(val status: Int, val body: String)

val response = HttpResponse(404, "the content")

response.asClue {
it.status shouldBe 200
it.body shouldBe "the content"
}
```

Would output:

```
HttpResponse(status=404, body=the content)
Expected :200
Actual :404
```

:::note
Kotest considers all `() -> Any?` clues as lazy clues, and would compute them and use `.toString()` on the resulting value
instead of calling `.toString()` on the function itself.
In most cases, it should do exactly what you need, however, if clue object implements `() -> Any?`, and you want
using `clue.toString()`, then consider wrapping the clue manually as `{ clue.toString() }.asClue { ... }`.
:::

## Nested clues

Clues can be nested, and they all will be visible in the failed assertion messages:

```kotlin
{ "Verifying user_id=${user.name}" }.asClue {
"email_confirmed should be false since we've just created the user".asClue {
user.emailConfirmed shouldBe false
}
"login".asClue {
user.login shouldBe "sksamuel"
}
}
```

The failure might look like

```
Verifying user_id=42
email_confirmed should be false since we've just created the user
<true> should equal <false>
```
52 changes: 52 additions & 0 deletions documentation/versioned_docs/version-5.9/assertions/collections.md
View file
@@ -0,0 +1,52 @@
---
id: collections
title: Collection Matchers
slug: collection-matchers.html
sidebar_label: Collections
---

This page describes the rich assertions (matchers) that are available for Collection, Iterable and Array types.

Also, see [inspectors](inspectors.md) which are useful ways to test multiple elements in a collection.


| Collections | |
|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `collection.shouldBeEmpty()` | Asserts that the collections has zero elements. |
| `collection.shouldBeUnique()` | Asserts that all the elements of the collection are distinct using the natural equals of the elements. |
| `collection.shouldBeUnique(comparator)` | Asserts that all the elements of the collection are distinct by comparing elements using the given `comparator`. |
| `collection.shouldContain(element)` | Asserts that the collection contains the given element. |
| `collection.shouldContainAll(e1, e2, ..., en)` | Asserts that the collection contains all the elements listed, where order is not important. Ie, element 2 can be in the collection before element 1. |
| `collection.shouldContainDuplicates()` | Asserts that the collection contains at least one duplicate element. |
| `collection.shouldContainExactly()` | Assert that a collection contains exactly the given values and nothing else, in order. |
| `collection.shouldContainExactlyInAnyOrder()` | Assert that a collection contains exactly the given values and nothing else, in _any_ order. |
| `collection.shouldContainAllInAnyOrder()` | Assert that a collection contains all the given values, in _any_ order. |
| `collection.shouldContainNoNulls()` | Asserts that the collection contains no null elements, or is empty. |
| `collection.shouldContainNull()` | Asserts that the collection contains at least one null element. |
| `collection.shouldContainOnlyNulls()` | Asserts that the collection contains only null elements, or is empty. |
| `collection.shouldContainAllIgnoringFields()` | Asserts that the collection contains all the elements listed ignoring one or more fields. |
| `collection.shouldHaveSingleElement(element)` | Asserts that the collection only contains a single element and that that element is the given one. |
| `collection.shouldHaveSingleElement { block }` | Asserts that the collection contains a single element by a given predicate. |
| `collection.shouldHaveSize(length)` | Asserts that the collection is exactly the given length. |
| `collection.shouldBeSingleton()` | Asserts that the collection contains only one element. |
| `collection.shouldBeSingleton { block }` | Asserts that the collection only one element, and then, runs the block with this element. |
| `collection.shouldHaveLowerBound(element)` | Asserts that the given element is smaller or equal to every element of the collection. Works only for elements that implement Comparable. |
| `collection.shouldHaveUpperBound(element)` | Asserts that the given element is larger or equal to every element of the collection. Works only for elements that implement Comparable. |
| `collection.shouldBeSmallerThan(col)` | Asserts that the collection is smaller than the other collection. |
| `collection.shouldBeLargerThan(col)` | Asserts that the collection is larger than the other collection. |
| `collection.shouldBeSameSizeAs(col)` | Asserts that the collection has the same size as the other collection. |
| `collection.shouldHaveAtLeastSize(n)` | Asserts that the collection has at least size n. |
| `collection.shouldHaveAtMostSize(n)` | Asserts that the collection has at most size n. |
| `list.shouldBeSorted()` | Asserts that the list is sorted. |
| `list.shouldBeSortedBy { transform }` | Asserts that the list is sorted by the value after applying the transform. |
| `list.shouldContainInOrder(other)` | Asserts that this list contains the given list in order. Other elements may appear either side of the given list. |
| `list.shouldExistInOrder({ element }, ...)` | Asserts that this list contains elements matching the predicates in order. Other elements may appear around or between the elements matching the predicates. |
| `list.shouldHaveElementAt(index, element)` | Asserts that this list contains the given element at the given position. |
| `list.shouldStartWith(lst)` | Asserts that this list starts with the elements of the given list, in order. |
| `list.shouldEndWith(lst)` | Asserts that this list ends with the elements of the given list, in order. |
| `iterable.shouldMatchEach(assertions)` | Iterates over this list and the assertions and asserts that each element of this list passes the associated assertion. Fails if size of the collections mismatch. |
| `iterable.shouldMatchInOrder(assertions)` | Asserts that there is a subsequence of this iterator that matches the assertions in order, with no gaps allowed. |
| `iterable.shouldMatchInOrderSubset(assertions)` | Asserts that there is a subsequence (possibly with gaps) that matches the assertions in order. |
| `value.shouldBeOneOf(collection)` | Asserts that a specific instance is contained in a collection. |
| `collection.shouldContainAnyOf(collection)` | Asserts that the collection has at least one of the elements in `collection` |
| `value.shouldBeIn(collection)` | Asserts that an object is contained in collection, checking by value and not by reference. |
53 changes: 53 additions & 0 deletions documentation/versioned_docs/version-5.9/assertions/compiler.md
View file
@@ -0,0 +1,53 @@
---
id: compiler
title: Compiler Matchers
slug: compiler-matchers.html
sidebar_label: Compiler
---


The ```kotest-assertions-compiler``` extension provides matchers to assert that given kotlin code snippet compiles or not.
This extension is a wrapper over [kotlin-compile-testing](https://github.com/tschuchortdev/kotlin-compile-testing) and provides following matchers

* String.shouldCompile()
* String.shouldNotCompile()
* File.shouldCompile()
* File.shouldNotCompile()

To add the compilation matcher, add the following dependency to your project

```groovy
testImplementation("io.kotest.extensions:kotest-assertions-compiler:${version}")
```

Usage:
```kotlin
class CompilationTest: StringSpec() {
init {
"shouldCompile test" {
val codeSnippet = """ val aString: String = "A valid assignment" """.trimMargin()

codeSnippet.shouldCompile()
File("SourceFile.kt").shouldCompile()
}

"shouldNotCompile test" {
val codeSnippet = """ val aInteger: Int = "A invalid assignment" """.trimMargin()

codeSnippet.shouldNotCompile()
File("SourceFile.kt").shouldNotCompile()
}
}
}
```

During checking of code snippet compilation the classpath of calling process is inherited, which means any dependencies which are available in calling process will also be available while compiling the code snippet.



Matchers that verify if a given piece of Kotlin code compiles or not

| Matcher | Description |
| ---------- | --- |
| `string.shouldCompile()` | Asserts that the string is a valid Kotlin code. |
| `file.shouldCompile()` | Asserts that the file contains valid Kotlin code. |

0 comments on commit 879e562

Please sign in to comment.