1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189
//! ####  Chaotic testing harness //! //! **Kaos** is a chaotic testing harness to test your services against random failures. //! It allows you to add points to your code to crash sporadically and //! harness asserts availability and fault tolerance of your services by seeking //! minimum time between failures, fail points, and randomized runs. //! //! Kaos is equivalent of Chaos Monkey for the Rust ecosystem. But it is more smart to find the closest MTBF based on previous runs. //! This is dependable system practice. For more information please visit [Chaos engineering](https://en.wikipedia.org/wiki/Chaos_engineering). //! //! # Test Setup //! //! It is better to separate resilience tests. //! Create a directory that will hold all chaos tests. In our example it will be `kaos-tests`. //! //! A minimal launcher for kaos setup looks like this: //! //! ``` //! #[test] //! fn chaos_tests() { //! let k = kaos::Runs::new(); //! //! for entry in fs::read_dir("kaos-tests").unwrap() { //! let entry = entry.unwrap(); //! let path = entry.path(); //! //! // Every service run should be available at least 2 seconds //! k.available(path, Duration::from_secs(2)); //! } //! } //! ``` //! //! and in your Cargo.toml //! //! ```toml //! [[test]] //! name = "chaos_tests" //! path = "kaos-tests/launcher.rs" //! ``` //! //! ## Definining flunks //! In kaos there is a concept of [flunk]. Every flunk is a point of failure with panic. This can be redefinable. //! After adding kaos as dependency you can add flunk points to define fallible operations or crucial points that system should continue its operation. //! //! Basic flunk is like: //! ```rust //! use kaos::flunk; //! fn vec_check(v: &Vec<usize>) { //! if v.len() == 3 { //! flunk!("fail-when-three-elems"); //! } //! } //! ``` //! This flunk point will be used later by kaos. //! //! ## Writing tests //! Test harness will execute tests marked by a launcher. An example test for the flunk mentioned above is like this: //! ``` //! # use std::panic; //! # use kaos::flunk; //! # fn vec_check(v: &Vec<usize>) { //! # if v.len() == 3 { //! # flunk!("fail-when-three-elems"); //! # } //! # } //! use kaos::kaostest; //! //! kaostest!("fail-when-three-elems", //! { //! panic::catch_unwind(|| { //! let mut v = &mut vec![]; //! loop { //! v.push(1); //! vec_check(v); //! } //! }); //! } //! ); //! ``` //! //! That's all, now what you have to do is run with `cargo test`. //! //! Kaos is using the same approach that [trybuild](https://docs.rs/trybuild) has. //! Instead of being compiler-like test harness, it has diverged to be chaos engineering //! oriented harness. #![doc( html_logo_url = "https://raw.githubusercontent.com/vertexclique/kaos/master/img/achaos.gif" )] extern crate humantime; #[macro_use] mod term; #[macro_use] mod path; mod cargo; mod dependencies; mod diff; mod env; mod error; mod features; mod manifest; mod message; mod normalize; mod run; mod rustflags; mod macros; use std::cell::RefCell; use std::path::{Path, PathBuf}; use std::{time::Duration, thread}; #[doc(hidden)] pub use fail::eval as flunker; #[doc(hidden)] pub use fail::cfg as flunker_cfg; #[doc(hidden)] pub use fail::FailScenario as KaosFailScenario; pub use macros::*; /// /// Chaotic runs test setup #[derive(Debug)] pub struct Runs { runner: RefCell<Runner>, } #[derive(Debug)] struct Runner { tests: Vec<Test>, } #[derive(Clone, Debug)] struct Test { path: PathBuf, duration: Option<Duration>, max_surge: isize, expected: Expected, } #[derive(Copy, Clone, Debug)] enum Expected { Available, Chaotic } impl Runs { #[allow(clippy::new_without_default)] pub fn new() -> Self { Runs { runner: RefCell::new(Runner { tests: Vec::new() }), } } pub fn available<P: AsRef<Path>>(&self, path: P, duration: Duration) { self.runner.borrow_mut().tests.push(Test { path: path.as_ref().to_owned(), duration: Some(duration), max_surge: !0, expected: Expected::Available, }); } pub fn chaotic<P: AsRef<Path>>(&self, path: P, run_count: usize, max_surge: usize) { (0..run_count).into_iter().for_each(|_| { self.runner.borrow_mut().tests.push(Test { path: path.as_ref().to_owned(), duration: None, max_surge: max_surge as isize, expected: Expected::Chaotic, }); }); } } #[doc(hidden)] impl Drop for Runs { fn drop(&mut self) { if !thread::panicking() { self.runner.borrow_mut().run(); } } }