# Matchers

<!-- Generated by mise-tasks/docs/catalog. Do not edit. -->

Every public method on `Expectation`, grouped by the type of the value
under test. Methods with a return type navigate: they return an
expectation on a part of the value.

The examples come from the tests, so they compile and pass. `fails` and
`parse_number` are small helpers in the tests: `fails(message)` raises a
`Failure`, and `parse_number(text)` raises a `ParseError` for text that
is not a number.

## Any value

| Method | Description | Example |
|---|---|---|
| `to_be_equivalent_to` | Assert the actual value is equivalent to `expected`: the two values are compared field by field, through what their `Debug` output shows. The type does not need `Eq`. | `@expect.expect((1.0, [2.0])).to_be_equivalent_to((1.05, [1.95]), tolerance=0.1)` |
| `because` → `Expectation[T]` | Give the reason why the assertion must hold. A failure shows the reason on a `Because` line: `expect(retries).because("the client retries three times").to_equal(3)`. | `@expect.expect(1).because("never fails").to_equal(1)` |
| `not` → `Expectation[T]` | Negate the next matcher. | `@expect.expect(3).not().to_equal(5)` |
| `to_equal` | Assert the actual value equals the expected value. | `@expect.expect(42).to_equal(42)` |
| `to_not_equal` | Assert the actual value does not equal the given value. | `@expect.expect(3).to_not_equal(5)` |
| `to_satisfy` | Assert the actual value satisfies a predicate. | `@expect.expect(4).to_satisfy(x => x % 2 == 0)` |
| `to` | Assert the actual value matches `matcher`. | `@expect.expect(3).to(@expect.equal_to(3))` |
| `get` → `Expectation[U]` | Apply `f` to the value under test and return an expectation on the result. `name` extends the label, so failures show the path to the value. Cannot be used after `not()`. | `@expect.expect([ada]).single().get("name", u => u.name).to_equal("Ada")` |
| `all` | Run several matchers on the same value: `expect(age).all(it => { it.to_be_greater_than(0); it.to_be_less_than(150) })`. | `@expect.expect(3).all(it => it.to_be_positive())` |
| `to_be_one_of` | Assert the actual value equals one of `values`. | `@expect.expect(2).to_be_one_of([1, 2, 3])` |
| `to_be_in` | Assert the actual value is in `set`. | `@expect.expect(2).to_be_in(Set([1, 2, 3]))` |

## Ordered values

| Method | Description | Example |
|---|---|---|
| `to_be_greater_than` | Assert the actual value is greater than the given value. | `@expect.expect(5).to_be_greater_than(3)` |
| `to_be_greater_than_or_equal` | Assert the actual value is greater than or equal to the given value. | `@expect.expect(5).to_be_greater_than_or_equal(5)` |
| `to_be_less_than` | Assert the actual value is less than the given value. | `@expect.expect(3).to_be_less_than(5)` |
| `to_be_less_than_or_equal` | Assert the actual value is less than or equal to the given value. | `@expect.expect(5).to_be_less_than_or_equal(5)` |
| `to_be_between` | Assert the actual value is between `low` and `high`. Both bounds are inclusive unless you set `low_inclusive` or `high_inclusive` to `false`. | `@expect.expect(5).to_be_between(1, 5)` |

## Numbers

| Method | Description | Example |
|---|---|---|
| `to_be_positive` | Assert the actual number is greater than zero. | `@expect.expect(3).to_be_positive()` |
| `to_be_negative` | Assert the actual number is less than zero. | `@expect.expect(-3L).to_be_negative()` |
| `to_be_zero` | Assert the actual number is zero. For floating-point numbers, `-0.0` is zero too. | `@expect.expect(0.0).to_be_zero()` |

## Floating-point numbers

| Method | Description | Example |
|---|---|---|
| `to_be_nan` | Assert the actual value is NaN. | `@expect.expect(0.0 / 0.0).to_be_nan()` |
| `to_be_finite` | Assert the actual value is finite: not NaN and not infinite. | `@expect.expect(1.0).to_be_finite()` |
| `to_be_close_to` | Assert the actual value is close to `expected`, within an absolute, relative or ULP tolerance. NaN is never close to any value. | `@expect.expect(0.1 + 0.2).to_be_close_to(0.3)` |

## Booleans

| Method | Description | Example |
|---|---|---|
| `to_be_true` | Assert the actual boolean value is true. | `@expect.expect(true).to_be_true()` |
| `to_be_false` | Assert the actual boolean value is false. | `@expect.expect(false).to_be_false()` |

## Options

