{"id":13580148,"url":"https://github.com/tikv/fail-rs","last_synced_at":"2025-04-14T02:57:26.049Z","repository":{"id":39340295,"uuid":"103275720","full_name":"tikv/fail-rs","owner":"tikv","description":"Fail points for rust","archived":false,"fork":false,"pushed_at":"2024-12-09T07:43:09.000Z","size":83,"stargazers_count":346,"open_issues_count":20,"forks_count":40,"subscribers_count":56,"default_branch":"master","last_synced_at":"2025-04-14T02:57:21.154Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tikv.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-12T13:41:13.000Z","updated_at":"2025-04-13T21:02:19.000Z","dependencies_parsed_at":"2024-02-28T03:26:02.200Z","dependency_job_id":"55869656-ad95-4ca2-bd92-6902fcec8549","html_url":"https://github.com/tikv/fail-rs","commit_stats":{"total_commits":57,"total_committers":21,"mean_commits":"2.7142857142857144","dds":0.7192982456140351,"last_synced_commit":"b6d5834ed7e339625024fedee4f9b589751be766"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tikv%2Ffail-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tikv%2Ffail-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tikv%2Ffail-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tikv%2Ffail-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tikv","download_url":"https://codeload.github.com/tikv/fail-rs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248813786,"owners_count":21165632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T15:01:47.994Z","updated_at":"2025-04-14T02:57:26.022Z","avatar_url":"https://github.com/tikv.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# fail-rs\n\n[![CI](https://github.com/tikv/fail-rs/workflows/CI/badge.svg)](https://github.com/tikv/fail-rs/actions)\n[![Crates.io](https://img.shields.io/crates/v/fail.svg?maxAge=2592000)](https://crates.io/crates/fail)\n\n[Documentation](https://docs.rs/fail).\n\nA fail point implementation for Rust.\n\nFail 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.\n\nThis crate is inspired by FreeBSD's [failpoints](https://freebsd.org/cgi/man.cgi?query=fail).\n\n## Usage\n\nFirst, add this to your `Cargo.toml`:\n\n```toml\n[dependencies]\nfail = \"0.5\"\n```\n\nNow you can import the `fail_point!` macro from the `fail` crate and use it to inject dynamic failures.\nFail points generation by this macro is disabled by default, and can be enabled where relevant with the `failpoints` Cargo feature.\n\nAs an example, here's a simple program that uses a fail point to simulate an I/O panic:\n\n```rust\nuse fail::{fail_point, FailScenario};\n\nfn do_fallible_work() {\n    fail_point!(\"read-dir\");\n    let _dir: Vec\u003c_\u003e = std::fs::read_dir(\".\").unwrap().collect();\n    // ... do some work on the directory ...\n}\n\nfn main() {\n    let scenario = FailScenario::setup();\n    do_fallible_work();\n    scenario.teardown();\n    println!(\"done\");\n}\n```\n\nHere, 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.\n\nWhen the program is run normally it just prints \"done\":\n\n```sh\n$ cargo run --features fail/failpoints\n    Finished dev [unoptimized + debuginfo] target(s) in 0.01s\n     Running `target/debug/failpointtest`\ndone\n```\n\nBut now, by setting the `FAILPOINTS` variable we can see what happens if the `read_dir` fails:\n\n```\nFAILPOINTS=read-dir=panic cargo run --features fail/failpoints\n    Finished dev [unoptimized + debuginfo] target(s) in 0.01s\n     Running `target/debug/failpointtest`\nthread 'main' panicked at 'failpoint read-dir panic', /home/ubuntu/.cargo/registry/src/github.com-1ecc6299db9ec823/fail-0.2.0/src/lib.rs:286:25\nnote: Run with `RUST_BACKTRACE=1` for a backtrace.\n```\n\nFor further information see the [API documentation](https://docs.rs/fail).\n\n\n## TODO\n\nTriggering a fail point via the HTTP API is planned but not implemented yet.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftikv%2Ffail-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftikv%2Ffail-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftikv%2Ffail-rs/lists"}