Skip to content
Fail points for rust
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Create issue templates (#17) Nov 3, 2018
src
tests
.gitignore add basic runtime (#1) Sep 16, 2017
.travis.yml *: format and lint code (#18) Dec 11, 2018
CHANGELOG.md
CODE_OF_CONDUCT.md
Cargo.toml *: bump version to 0.3.0 from 0.2.1 Jan 28, 2019
LICENSE Initial commit Sep 12, 2017
README.md fail is 0.3 now Feb 5, 2019
appveyor.yml add ci check (#5) Sep 20, 2017

README.md

fail-rs

Build Status Build status Crates.io

Documentation.

A fail point implementation for Rust.

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.

Usage

First, add this to your Cargo.toml:

[dependencies]
fail = "0.3"

Now you can import the fail_point! macro from the fail crate and use it to inject dynamic failures.

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.

TODO

Triggering a fail point via the HTTP API is planned but not implemented yet.

You can’t perform that action at this time.