| Method | Description | Example |
|---|---|---|
| `to_be_some` | Assert the actual Option value is Some. | `@expect.expect(Some(42)).to_be_some()` |
| `to_be_none` | Assert the actual Option value is None. | `@expect.expect((None : Int?)).to_be_none()` |
| `unwrap_some` → `Expectation[T]` | Assert the actual Option value is Some, and return an expectation on the inner value. Cannot be used after `not()`. | `@expect.expect(Some(42)).unwrap_some().to_equal(42)` |

## Results

| Method | Description | Example |
|---|---|---|
| `to_be_ok` | Assert the actual Result value is Ok. | `@expect.expect((Ok(1) : Result[Int, String])).to_be_ok()` |
| `to_be_err` | Assert the actual Result value is Err. | `@expect.expect((Err("boom") : Result[Int, String])).to_be_err()` |
| `unwrap_ok` → `Expectation[T]` | Assert the actual Result value is Ok, and return an expectation on the inner value. Cannot be used after `not()`. | `@expect.expect((Ok(1) : Result[Int, String])).unwrap_ok().to_equal(1)` |
| `unwrap_err` → `Expectation[E]` | Assert the actual Result value is Err, and return an expectation on the error. Cannot be used after `not()`. | `@expect.expect((Err("boom") : Result[Int, String])).unwrap_err().to_equal("boom")` |

## Strings

| Method | Description | Example |
|---|---|---|
| `to_contain` | Assert a String contains the given substring. | `@expect.expect("hello world").to_contain("world")` |
| `to_start_with` | Assert a String starts with the given prefix. | `@expect.expect("hello world").to_start_with("hello")` |
| `to_end_with` | Assert a String ends with the given suffix. | `@expect.expect("hello world").to_end_with("world")` |
| `to_match` | Assert a String matches a regular expression. The match is a search: it can start anywhere in the string. Use `^` and `$` to match the whole string. | `@expect.expect("abc").to_match("^a.c$")` |
| `to_equal_ignoring_case` | Assert a String equals `expected` when case is ignored. | `@expect.expect("Hello").to_equal_ignoring_case("hELLO")` |
| `to_equal_ignoring_whitespace` | Assert a String equals `expected` when all whitespace is removed from both. Whitespace is every character for which `Char::is_whitespace` is true, such as spaces, tabs and newlines. | `@expect.expect(" a b\n\tc ").to_equal_ignoring_whitespace("abc")` |
| `to_be_blank` | Assert a String is empty or holds only whitespace. | `@expect.expect("").to_be_blank()` |
| `to_contain_times` | Assert a String contains `text` exactly `count` times. Occurrences do not overlap: `"aaaa"` contains `"aa"` twice. | `@expect.expect("abc").to_contain_times("x", 0)` |
| `to_contain_substrings_in_order` | Assert a String contains the given parts in this order, with other text allowed between them. | `@expect.expect("one two three").to_contain_substrings_in_order(["one", "three"])` |
| `to_match_fully` | Assert the whole String matches a regular expression. Unlike `to_match`, the match must start at the start of the string and end at its end. | `@expect.expect("ab").to_match_fully("a\|ab")` |

## Chars

| Method | Description | Example |
|---|---|---|
| `to_be_digit` | Assert a Char is an ASCII digit, `0` to `9`. | `@expect.expect('7').to_be_digit()` |
| `to_be_letter` | Assert a Char is an ASCII letter, `a` to `z` or `A` to `Z`. | `@expect.expect('a').to_be_letter()` |
| `to_be_whitespace` | Assert a Char is whitespace, as `Char::is_whitespace` defines it. This includes Unicode whitespace, not only ASCII. | `@expect.expect(' ').to_be_whitespace()` |
| `to_be_upper_case` | Assert a Char is an ASCII upper-case letter, `A` to `Z`. | `@expect.expect('A').to_be_upper_case()` |
| `to_be_lower_case` | Assert a Char is an ASCII lower-case letter, `a` to `z`. | `@expect.expect('a').to_be_lower_case()` |

## Collections with a length

| Method | Description | Example |
|---|---|---|
| `to_be_empty` | Assert the actual value is empty. | `@expect.expect("").to_be_empty()` |
| `to_have_length` | Assert the actual value has the given length. | `@expect.expect(b"abc").to_have_length(3)` |

## Arrays

