## Tricks and tips for using Strikt assertions

Strikt is very powerful, however it is sometimes hard to find particular methods. This is a handy cheatsheet.

### Basics

#### Top-level assertions

`expect`, `expectThat`, `expectCatching` and `expectThrows`

#### Narrowing

Non-null assertion and assertions on narrowed type:

```kotlin
expectThat(subject)
  .isNotNull()
  .and {
//  ...
  }
```

Use `.isNotNull()` to narrow nullability and `.isA<Int>()` to narrow to specific type.

#### Grouping

Use `.and { }` to group assertions on a subtree

#### Chained Assertions

These fail fast:

```kotlin
expectThat(subject)
  .isA<String>()
  .hasLength(1)
```

#### Block Assertions

Will run all assertions in the block before failing:

```kotlin
expectThat(subject) {
  isA<String>()
  hasLength(1)
}
```

or as a subblock

```kotlin
.and(subject) {
  isA<String>()
  hasLength(1)
}
```

#### Asserting Different Subjects

```kotlin
expect {
  that(varOne)
    .isA<String>()
    .hasLength(1)
  that(varTwo) {
    isLessThan(1L)
}
```

### Sub-trees

Using get to assert sub-properties

```kotlin
expectThat(subject) {
  get { name }.isEqualTo("Ziggy")
  get { birthDate.year }.isEqualTo(1971)
}
```
or with property/method references:
```kotlin
expectThat(subject) {
  get(Person::name).isEqualTo("David")
  get(Person::birthDate).get(LocalDate::getYear).isEqualTo(1947)
}
```
or as separate assertions
```kotlin
expect {
  that(person.name).isEqualTo("David")
  that(person.birthDate.year).isEqualTo(1947)
}
```

#### Traversals and Modifers

Combine these with asserts to traverse to different objects or modify the object under test:

* CharSequence `.trim()` : trims a string
* File `.toPath()` : returns the file path string
* File `.lines()` : returns contents of file as a collection of lines
* File `.text()` : returns contents of file as text
* Iterable `.map()` : allows assertions to be mapped to each collection member
* Iterable `.first()` : returns first element
* Iterable `.first { predicate }` : returns first matching element
* Iterable `.single()` : returns single element
* Iterable `.last()` : returns last element
* Iterable `.flatMap()` : Flattens nested collections
* Iterable `.filter { predicate }` : Filters matching elements
* Iterable `.filterNot { predicate }` : Filters non-matching elements
* Iterable `.filterIsInstance<R>()` : Filters for matching instance types
* Iterable `.get(n)` : returns element n
* Iterable `.get(range)` : returns elements in range
* Map `.get(key)` : returns element for key
* Map `.getValue(key)` : returns element for key (asserts for existence)
* Optional `.toNullable()` : returns kotlin nullable type from Java Optional
* Path `.resolve(other)` : returns the combined paths
* Path `.toFile()` : returns file for path
* Path `.allBytes()` : returns bytes of all files on path???
* Path `.allLines()` : returns lines of all files on path???
* Path `.allLines(charset)` : returns lines of all files on path converted using charset???

### Collections

Mapping elements of exceptions:
```kotlin
expectThat(subject)
  .map(Person::name)
  .containsExactly("David", "Ziggy", "Aladdin", "Jareth")
```
(See traversals, above, for more options)


#### Asserting contents

`expectThat()` with `.all` / `.any` / `.none`

### Failures

Checking that a block throws an exception:

```kotlin
expectCatching { identifyHotdog("hamburger") }
  .failed()
  .isA<NotHotdogException>()
```

or

```kotlin
expect {
  catching { identifyHotdog("hamburger") }
    .failed()
    .isA<NotHotdogException>()
}
```

or

```kotlin
expectThrows<NotHotdogException> {
  identifyHotdog("hamburger")
}
```

Checking that a block **does not** throw an exception:

```kotlin
expectCatching { identifyHotdog("hotdog") }
  .succeeded()
```