Version: 1.0.18

# How to Use Test Assertions

Using the `Assertion` type effectively often involves finding the best fitting function for the type of assumptions you would like to verify.

This list is intended to break up the available functions into groups based on the Result type. The types of the functions are included as well, to guide intuition.

For instance, if we wanted to assert that the fourth element of a `Vector[Int]` was a value equal to the number `5`, we would first look at assertions that operate on `Seq[A]`, with the type `Assertion[Seq[A]]`.

For this example, I would select `hasAt`, as it accepts both the position into a sequence, as well as an `Assertion[A]` to apply at that position:

``Assertion.hasAt[A](pos: Int)(assertion: Assertion[A]): Assertion[Seq[A]]``

I could start by writing:

``val xs = Vector(0, 1, 2, 3)// xs: Vector[Int] = Vector(0, 1, 2, 3)test("Fourth value is equal to 5") {  assert(xs)(hasAt(3)(???))}// res1: ZSpec[Any, Nothing] = Spec(//   caseValue = LabeledCase(//     label = "Fourth value is equal to 5",//     spec = Spec(//       caseValue = TestCase(//         test = <function1>,//         annotations = Map(zio.test.TestAnnotation@fa40ba79 -> List(SourceLocation(use-test-assertions.md,20)))//       )//     )//   )// )``

The second parameter to `hasAt` is an `Assertion[A]` that applies to the third element of that sequence, so I would look for functions that operate on `A`, of the return type `Assertion[A]`.

I could select `equalTo`, as it accepts an `A` as a parameter, allowing me to supply `5`:

``val xs = Vector(0, 1, 2, 3)// xs: Vector[Int] = Vector(0, 1, 2, 3)test("Fourth value is equal to 5") {  assert(xs)(hasAt(3)(equalTo(5)))}// res3: ZSpec[Any, Nothing] = Spec(//   caseValue = LabeledCase(//     label = "Fourth value is equal to 5",//     spec = Spec(//       caseValue = TestCase(//         test = <function1>,//         annotations = Map(zio.test.TestAnnotation@fa40ba79 -> List(SourceLocation(use-test-assertions.md,40)))//       )//     )//   )// )``

Let's say this is too restrictive, and I would prefer to assert that a value is near the number five, with a tolerance of two. This requires a little more knowledge of the type `A`, so I'll look for an assertion in the `Numeric` section. `approximatelyEquals` looks like what we want, as it permits the starting value `reference`, as well as a `tolerance`, for any `A` that is `Numeric`:

``Assertion.approximatelyEquals[A: Numeric](reference: A, tolerance: A): Assertion[A]``

Changing out `equalTo` with `approximatelyEquals` leaves us with:

``val xs = Vector(0, 1, 2, 3)// xs: Vector[Int] = Vector(0, 1, 2, 3)test("Fourth value is approximately equal to 5") {  assert(xs)(hasAt(3)(approximatelyEquals(5, 2)))}// res5: ZSpec[Any, Nothing] = Spec(//   caseValue = LabeledCase(//     label = "Fourth value is approximately equal to 5",//     spec = Spec(//       caseValue = TestCase(//         test = <function1>,//         annotations = Map(zio.test.TestAnnotation@fa40ba79 -> List(SourceLocation(use-test-assertions.md,60)))//       )//     )//   )// )``

# Values

Assertions that apply to plain values.

## Any​

Assertions that apply to `Any` value.

FunctionResult typeDescription
`anything``Assertion[Any]`Makes a new assertion that always succeeds.
`isNull``Assertion[Any]`Makes a new assertion that requires a null value.
`isSubtype[A](assertion: Assertion[A])(implicit C: ClassTag[A])``Assertion[Any]`Makes a new assertion that requires a value have the specified type.
`nothing``Assertion[Any]`Makes a new assertion that always fails.
`throwsA[E: ClassTag]``Assertion[Any]`Makes a new assertion that requires the expression to throw.

## A​

Assertions that apply to specific values.

FunctionResult typeDescription
`equalTo[A](expected: A)``Assertion[A]`Makes a new assertion that requires a value equal the specified value.
`hasField[A, B](name: String, proj: A => B, assertion: Assertion[B])``Assertion[A]`Makes a new assertion that focuses in on a field in a case class.
`isOneOf[A](values: Iterable[A])``Assertion[A]`Makes a new assertion that requires a value to be equal to one of the specified values.
`not[A](assertion: Assertion[A])``Assertion[A]`Makes a new assertion that negates the specified assertion.
`throws[A](assertion: Assertion[Throwable])``Assertion[A]`Makes a new assertion that requires the expression to throw.

## Numeric​

Assertions on `Numeric` types