| Method | Description | Example |
|---|---|---|
| `to_contain_exactly` | Assert an Array has exactly the given elements, in the same order. | `@expect.expect([1, 2, 3]).to_contain_exactly([1, 2, 3])` |
| `to_contain_only` | Assert every element of an Array is one of `expected`, and every element of `expected` appears at least once. Order and duplicates do not matter. | `@expect.expect([1, 2, 2, 3]).to_contain_only([3, 1, 2])` |
| `to_contain_in_order` | Assert an Array contains the given elements in this order, with other elements allowed between them. | `@expect.expect([1, 2, 3, 4]).to_contain_in_order([1, 3, 4])` |
| `to_start_with_elements` | Assert an Array starts with the given elements. | `@expect.expect([1, 2, 3]).to_start_with_elements([1, 2])` |
| `to_end_with_elements` | Assert an Array ends with the given elements. | `@expect.expect([1, 2, 3]).to_end_with_elements([2, 3])` |
| `to_any_satisfy` | Assert at least one element of an Array satisfies a predicate. | `@expect.expect([1, 2, 3]).to_any_satisfy(x => x > 2)` |
| `to_none_satisfy` | Assert no element of an Array satisfies a predicate. | `@expect.expect([1, 2, 3]).to_none_satisfy(x => x > 3)` |
| `to_have_count_satisfying` | Assert exactly `count` elements of an Array satisfy a predicate. | `@expect.expect([1, 2, 3, 4]).to_have_count_satisfying(2, x => x % 2 == 0)` |
| `to_contain_none_of` | Assert an Array contains none of the given values. | `@expect.expect([1, 2, 3]).to_contain_none_of([4, 5])` |
| `to_satisfy_respectively` | Run one check per element: `checks[i]` runs on the element at index `i`. The Array must have one element for each check. A failed check reports the index in its path, such as `items[1]`. Cannot be used after `not()`. | `@expect.expect([1]).to_satisfy_respectively([it => it.to_equal(1)])` |
| `to_be_sorted` | Assert an Array is sorted in ascending order. Equal neighbors are allowed. | `@expect.expect([1, 2, 2, 3]).to_be_sorted()` |
| `to_be_sorted_by` | Assert an Array is sorted in ascending order of `key`. Equal keys are allowed. | `@expect.expect(["a", "bb", "ccc"]).to_be_sorted_by(s => s.length())` |
| `to_have_no_duplicates` | Assert no two elements of an Array are equal. | `@expect.expect([1, 2, 3]).to_have_no_duplicates()` |
| `to_contain_element` | Assert an Array contains the given element. | `@expect.expect([1, 2, 3]).to_contain_element(2)` |
| `to_contain_all` | Assert an Array contains every one of the given elements. Negated, it asserts that at least one element is missing. | `@expect.expect([1, 2, 3]).to_contain_all([3, 1])` |
| `to_equal_ignoring_order` | Assert an Array has the same elements as `expected`, in any order. Duplicates count: `[1, 1, 2]` does not match `[1, 2, 2]`. | `@expect.expect([3, 1, 2]).to_equal_ignoring_order([1, 2, 3])` |
| `to_all_satisfy` | Assert every element of an Array satisfies a predicate. Negated, it asserts that at least one element does not. | `@expect.expect([2, 4, 6]).to_all_satisfy(x => x % 2 == 0)` |
| `to_contain_element_matching` | Assert at least one element of an Array matches `matcher`. A failure shows why each element does not match. | `@expect.expect([1, 2, 3]).to_contain_element_matching(@expect.equal_to(2))` |
| `element` → `Expectation[T]` | Assert an Array has an element at `index`, and return an expectation on it. Cannot be used after `not()`. | `@expect.expect([10, 20, 30]).element(1).to_equal(20)` |
| `first` → `Expectation[T]` | Assert an Array is not empty, and return an expectation on its first element. Cannot be used after `not()`. | `@expect.expect([1, 2, 3]).first().to_equal(1)` |
| `last` → `Expectation[T]` | Assert an Array is not empty, and return an expectation on its last element. Cannot be used after `not()`. | `@expect.expect([1, 2, 3]).last().to_equal(3)` |
| `single` → `Expectation[T]` | Assert an Array has exactly one element, and return an expectation on it. Cannot be used after `not()`. | `@expect.expect([ada]).single().get("name", u => u.name).to_equal("Ada")` |

## Maps

