fail
is a crate for injecting panics, errors, and other behavior into your programs, called "fail points". This is a pretty useful little crate that more people should be aware of, so this release fills out the documentation to make it easier to use. Note that this is not the more well-known failure
crate, and that the two have different purposes.
Fail points are code instrumentations that allow errors and other behavior to be injected dynamically at runtime, primarily for testing purposes. Fail points are flexible and can be configured to exhibit a variety of behavior, including panics, early returns, and sleeping. They can be controlled both programmatically and via the environment, and can be triggered conditionally and probabilistically.
This crate is inspired by FreeBSD's failpoints.
crates.io: https://crates.io/crates/fail
docs.rs: fail - Rust
As an example, here's a simple program that uses a fail point to simulate an I/O panic:
#[macro_use]
extern crate fail;
fn do_fallible_work() {
fail_point!("read-dir");
let _dir: Vec<_> = std::fs::read_dir(".").unwrap().collect();
// ... do some work on the directory ...
}
fn main() {
fail::setup();
do_fallible_work();
fail::teardown();
println!("done");
}
Here, the program calls unwrap
on the result of read_dir
, a function that returns a Result
. In other words, this particular program expects this call to read_dir
to always succeed. And in practice it almost always will, which makes the behavior of this program when read_dir
fails difficult to test. By instrumenting the program with a fail point we can pretend that read_dir
failed, causing the subsequent unwrap
to panic, and allowing us to observe the program's behavior under failure conditions.
When the program is run normally it just prints "done":
$ cargo run
Finished dev [unoptimized + debuginfo] target(s) in 0.01s
Running `target/debug/failpointtest`
done
But now, by setting the FAILPOINTS
variable we can see what happens if the read_dir
fails:
FAILPOINTS=read-dir=panic cargo run
Finished dev [unoptimized + debuginfo] target(s) in 0.01s
Running `target/debug/failpointtest`
thread 'main' panicked at 'failpoint read-dir panic', /home/ubuntu/.cargo/registry/src/github.com-1ecc6299db9ec823/fail-0.2.0/src/lib.rs:286:25
note: Run with `RUST_BACKTRACE=1` for a backtrace.
For further information see the API documentation.
This crate is maintained by PingCAP for TiKV, and you can see how they use it here: tikv/tests/failpoints at master · tikv/tikv · GitHub