Initial commit

.gitignore

@@ -0,0 +1,2 @@
+/target
+/Cargo.lock

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 <[email protected]>"]
+repository = "https://github.com/mishmish-dev/subcase"
+license = "MIT"
+categories = ["development-tools::testing"]
+keywords = ["macros", "section", "subcase", "catch2", "testing"]
+
+[lib]
+crate-type = ["lib"]
+
+

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.

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)
+
+<!-- cargo-rdme start -->
+
+# 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.
+
+<!-- cargo-rdme end -->

src/detail.rs

@@ -0,0 +1,44 @@
+pub type TreePath = Vec<usize>;
+
+#[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();
+    }
+}

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;

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;
+                }
+            }
+        )+
+    }
+}