FunctionResult typeDescription
`approximatelyEquals[A: Numeric](reference: A, tolerance: A)``Assertion[A]`Makes a new assertion that requires a given numeric value to match a value with some tolerance.
`isNegative[A](implicit num: Numeric[A])``Assertion[A]`Makes a new assertion that requires a numeric value is negative.
`isPositive[A](implicit num: Numeric[A])``Assertion[A]`Makes a new assertion that requires a numeric value is positive.
`isZero[A](implicit num: Numeric[A])``Assertion[A]`Makes a new assertion that requires a numeric value is zero.
`nonNegative[A](implicit num: Numeric[A])``Assertion[A]`Makes a new assertion that requires a numeric value is non negative.
`nonPositive[A](implicit num: Numeric[A])``Assertion[A]`Makes a new assertion that requires a numeric value is non positive.

## Ordering​

Assertions on types that support `Ordering`

FunctionResult typeDescription
`isGreaterThan[A](reference: A)(implicit ord: Ordering[A])``Assertion[A]`Makes a new assertion that requires the value be greater than the specified reference value.
`isGreaterThanEqualTo[A](reference: A)(implicit ord: Ordering[A])``Assertion[A]`Makes a new assertion that requires the value be greater than or equal to the specified reference value.
`isLessThan[A](reference: A)(implicit ord: Ordering[A])``Assertion[A]`Makes a new assertion that requires the value be less than the specified reference value.
`isLessThanEqualTo[A](reference: A)(implicit ord: Ordering[A])``Assertion[A]`Makes a new assertion that requires the value be less than or equal to the specified reference value.
`isWithin[A](min: A, max: A)(implicit ord: Ordering[A])``Assertion[A]`Makes a new assertion that requires a value to fall within a specified min and max (inclusive).

# Iterable

Assertions on types that extend `Iterable`, like `List`, `Seq`, `Set`, `Map`, and many others.