| Method | Description | Example |
|---|---|---|
| `to_contain_key` | Assert a Map contains the given key. | `@expect.expect({ "a": 1 }).to_contain_key("a")` |
| `to_contain_value` | Assert a Map contains the given value under any key. | `@expect.expect({ "a": 1 }).to_contain_value(1)` |
| `to_contain_entry` | Assert a Map contains `key` with the given value. | `@expect.expect({ "a": 1, "b": 2 }).to_contain_entry("a", 1)` |
| `to_contain_entries` | Assert a Map contains every entry of `expected`. Other entries are allowed. | `@expect.expect({ "a": 1, "b": 2 }).to_contain_entries({ "b": 2 })` |
| `value_at` → `Expectation[V]` | Assert a Map contains `key`, and return an expectation on its value. Cannot be used after `not()`. | `@expect.expect({ "http": 80 }).value_at("http").to_equal(80)` |

## Pairs

| Method | Description | Example |
|---|---|---|
| `fst` → `Expectation[A]` | Return an expectation on the first part of a pair. Cannot be used after `not()`. | `@expect.expect((1, "one")).fst().to_equal(1)` |
| `snd` → `Expectation[B]` | Return an expectation on the second part of a pair. Cannot be used after `not()`. | `@expect.expect((1, "one")).snd().to_equal("one")` |

## Json

| Method | Description | Example |
|---|---|---|
| `at` → `Expectation[Json]` | Return an expectation on the value at `path`, such as `items[0].name`. Keys are separated by `.`, and array indices are in brackets. Fails when the path does not exist. Cannot be used after `not()`. | `@expect.expect(({ "a": [{ "b": 1 }] } : Json)).at("a[0].b").to_equal(1)` |
| `to_contain_json` | Assert a Json value contains `expected`: every key of an object in `expected` must exist with a value that contains the expected value, at every depth. Other keys are allowed. Arrays must have the same length, and each element must contain the expected element. Numbers compare by value. | `@expect.expect(({ "id": 7, "qty": 2 } : Json)).to_contain_json({ "id": 7 })` |

## Functions (`expect_call`)

| Method | Description | Example |
|---|---|---|
| `to_return` → `Expectation[T]` | Assert the function returns without an error, and return an expectation on the returned value. Cannot be used after `not()`. | `@expect.expect_call(() => @string.parse_int("42")).to_return().to_equal(42)` |
| `to_raise_error` → `Expectation[Error]` | Assert the function raises an error, and return an expectation on the error. Use `message()` to check the error text. Cannot be used after `not()`. | `@expect.expect_call(() => fails("x")).to_raise_error().message().to_equal("x")` |
| `to_raise_matching` | Assert the function raises an error that satisfies `predicate`. Use an `is` pattern to check the error type: `expect_call(() => parse("x")).to_raise_matching(e => e is ParseError::Invalid(_))`. | `@expect.expect_call(() => parse_number("x")).to_raise_matching(e => e is Invalid(_))` |
| `to_raise` | Assert the function raises an error. Create the expectation with `expect_call`. | `@expect.expect_call(() => @string.parse_int("x")).to_raise()` |

## Errors

| Method | Description | Example |
|---|---|---|
| `message` → `Expectation[String]` | Return an expectation on the message of an error. For a `Failure` raised by `fail`, the message does not include the source location. | `@expect.expect_call(() => fails("x")).to_raise_error().message().to_equal("x")` |

## Matcher values

Functions that return a `Matcher[T]`. Run one with `to`, or pass it to
another matcher such as `to_contain_element_matching`.

| Function | Description | Example |
|---|---|---|
| `equal_to` | A matcher for values equal to `expected`. | `@expect.expect(3).to(@expect.equal_to(3))` |
| `satisfying` | A matcher for values that satisfy `predicate`. | `@expect.expect(4).to(@expect.satisfying(x => x % 2 == 0, description="even"))` |
| `all_of` | A matcher for values that match every one of `matchers`. A mismatch names each part that does not match. | `@expect.expect(4).to(@expect.all_of([@expect.equal_to(4), @expect.is_not(@expect.equal_to(5))]))` |
| `any_of` | A matcher for values that match at least one of `matchers`. | `@expect.expect(8).to(@expect.any_of([@expect.equal_to(1), @expect.equal_to(8)]))` |
| `is_not` | A matcher for values that do not match `matcher`. | `@expect.expect(3).to(@expect.is_not(@expect.equal_to(4)))` |
| `field` | A matcher that applies `f` to the value and checks the result with `matcher`: `field("name", u => u.name, equal_to("Ada"))`. | `@expect.expect((1, "a")).to(@expect.field("first", p => p.0, @expect.equal_to(1)))` |
| `matching` | A matcher that runs method matchers on the value: `matching("an adult", it => it.to_be_greater_than_or_equal(18))`. | `@expect.expect(3).to(@expect.matching("positive", it => it.to_be_positive()))` |