From 8d3d6adf891dda9d7b94737d357fb6b2d632215f Mon Sep 17 00:00:00 2001 From: Mishmish Dev Date: Sun, 26 Mar 2023 15:02:24 +0300 Subject: [PATCH] Initial commit --- .gitignore | 2 + Cargo.toml | 16 ++++++ LICENSE.txt | 20 ++++++++ README.md | 117 ++++++++++++++++++++++++++++++++++++++++++++ src/detail.rs | 44 +++++++++++++++++ src/lib.rs | 125 +++++++++++++++++++++++++++++++++++++++++++++++ src/macro_def.rs | 48 ++++++++++++++++++ tests/subcase.rs | 66 +++++++++++++++++++++++++ 8 files changed, 438 insertions(+) create mode 100644 .gitignore create mode 100644 Cargo.toml create mode 100644 LICENSE.txt create mode 100644 README.md create mode 100644 src/detail.rs create mode 100644 src/lib.rs create mode 100644 src/macro_def.rs create mode 100644 tests/subcase.rs diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4fffb2f --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +/target +/Cargo.lock diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..79a0a61 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,16 @@ +[package] +name = "subcase" +description = "Deduplicate unit test code in Rust without fixtures" +version = "0.1.1" +edition = "2021" +rust-version = "1.56.1" +authors = ["Mishmish Dev "] +repository = "https://github.com/mishmish-dev/subcase" +license = "MIT" +categories = ["development-tools::testing"] +keywords = ["macros", "section", "subcase", "catch2", "testing"] + +[lib] +crate-type = ["lib"] + + diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..4e39fcf --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,20 @@ +Copyright (c) 2023 Mishmish Dev + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..064ee37 --- /dev/null +++ b/README.md @@ -0,0 +1,117 @@ +[![crates.io](https://img.shields.io/crates/v/subcase?style=for-the-badge&color=blue)](https://crates.io/crates/subcase) + + + +# Intuitive way to deduplicate your tests code + +## What is a subcase? + +*Sections*, or *subcases* are a cool feature of unit testing frameworks, +such as (awesome) C++ libraries [Catch2](https://github.com/catchorg/Catch2) +and [doctest](https://github.com/doctest/doctest). +Subcases provide an easy way to share code between tests, +like fixtures do, but without needing to move setup and teardown code +outside of your tests' meat, without hassles of object orientation. + +How do they work? Subcases allow you to fork function execution +to into different paths which will have common code in the places +you want them to. + +Let's look at an example. +```rust +use subcase::with_subcases; +with_subcases! { + #[test] + fn my_test_case() { + let mut v = vec![1,2,3]; + + subcase! {{ + v.push(9); + assert_eq!(v.last().unwrap().clone(), 9); + }} + subcase! {{ + v.clear(); + assert!(v.is_empty()); + for _i in 0..4 { v.push(1); } + }} + + assert_eq!(v.len(), 4); + assert!(v.capacity() >= 4); + } +} +``` +`my_test_case`'s body will be executed twice, first time +with first `subcase!{{...}}` block, ignoring the second, +and vice versa. + +That's not all! Subcases can be nested! +```rust +let mut v = vec![1,2,3]; +subcase! {{ + v.push(9); +}} +subcase! {{ + v.clear(); + + subcase! {{ + for _i in 0..5 { v.push(1); } + assert_eq!(v.len(), 5); + }} + + v.push(100); + + subcase! {{ + v.extend_from_slice(&[4,5,6,7,8]); + }} + assert_eq!(v.len(), 6); + + v.pop(); + v.pop(); +}} +assert_eq!(v.len(), 4); +``` +In this example, test function body is executed 3 times: once +for each of leaf subcases (i.e. not containing more nested subcases), +while the big parent subcase is entered twice. + +You can write only one subcase or no subcases at all --- function +will run as usual. + +## Other oprions? + +Indeed, there are already a few crates that implement the concept +of subcases: ++ [rust-catch](https://crates.io/crates/rust-catch) ++ [rye](https://crates.io/crates/rye) ++ [crossroads](https://crates.io/crates/crossroads) + +What distinguishes subcase crate from each of them, is that +subcase only uses lightweight declarative (i.e. `macro_rules!`) +macros and has zero dependencies. Also, `with_subcases` macro stuffs +all execution paths inside one function, instead of generating +many. These making it very easy on Rust compiler, in comparison +to the mentioned crates. + +(I will provide actual benchmarks in the future.) + +## Limitations + +Probably most of these limitations will be (partially) lifted in +the future, stay tuned. + ++ As of current version, Rust builtin testing framework cannot help you +know what exact path of execution has failed. Also, as different +branches of evaluation are switched at runtime, you possibly can +trigger borrow checker. + ++ Only `()`-returning functions are supported. + ++ You must use double pair of braces with inner `subcase!` macro. + ++ You cannot rename the inner `subcase!` macro. + +## License + +Licensed under MIT License. + + diff --git a/src/detail.rs b/src/detail.rs new file mode 100644 index 0000000..b816584 --- /dev/null +++ b/src/detail.rs @@ -0,0 +1,44 @@ +pub type TreePath = Vec; + +#[derive(Default)] +pub struct SubcasesState { + depth: usize, + path: TreePath, +} + +impl SubcasesState { + pub fn enter_subcase(&mut self, exec_path: &mut TreePath) -> bool { + if exec_path.len() <= self.depth { + exec_path.push(0); + } + if self.path.len() <= self.depth { + self.path.push(0); + } else { + self.path[self.depth] += 1; + } + self.depth += 1; + + exec_path[0..self.depth] == self.path[0..self.depth] + } + + pub fn exit_subcase(&mut self) { + self.depth -= 1; + } + + pub fn update_exec_path(&mut self, exec_path: &mut TreePath) { + while !exec_path.is_empty() { + let i = exec_path.len() - 1; + if exec_path[i] < self.path[i] { + exec_path[i] += 1; + return; + } else { + exec_path.pop(); + } + } + } + + pub fn clear(&mut self) { + self.depth = 0; + self.path.clear(); + } +} diff --git a/src/lib.rs b/src/lib.rs new file mode 100644 index 0000000..9b1b805 --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,125 @@ +//! # Intuitive way to deduplicate your tests code +//! +//! ## What is a subcase? +//! +//! *Sections*, or *subcases* are a cool feature of unit testing frameworks, +//! such as (awesome) C++ libraries [Catch2](https://github.com/catchorg/Catch2) +//! and [doctest](https://github.com/doctest/doctest). +//! Subcases provide an easy way to share code between tests, +//! like fixtures do, but without needing to move setup and teardown code +//! outside of your tests' meat, without hassles of object orientation. +//! +//! How do they work? Subcases allow you to fork function execution +//! to into different paths which will have common code in the places +//! you want them to. +//! +//! Let's look at an example. +//! ``` +//! use subcase::with_subcases; +//! with_subcases! { +//! #[test] +//! fn my_test_case() { +//! let mut v = vec![1,2,3]; +//! +//! subcase! {{ +//! v.push(9); +//! assert_eq!(v.last().unwrap().clone(), 9); +//! }} +//! subcase! {{ +//! v.clear(); +//! assert!(v.is_empty()); +//! for _i in 0..4 { v.push(1); } +//! }} +//! +//! assert_eq!(v.len(), 4); +//! assert!(v.capacity() >= 4); +//! } +//! } +//! ``` +//! `my_test_case`'s body will be executed twice, first time +//! with first `subcase!{{...}}` block, ignoring the second, +//! and vice versa. +//! +//! That's not all! Subcases can be nested! +//! ``` +//! # use subcase::with_subcases; +//! # with_subcases! { +//! # #[test] +//! # fn my_tremendous_test_case() { +//! let mut v = vec![1,2,3]; +//! subcase! {{ +//! v.push(9); +//! }} +//! subcase! {{ +//! v.clear(); +//! +//! subcase! {{ +//! for _i in 0..5 { v.push(1); } +//! assert_eq!(v.len(), 5); +//! }} +//! +//! v.push(100); +//! +//! subcase! {{ +//! v.extend_from_slice(&[4,5,6,7,8]); +//! }} +//! assert_eq!(v.len(), 6); +//! +//! v.pop(); +//! v.pop(); +//! }} +//! assert_eq!(v.len(), 4); +//! # } +//! # } +//! ``` +//! In this example, test function body is executed 3 times: once +//! for each of leaf subcases (i.e. not containing more nested subcases), +//! while the big parent subcase is entered twice. +//! +//! You can write only one subcase or no subcases at all --- function +//! will run as usual. +//! +//! ## Other oprions? +//! +//! Indeed, there are already a few crates that implement the concept +//! of subcases: +//! + [rust-catch](https://crates.io/crates/rust-catch) +//! + [rye](https://crates.io/crates/rye) +//! + [crossroads](https://crates.io/crates/crossroads) +//! +//! What distinguishes subcase crate from each of them, is that +//! subcase only uses lightweight declarative (i.e. `macro_rules!`) +//! macros and has zero dependencies. Also, `with_subcases` macro stuffs +//! all execution paths inside one function, instead of generating +//! many. These making it very easy on Rust compiler, in comparison +//! to the mentioned crates. +//! +//! (I will provide actual benchmarks in the future.) +//! +//! ## Limitations +//! +//! Probably most of these limitations will be (partially) lifted in +//! the future, stay tuned. +//! +//! + As of current version, Rust builtin testing framework cannot help you +//! know what exact path of execution has failed. Also, as different +//! branches of evaluation are switched at runtime, you possibly can +//! trigger borrow checker. +//! +//! + Only `()`-returning functions are supported. +//! +//! + You must use double pair of braces with inner `subcase!` macro. +//! +//! + You cannot rename the inner `subcase!` macro. +//! +//! ## License +//! +//! Licensed under MIT License. + +#![deny(missing_docs)] + +/// Defines the sole public macro [with_subcases] +pub mod macro_def; + +#[doc(hidden)] +pub mod detail; diff --git a/src/macro_def.rs b/src/macro_def.rs new file mode 100644 index 0000000..2c7c0aa --- /dev/null +++ b/src/macro_def.rs @@ -0,0 +1,48 @@ +/// Allows to fork a function's execution +/// to create multiple paths which share code, for example, +/// test case setup/teardown. +/// +/// Macro body can contain one or more function definition. +/// Functions are restricted to not to return anything. +/// +/// For usage, please refer to the crate doc. +#[macro_export] +macro_rules! with_subcases { + ( + $( + $( #[$meta:meta] )* + $vis:vis fn $name:ident ( $( $arg:ident : $arg_t:ty ),* $(,)? ) { + $($body:tt)* + } + )+ + ) => { + $( + $( #[$meta] )* + $vis fn $name ( $( $arg : $arg_t ),* ) { + + let mut exec_path = $crate::detail::TreePath::new(); + let mut state = $crate::detail::SubcasesState::default(); + + macro_rules! subcase { + ($block:block) => { + if state.enter_subcase(&mut exec_path) + $block + ; + state.exit_subcase(); + } + } + + let mut first = true; + while first || !exec_path.is_empty() { + { + $($body)* + } + + state.update_exec_path(&mut exec_path); + state.clear(); + first = false; + } + } + )+ + } +} diff --git a/tests/subcase.rs b/tests/subcase.rs new file mode 100644 index 0000000..d75c264 --- /dev/null +++ b/tests/subcase.rs @@ -0,0 +1,66 @@ +use subcase::with_subcases; + +with_subcases! { + #[test] + fn my_test_case() { + let mut v = vec![1,2,3]; + + subcase! {{ + v.push(9); + assert_eq!(v.last().unwrap().clone(), 9); + }} + subcase! {{ + v.clear(); + assert!(v.is_empty()); + for _i in 0..4 { v.push(1); } + }} + + assert_eq!(v.len(), 4); + assert!(v.capacity() >= 4); + } + + #[test] + fn my_tremendous_test_case() { + let mut v = vec![1,2,3]; + + subcase! {{ + v.push(9); + }} + subcase! {{ + v.clear(); + assert!(v.is_empty()); + + subcase! {{ + for _i in 0..5 { v.push(1); } + assert_eq!(v.len(), 5); + }} + + v.push(100); + + subcase! {{ + v.extend_from_slice(&[4,5,6,7,8]); + }} + + assert_eq!(v.len(), 6); + v.pop(); + v.pop(); + }} + + assert_eq!(v.len(), 4); + } + + #[test] + #[should_panic] + fn test_two() { + let mut v = vec![1,2,3]; + + subcase! {{ + v.push(4); + }} + subcase! {{ + v.push(5); + }} + + assert_eq!(v.len(), 5); + } +}