A Rust unit test marked `#[should_panic]` for `split_evenly(total, 0)` still passes after its setup `unwrap()` started panicking; why, and how does `expected = "..."` catch it?
answer
- which panic satisfies the attribute
- setup runs inside the test body
- a substring of the panic message
- panic did not contain expected string
basics
~20 sA bare #[should_panic] passes on any panic in the test body, including a setup unwrap(). With expected = "parts must be positive" the harness also requires that substring in the panic message, so the wrong panic fails the test.
solid answer
~40 sA bare `#[should_panic]` passes when anything in the test body panics, so once the fixture `parse_tenths("12.5").unwrap()` started failing, the test passed on the `unwrap` panic and never reached the guard in `split_evenly`. With `#[should_panic(expected = "parts must be positive")]` the harness checks that the panic message contains that text; the unwrap message does not, so the test fails with `panic did not contain expected string` and shows both strings. The match is a case-sensitive substring test, so pick a stable fragment of the guard's message rather than its formatted value. If nothing panics, the test fails with `test did not panic as expected`. Building the inputs as literals keeps setup from panicking at all.
code
rust · 32 lines/// Parses an amount written in tenths of a cent, such as "125".
pub fn parse_tenths(s: &str) -> Result<i64, std::num::ParseIntError> {
s.trim().parse()
}
/// Splits a bill in cents into `parts` shares that differ by at most one cent.
pub fn split_evenly(total_cents: i64, parts: i64) -> Vec<i64> {
assert!(parts > 0, "parts must be positive, got {parts}");
let (base, extra) = (total_cents / parts, total_cents % parts);
(0..parts).map(|i| base + i64::from(i < extra)).collect()
}
#[cfg(test)]
mod tests {
use super::*;
// Passes, but for the wrong reason: the unwrap panics first.
#[test]
#[should_panic]
fn zero_parts_rejected_loose() {
let total = parse_tenths("12.5").unwrap();
split_evenly(total, 0);
}
// Same body; now the harness checks the panic message.
#[test]
#[should_panic(expected = "parts must be positive")]
fn zero_parts_rejected_strict() {
let total = parse_tenths("12.5").unwrap();
split_evenly(total, 0);
}
}go deeper
Know that #[should_panic] makes a test pass when it panics, and that expected checks part of the panic message.
Explain the harness rules: any panic satisfies the bare form, expected is a case-sensitive substring of a string payload, and no panic is a failure.
Diagnose the false pass: a should_panic test that passes on setup code. Fix it with a distinctive expected fragment, literal inputs and one panicking call per test.
Set the review norm that panic tests name their message, because a bare should_panic can go on passing after the guard it protects has been deleted.
## The scenario A bill-splitting function in a currency module guards its input with an assertion: ```rust pub fn split_evenly(total_cents: i64, parts: i64) -> Vec<i64> { assert!(parts > 0, "parts must be positive, got {parts}"); let (base, extra) = (total_cents / parts, total_cents % parts); (0..parts).map(|i| base + i64::from(i < extra)).collect() } ``` Its test was written as a **`#[should_panic]` unit test** that first parses a fixture amount and then calls `split_evenly(total, 0)`. During a refactor the fixture string became `"12.5"`, which `parse_tenths` rejects, so the setup's `unwrap()` now panics before `split_evenly` is ever reached. The test still passes. Someone could delete the guard entirely and the test would keep passing. Nothing in the output hints at the problem. The harness captures the output of a passing test, so the `unwrap` panic message is never shown; the summary simply reads `test tests::zero_parts_rejected_loose - should panic ... ok`. Even with a valid fixture the bare attribute would hide a deleted guard, because `total_cents / parts` with `parts == 0` panics with a division-by-zero message of its own. ## How the harness judges a `should_panic` test The test harness (libtest) catches the panic that ends a test and compares it with what the attribute asked for. Its decision table: | Attribute | Panics, message contains the text | Panics with any other message | Returns without panicking | |---|---|---|---| | none | fail | fail | pass | | `#[should_panic]` | pass | pass | fail: `test did not panic as expected` | | `#[should_panic(expected = "text")]` | pass | fail: `panic did not contain expected string` | fail: `test did not panic as expected` | The bare form accepts **any** panic raised in the test body: a setup `unwrap()`, an index out of bounds, a division by zero in a helper. That is the false pass. ## What `expected` checks The harness takes the panic payload and tests `payload.contains(expected)`: - **Substring, not equality.** `expected = "must be positive"` matches `"parts must be positive, got 0"`. - **Case-sensitive.** `"Must be positive"` does not match, because `str::contains` compares bytes exactly. - **String payloads only.** `panic!` and the assertion macros produce a `String` or `&'static str` payload. A test that panics with `std::panic::panic_any(42_u32)` fails with `expected panic with string value`, whatever the expected text. - **Three spellings.** `#[should_panic]`, `#[should_panic = "text"]` and `#[should_panic(expected = "text")]`; the last is the common one. ## Reading the failure With `expected = "parts must be positive"` on the same test body, the harness reports the mismatch and both strings: ```plaintext note: panic did not contain expected string panic message: "called `Result::unwrap()` on an `Err` value: ParseIntError { kind: InvalidDigit }" expected substring: "parts must be positive" ``` The report points straight at the real cause, the fixture. ## Hardening `should_panic` tests 1. **Always give `expected`.** A bare `#[should_panic]` cannot tell your guard from any other panic. 2. **Pick a stable, distinctive fragment.** `"parts must be positive"` survives a change to how the value is formatted; `"parts must be positive, got 0"` breaks if the wording after the comma changes. 3. **Keep the setup panic-free.** Build inputs as literals, as in `split_evenly(1250, 0)`, so the only call that can panic is the one under test. 4. **One panicking call per test.** Two calls that could panic in one body make the verdict ambiguous again. 5. **Use `should_panic` only for documented panics.** A recoverable failure that returns `Err` is tested by asserting on the `Result`, not by unwrapping it and expecting the panic. ## What the test pins down A `should_panic` test documents a **contract**: this input is a caller bug, and the function refuses it loudly. That contract has three parts, and a good test pins each one: - **which call** refuses the input, which is why the setup must not be able to panic first; - **which check** fires, identified by the fixed part of its message; - **that the refusal is a panic** rather than an `Err`, which is a design decision about the API, not about the test. When the third part changes, for example when `split_evenly` starts returning `Result<Vec<i64>, SplitError>`, the `should_panic` test should be rewritten as an assertion on the returned `Err`, not loosened. ## Limits of the attribute - It needs a test that returns `()`. rustc rejects it on a test returning `Result` with "functions using `#[should_panic]` must return `()`". - It inspects the panic that ends the test function itself; a panic inside a helper call counts, and so does one in setup code, which is the whole hazard. - A test that should panic but returns normally is a failure, not an ignored test, and the report gives the test's file, line and column.
- Why not set `expected` to the full message, `"parts must be positive, got 0"`?It works, because a whole string contains itself, but it couples the test to the formatting of the value. Rewording the part after the comma, or changing how the number is printed, breaks the test without any change in behaviour. A distinctive fixed fragment such as `"parts must be positive"` checks the guard and nothing else.
- How would you test that `parse_tenths("12.5")` is rejected without using `#[should_panic]`?Assert on the returned value: `assert!(parse_tenths("12.5").is_err())`, or match the `Err` and check its kind. A recoverable failure is part of the function's contract as a value; unwrapping it and expecting the panic hides which call failed.
- What happens if the code under test panics with `std::panic::panic_any(42_u32)` and the test says `expected = "42"`?The test fails. The harness can compare only `String` and `&'static str` payloads, so it reports `expected panic with string value` and a non-string type id, whatever the expected text says.
- #[should_panic] passes only when the function under test is the one that panics.
- expected must equal the entire panic message, character for character.
- The expected text is matched case-insensitively.
- A should_panic test that never panics is reported as ignored.
- #[should_panic] can be combined with a test that returns Result.