FunctionResult typeDescription
`contains[A](element: A)``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable contain the specified element. See Assertion.exists if you want to require an Iterable to contain an element satisfying an assertion.
`exists[A](assertion: Assertion[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable contain an element satisfying the given assertion.
`forall[A](assertion: Assertion[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable contain only elements satisfying the given assertion.
`hasFirst[A](assertion: Assertion[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable to contain the first element satisfying the given assertion.
`hasIntersection[A](other: Iterable[A])(assertion: Assertion[Iterable[A]])``Assertion[Iterable[A]]`Makes a new assertion that requires the intersection of two Iterables satisfy the given assertion.
`hasLast[A](assertion: Assertion[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable to contain the last element satisfying the given assertion.
`hasSize[A](assertion: Assertion[Int])``Assertion[Iterable[A]]`Makes a new assertion that requires the size of an Iterable be satisfied by the specified assertion.
`hasAtLeastOneOf[A](other: Iterable[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable contain at least one of the specified elements.
`hasAtMostOneOf[A](other: Iterable[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable contain at most one of the specified elements.
`hasNoneOf[A](other: Iterable[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable contain none of the specified elements.
`hasOneOf[A](other: Iterable[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable contain exactly one of the specified elements.
`hasSameElements[A](other: Iterable[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable to have the same elements as the specified Iterable, though not necessarily in the same order.
`hasSameElementsDistinct[A](other: Iterable[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable to have the same distinct elements as the other Iterable, though not necessarily in the same order.
`hasSubset[A](other: Iterable[A])``Assertion[Iterable[A]]`Makes a new assertion that requires the specified Iterable to be a subset of the other Iterable.
`isDistinct``Assertion[Iterable[Any]]`Makes a new assertion that requires an Iterable is distinct.
`isEmpty``Assertion[Iterable[Any]]`Makes a new assertion that requires an Iterable to be empty.
`isNonEmpty``Assertion[Iterable[Any]]`Makes a new assertion that requires an Iterable to be non empty.

## Ordering​

Assertions that apply to ordered `Iterable`s

FunctionResult typeDescription
`isSorted[A](implicit ord: Ordering[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable is sorted.
`isSortedReverse[A](implicit ord: Ordering[A])``Assertion[Iterable[A]]`Makes a new assertion that requires an Iterable is sorted in reverse order.

## Seq​

Assertions that operate on sequences (`List`, `Vector`, `Map`, and many others)

FunctionResult typeDescription
`endsWith[A](suffix: Seq[A])``Assertion[Seq[A]]`Makes a new assertion that requires a given string to end with the specified suffix.
`hasAt[A](pos: Int)(assertion: Assertion[A])``Assertion[Seq[A]]`Makes a new assertion that requires a sequence to contain an element satisfying the given assertion on the given position.
`startsWith[A](prefix: Seq[A])``Assertion[Seq[A]]`Makes a new assertion that requires a given sequence to start with the specified prefix.

# Either

Assertions for `Either` values.

FunctionResult typeDescription
`isLeft[A](assertion: Assertion[A])``Assertion[Either[A, Any]]`Makes a new assertion that requires a Left value satisfying a specified assertion.
`isLeft``Assertion[Either[Any, Any]]`Makes a new assertion that requires an Either is Left.
`isRight[A](assertion: Assertion[A])``Assertion[Either[Any, A]]`Makes a new assertion that requires a Right value satisfying a specified assertion.
`isRight``Assertion[Either[Any, Any]]`Makes a new assertion that requires an Either is Right.

# Exit/Cause/Throwable

Assertions for `Exit` or `Cause` results.

FunctionResult typeDescription
`containsCause[E](cause: Cause[E])``Assertion[Cause[E]]`Makes a new assertion that requires a Cause contain the specified cause.
`dies(assertion: Assertion[Throwable])``Assertion[Exit[Any, Any]]`Makes a new assertion that requires an exit value to die.
`failsCause[E](assertion: Assertion[Cause[E]])``Assertion[Exit[E, Any]]`Makes a new assertion that requires an exit value to fail with a cause that meets the specified assertion.
`fails[E](assertion: Assertion[E])``Assertion[Exit[E, Any]]`Makes a new assertion that requires an exit value to fail.
`isInterrupted``Assertion[Exit[Any, Any]]`Makes a new assertion that requires an exit value to be interrupted.
`succeeds[A](assertion: Assertion[A])``Assertion[Exit[Any, A]]`Makes a new assertion that requires an exit value to succeed.
`hasMessage(message: Assertion[String])``Assertion[Throwable]`Makes a new assertion that requires an exception to have a certain message.
`hasThrowableCause(cause: Assertion[Throwable])``Assertion[Throwable]`Makes a new assertion that requires an exception to have a certain cause.

# Try

FunctionResult typeDescription
`isFailure(assertion: Assertion[Throwable])``Assertion[Try[Any]]`Makes a new assertion that requires a Failure value satisfying the specified assertion.
`isFailure``Assertion[Try[Any]]`Makes a new assertion that requires a Try value is Failure.
`isSuccess[A](assertion: Assertion[A])``Assertion[Try[A]]`Makes a new assertion that requires a Success value satisfying the specified assertion.
`isSuccess``Assertion[Try[Any]]`Makes a new assertion that requires a Try value is Success.

# Sum type

An assertion that applies to some type, giving a method to transform the source type into another type, then assert a property on that projected type.

FunctionResult typeDescription
`isCase[Sum, Proj]( termName: String, term: Sum => Option[Proj], assertion: Assertion[Proj])``Assertion[Sum]`Makes a new assertion that requires the sum type be a specified term.

# Map

Assertions for `Map[K, V]`

FunctionResult typeDescription
`hasKey[K, V](key: K)``Assertion[Map[K, V]]`Makes a new assertion that requires a Map to have the specified key.
`hasKey[K, V](key: K, assertion: Assertion[V])``Assertion[Map[K, V]]`Makes a new assertion that requires a Map to have the specified key with value satisfying the specified assertion.
`hasKeys[K, V](assertion: Assertion[Iterable[K]])``Assertion[Map[K, V]]`Makes a new assertion that requires a Map have keys satisfying the specified assertion.
`hasValues[K, V](assertion: Assertion[Iterable[V]])``Assertion[Map[K, V]]`Makes a new assertion that requires a Map have values satisfying the specified assertion.

# String

Assertions for Strings

FunctionResult typeDescription
`containsString(element: String)``Assertion[String]`Makes a new assertion that requires a substring to be present.
`endsWithString(suffix: String)``Assertion[String]`Makes a new assertion that requires a given string to end with the specified suffix.
`equalsIgnoreCase(other: String)``Assertion[String]`Makes a new assertion that requires a given string to equal another ignoring case.
`hasSizeString(assertion: Assertion[Int])``Assertion[String]`Makes a new assertion that requires the size of a string be satisfied by the specified assertion.
`isEmptyString``Assertion[String]`Makes a new assertion that requires a given string to be empty.
`isNonEmptyString``Assertion[String]`Makes a new assertion that requires a given string to be non empty.
`matchesRegex(regex: String)``Assertion[String]`Makes a new assertion that requires a given string to match the specified regular expression.
`startsWithString(prefix: String)``Assertion[String]`Makes a new assertion that requires a given string to start with a specified prefix.

# Boolean

Assertions for Booleans

FunctionResult typeDescription
`isFalse``Assertion[Boolean]`Makes a new assertion that requires a value be false.
`isTrue``Assertion[Boolean]`Makes a new assertion that requires a value be true.

# Option

Assertions for Optional values

FunctionResult typeDescription
`isNone``Assertion[Option[Any]]`Makes a new assertion that requires a None value.
`isSome[A](assertion: Assertion[A])``Assertion[Option[A]]`Makes a new assertion that requires a Some value satisfying the specified assertion.
`isSome``Assertion[Option[Any]]`Makes a new assertion that requires an Option is Some.

# Unit

Assertion for Unit

FunctionResult typeDescription
`isUnit``Assertion[Unit]`Makes a new assertion that requires the value be unit.