test-better-matchers 0.2.1

Matcher trait, standard matchers, and the `check!` macro for the test-better testing library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

//! `test-better-matchers`: the `Matcher` trait and standard matchers.
//!
//! A matcher is a reusable, composable expectation. This crate provides:
//!
//! - [`Matcher`], the trait every matcher implements, and its structured
//!   result types [`MatchResult`] and [`Mismatch`];
//! - [`Description`], the composable account of what a matcher expects;
//! - the primitive matchers [`eq`], [`ne`], [`lt`], [`le`], [`gt`], [`ge`],
//!   [`is_true`], [`is_false`], and the test fixtures [`always_matches`] and
//!   [`never_matches`];
//! - the logical combinators [`not`], [`all_of`], and [`any_of`];
//! - the [`Option`]/[`Result`] matchers [`some`], [`none`], [`ok`], and
//!   [`err`];
//! - the collection matchers [`have_len`], [`is_empty`], [`is_not_empty`],
//!   [`contains`], [`contains_all`], [`contains_in_order`], [`every`], and
//!   [`at_least_one`], generic over the [`Sequence`] trait;
//! - the string matchers [`contains_str`], [`starts_with`], [`ends_with`], and
//!   (behind the `regex` feature) `matches_regex`;
//! - the numeric matchers [`close_to`], [`between`], [`is_nan`], and
//!   [`is_finite`], generic over the sealed [`Float`] trait;
//! - the [`predicate`] escape hatch, a matcher built from an arbitrary
//!   named Boolean-returning closure;
//! - the [`define_matcher!`](crate::define_matcher) macro, the declarative
//!   shortcut for the common custom-matcher case;
//! - the [`check!`](crate::check) macro and its [`Subject`] type, the entry point for an
//!   assertion; when the subject is a [`Future`], the `resolves_to` method
//!   awaits it and matches its output, and `completes_within` awaits it
//!   under a time limit (the latter behind a runtime feature: `tokio`,
//!   `async-std`, or `smol`); `matches_snapshot` compares a
//!   [`Display`](std::fmt::Display) value against a file-backed snapshot, and
//!   `matches_inline_snapshot` against a snapshot literal in the test source
//!   (`test-better-snapshot`); the `*_with` variants of each run a
//!   `Redactions` set over the value first, stabilizing non-deterministic
//!   content (UUIDs, timestamps) before the comparison;
//! - [`eventually`] and [`eventually_blocking`], which retry a `bool` probe on
//!   an exponential [`Backoff`] schedule until it passes or a deadline is hit,
//!   replacing `sleep + assert` flakiness;
//! - [`soft`] and its [`SoftAsserter`]/[`SoftScope`], which collect several
//!   failures in one test run instead of stopping at the first, with nestable
//!   context sub-scopes;
//! - the line-oriented [`diff_lines`] renderer, behind the default `diff`
//!   feature.
//!
//! Later iterations add the remaining matcher combinators.

mod collections;
mod combinators;
mod define;
mod description;
#[cfg(feature = "diff")]
mod diff;
mod fixtures;
mod matcher;
mod numeric;
mod option_result;
mod predicate;
mod primitives;
mod soft;
mod strings;
mod subject;

pub use collections::{
    ContainsAll, Items, Sequence, at_least_one, contains, contains_all, contains_in_order, every,
    have_len, is_empty, is_not_empty, items,
};
pub use combinators::{MatcherTuple, all_of, any_of, not};
pub use description::Description;
#[cfg(feature = "diff")]
pub use diff::diff_lines;
pub use fixtures::{always_matches, never_matches};
pub use matcher::{MatchResult, Matcher, Mismatch};
pub use numeric::{Float, between, close_to, is_finite, is_nan};
pub use option_result::{err, none, ok, some};
pub use predicate::predicate;
pub use primitives::{eq, ge, gt, is_false, is_true, le, lt, ne};
pub use soft::{SoftAsserter, SoftScope, soft};
#[cfg(feature = "regex")]
pub use strings::matches_regex;
pub use strings::{contains_str, ends_with, starts_with};
pub use subject::Subject;
// Re-exported from `test-better-async`: `Elapsed` and `RuntimeAvailable` appear
// in `Subject::completes_within`'s signature, and the `eventually` family is
// the polling counterpart to the timeout assertion.
pub use test_better_async::{
    Backoff, Elapsed, RuntimeAvailable, eventually, eventually_blocking, eventually_blocking_with,
    eventually_with,
};
// `check!` and `define_matcher!` are `#[macro_export]`, so they already live
// at the crate root.