assert-str 0.3.0

Macros for asserting multiline strings
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

# assert-str

[![build status](https://github.com/AnderEnder/assert-str/workflows/Build/badge.svg)](https://github.com/AnderEnder/assert-str/actions)
[![codecov](https://codecov.io/gh/AnderEnder/assert-str/branch/master/graph/badge.svg)](https://codecov.io/gh/AnderEnder/assert-str)
[![crates.io](https://img.shields.io/crates/v/assert-str.svg)](https://crates.io/crates/assert-str)

Macros for asserting multiline strings.

`assert-str` provides drop-in alternatives to `assert_eq!` / `assert_ne!` for
comparing multiline `&str` / `String` values while ignoring differences that are
usually noise: OS-specific line endings (`\n` vs `\r\n`), indentation, and other
whitespace. It is handy for comparing text generated on different platforms, or
a prettified JSON/XML/HTML value against its compact form. The left and right
operands may be different types (`&str`, `String`, `&String`, …).

No dependencies · no `unsafe` code · MSRV 1.85 (edition 2024).

## Usage

Add the dependency — usually as a dev-dependency, since these are test helpers:

```toml
[dev-dependencies]
assert-str = "0.3"
```

Import the macros:

```rust
use assert_str::{assert_str_eq, assert_str_ne};
use assert_str::{assert_str_trim_eq, assert_str_trim_ne};
use assert_str::{assert_str_trim_all_eq, assert_str_trim_all_ne};
// …or simply:
use assert_str::*;
```

## Macros

Each `*_eq!` macro asserts equality and each `*_ne!` macro asserts inequality
**after** applying a normalization. All of them treat `\n` and `\r\n` as
equivalent, and — like the standard `assert_eq!` — accept an optional trailing
format message.

| Macros | Normalization applied before comparing |
| ------ | --------------------------------------- |
| `assert_str_eq!` / `assert_str_ne!` | Line endings only (`\n` ≡ `\r\n`). |
| `assert_str_trim_eq!` / `assert_str_trim_ne!` | Line endings, plus each line is trimmed and blank lines are dropped. |
| `assert_str_trim_all_eq!` / `assert_str_trim_all_ne!` | All whitespace removed, anywhere in the string. |

```rust
#[test]
fn trimmed_string_assertions() {
    // Ignores per-line leading/trailing whitespace and normalizes line endings.
    assert_str_trim_eq!(
        "<html>\t \n\t<head> \n\t</head></html>",
        "<html>\r\n<head>\r\n</head></html>",
        "Responses should be equal"
    );

    // Removes all whitespace — compare a pretty-printed value to its minified form.
    assert_str_trim_all_eq!(
        "<html>\t \n\t<head> \n\t</head></html>",
        "<html><head></head></html>",
        "Responses should be equal"
    );
}
```

## Reusable normalization

The same normalization the macros use is also available as a plain function, so
you can reuse it outside of assertions — for example to pre-process snapshots,
build whitespace-insensitive hash/sort keys, or write your own comparison:

```rust
use assert_str::{normalize, Mode};

assert_eq!(normalize("a\r\nb", Mode::Lines), "a\nb");
assert_eq!(normalize("  a \n\n b ", Mode::Trim), "a\nb");
assert_eq!(normalize("a b\nc", Mode::TrimAll), "abc");
```

`Mode` is `#[non_exhaustive]`, so more normalization modes may be added in
future releases without a breaking change.

## Compatibility

`assert_str_trim_all_*` changed in **0.3.0**: it now removes all whitespace
*including within a line* (matching its documented purpose). If intra-line
whitespace should stay significant, use `assert_str_trim_eq!` instead. See
[`CHANGELOG.md`](CHANGELOG.md) for details.

## License

Licensed under either of [Apache-2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT) at
your option.