should_match 0.1.0

Pass a test if the output matches a pattern.
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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

# `should_match`

[![GitHub License](https://img.shields.io/github/license/PRO-2684/should_match?logo=opensourceinitiative)](https://github.com/PRO-2684/should_match/blob/main/LICENSE)
[![Crates.io Version](https://img.shields.io/crates/v/should_match?logo=rust)](https://crates.io/crates/should_match)
[![Crates.io Total Downloads](https://img.shields.io/crates/d/should_match?logo=rust)](https://crates.io/crates/should_match)
[![docs.rs](https://img.shields.io/docsrs/should_match?logo=rust)](https://docs.rs/should_match)

Pass a test if the output matches a pattern.

## Features

This library is **lightweight** and **fast**, since it is based on `macro_rules`, with zero dependencies.

## Setup

This crate is primarily intended for use in tests, so add it to your `dev-dependencies` instead of `dependencies`:

```shell
cargo add --dev should_match
```

Recommended to work with [`macro_rules_attr`](https://crates.io/crates/macro_rules_attr), which provides nice syntactic sugar:

```shell
cargo add --dev macro_rules_attr should_match
```

## The `should_match` macro

### With `macro_rules_attr`

Simply `apply` the `should_match` macro, and specify your pattern (the order of `apply` and `should_match` does not matter):

```rust
use macro_rules_attr::apply;
use should_match::should_match;

// This test will pass
#[apply(should_match, pattern = Err("error"))]
#[test]
fn test_apply_first() -> Result<(), &'static str> {
    Err("error")
}

// This test will also pass
#[test]
#[apply(should_match, pattern = Err("error"))]
fn test_apply_second() -> Result<(), &'static str> {
    Err("error")
}
```

To specify a custom panic message when it fails, pass an additional `message` argument:

```rust
# use macro_rules_attr::apply;
# use should_match::should_match;
#
#[test]
#[apply(should_match, pattern = Err(_), message = "Expected `Err`, but got `Ok`")]
fn test_with_custom_message() -> Result<(), &'static str> {
    Err("error")
}
```

### Direct usage

You can also use the `should_match` macro directly, but note that `#[test]` must be wrapped inside the macro:

```rust
use should_match::should_match;

// Without custom message
should_match! {
    #[test]
    fn test_match_direct() -> Result<(), &'static str> {
        Err("error")
    },
    pattern = Err("error")
}

// With custom message
should_match! {
    #[test]
    fn test_match_direct_custom_message() -> Result<(), &'static str> {
        Err("error")
    },
    pattern = Err("error"),
    message = "Expected `Err`, but got `Ok`"
}
```

## Shortcuts

### Predefined shortcuts

`should_match` provides some shortcuts for common patterns:

| Macro | Pattern | Message |
| --- | --- | --- |
| `should_ok` | `Ok(_)` | `` Expected `Ok`, but got `Err` `` |
| `should_err` | `Err(_)` | `` Expected `Err`, but got `Ok` `` |
| `should_none` | `None` | `` Expected `None`, but got `Some` `` |
| `should_some` | `Some(_)` | `` Expected `Some`, but got `None` `` |

An example of using `should_err`:

```rust
use macro_rules_attr::apply;
use should_match::should_err;

#[test]
#[apply(should_err)]
fn test_should_err() -> Result<(), &'static str> {
    Err("error")
}
```

Other shortcuts can be used in the same way.

### Define custom shortcuts

```rust
use macro_rules_attr::apply;
use should_match::should_match;

macro_rules! should_three {(
    $(#[$attr:meta])*
    $vis:vis fn $name:ident() -> $ret_ty:ty $body:block
) => {
    ::should_match::should_match! {
        $(#[$attr])*
        $vis fn $name() -> $ret_ty $body,
        pattern = $crate::Custom::Three, // Specify the pattern
        message = "Expected `Three`, but got something else" // Specify the message (optional)
    }
}}

#[test]
#[apply(should_three)]
fn test_custom_err() -> Custom {
    Custom::Three
}
```