diff --git a/README.md b/README.md index 6f406b2..9471e26 100644 --- a/README.md +++ b/README.md @@ -251,6 +251,42 @@ fn expectations_are_checked_before_the_next_step() { } ``` +## Clearing rules between steps + +`checkpoint()` checks a mock's rules so far and then removes them, so the next +step of a test can set its own. Use it when an earlier rule would otherwise keep +answering, such as a rule with the default unlimited count. + +```rust +use shimforge::{Session, mock}; + +fn read_status(service: &str) -> String { + // Queries a health endpoint in production. + format!("{service}: live") +} + +fn is_ready(service: &str) -> bool { + read_status(service).ends_with("ready") +} + +#[test] +fn each_step_starts_with_its_own_rules() { + let mut session = Session::new(); + let status = mock!(session, read_status, fn(&str) -> String); + + // Step 1: the service is still starting, however often it is asked. + status.expect().returns("billing: starting".to_owned()); + assert!(!is_ready("billing")); + assert!(!is_ready("billing")); + // Checks step 1 and removes its rule, which would otherwise keep answering. + status.checkpoint(); + + // Step 2: the service is ready. + status.expect().once().returns("billing: ready".to_owned()); + assert!(is_ready("billing")); +} +``` + ## Return values and call order `returns` clones a value, `return_once` moves it, and `returning` runs a closure diff --git a/tests/readme.rs b/tests/readme.rs index db1a61c..7f735a3 100644 --- a/tests/readme.rs +++ b/tests/readme.rs @@ -146,6 +146,36 @@ mod checking_expectations_during_a_test { } } +mod clearing_rules_between_steps { + use shimforge::{Session, mock}; + + fn read_status(service: &str) -> String { + // Queries a health endpoint in production. + format!("{service}: live") + } + + fn is_ready(service: &str) -> bool { + read_status(service).ends_with("ready") + } + + #[test] + fn each_step_starts_with_its_own_rules() { + let mut session = Session::new(); + let status = mock!(session, read_status, fn(&str) -> String); + + // Step 1: the service is still starting, however often it is asked. + status.expect().returns("billing: starting".to_owned()); + assert!(!is_ready("billing")); + assert!(!is_ready("billing")); + // Checks step 1 and removes its rule, which would otherwise keep answering. + status.checkpoint(); + + // Step 2: the service is ready. + status.expect().once().returns("billing: ready".to_owned()); + assert!(is_ready("billing")); + } +} + mod return_values_and_call_order { use shimforge::{Sequence, Session, mock};