test/doc: Chain (#66)

Author: julio4

src/pipelines/events.rs

@@ -106,9 +106,6 @@ mod tests {
 		reth::node::builder::BuiltPayload,
 	};
 
-	#[derive(Clone, Debug, PartialEq, Eq)]
-	struct StringEvent(String);
-
 	#[derive(Clone, Debug, PartialEq, Eq)]
 	struct UInt32Event(u32);
 

src/steps/combinator/atomic.rs

@@ -1,6 +1,9 @@
 use {super::*, crate::platform::types::BuiltPayload};
 
-combinator!(Atomic, and);
+combinator!(
+	/// TODO
+	, Atomic, and
+);
 
 impl<P: Platform> Step<P> for Atomic<P> {
 	async fn before_job(

src/steps/combinator/chain.rs

@@ -1,6 +1,37 @@
 use {super::*, crate::platform::types::BuiltPayload};
 
-combinator!(Chain, then);
+combinator!(
+	/// The [`Chain`] combinator executes a sequence of steps in order. Each step
+	/// receives the output checkpoint from the previous step.
+	///
+	/// # Execution Semantics
+	///
+	/// - If a step returns [`ControlFlow::Ok`], execution continues with the next
+	///   step
+	/// - If a step returns [`ControlFlow::Break`], execution stops and returns
+	///   [`ControlFlow::Break`]
+	/// - If a step returns [`ControlFlow::Fail`], execution stops and returns
+	///   [`ControlFlow::Fail`]
+	/// - The final result is either the last successful checkpoint or the first
+	///   non-Ok control flow
+	///
+	/// # Example
+	///
+	/// ```rust
+	/// use rblib::prelude::*;
+	///
+	/// # fn example<P: Platform>(
+	/// #     step1: impl Step<P>,
+	/// #     step2: impl Step<P>,
+	/// #     step3: impl Step<P>
+	/// # ) {
+	/// let chain = Chain::of(step1).then(step2).then(step3);
+	/// // or using macro:
+	/// let chain = chain!(step1, step2, step3);
+	/// # }
+	/// ```
+	, Chain, then
+);
 
 impl<P: Platform> Step<P> for Chain<P> {
 	async fn before_job(
@@ -71,3 +102,122 @@ macro_rules! chain {
         c
     }};
 }
+
+#[cfg(test)]
+mod tests {
+	use {
+		super::*,
+		crate::{
+			platform::{Ethereum, Optimism},
+			steps::CombinatorStep,
+			test_utils::*,
+		},
+		futures::StreamExt,
+	};
+
+	fake_step!(OkEvent2, emit_events, noop_ok);
+
+	#[rblib_test(Ethereum, Optimism)]
+	async fn chain_ok_one_step<P: TestablePlatform>() {
+		let chain = Chain::of(OkWithEventStep);
+
+		let step = OneStep::<P>::new(chain);
+		let mut event_sub = step.subscribe::<StringEvent>();
+
+		let output = step.run().await.unwrap();
+		assert!(output.is_ok());
+
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkWithEventStep: before_job".to_string()))
+		);
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkWithEventStep: step".to_string()))
+		);
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkWithEventStep: after_job".to_string()))
+		);
+	}
+
+	#[rblib_test(Ethereum, Optimism)]
+	async fn chain_execute_in_order<P: TestablePlatform>() {
+		let chain = Chain::of(OkWithEventStep).then(OkEvent2);
+
+		let step = OneStep::<P>::new(chain);
+		let mut event_sub = step.subscribe::<StringEvent>();
+
+		let output = step.run().await.unwrap();
+		assert!(output.is_ok());
+
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkWithEventStep: before_job".to_string()))
+		);
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkEvent2: before_job".to_string()))
+		);
+
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkWithEventStep: step".to_string()))
+		);
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkEvent2: step".to_string()))
+		);
+
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkWithEventStep: after_job".to_string()))
+		);
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkEvent2: after_job".to_string()))
+		);
+	}
+
+	#[rblib_test(Ethereum, Optimism)]
+	async fn chain_break_stops_execution<P: TestablePlatform>() {
+		let chain = Chain::of(AlwaysBreakStep).then(OkWithEventStep);
+
+		let step = OneStep::<P>::new(chain);
+		let mut event_sub = step.subscribe::<StringEvent>();
+
+		let output = step.run().await.unwrap();
+		assert!(output.is_break());
+
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkWithEventStep: before_job".to_string()))
+		);
+		// step is not called
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkWithEventStep: after_job".to_string()))
+		);
+	}
+
+	#[rblib_test(Ethereum, Optimism)]
+	async fn chain_fail_stops_execution<P: TestablePlatform>() {
+		let chain = Chain::of(AlwaysFailStep).then(OkWithEventStep);
+
+		let step = OneStep::<P>::new(chain);
+		let mut event_sub = step.subscribe::<StringEvent>();
+
+		let output = step.run().await.unwrap();
+		assert!(output.is_fail());
+
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkWithEventStep: before_job".to_string()))
+		);
+		// step is not called
+		assert_eq!(
+			event_sub.next().await,
+			Some(StringEvent("OkWithEventStep: after_job".to_string()))
+		);
+	}
+}

src/steps/combinator/mod.rs

@@ -48,10 +48,11 @@ pub trait CombinatorStep<P: Platform>: Step<P> {
 /// - `$append()` method to append a step to the collection
 /// - `steps()` method to get a slice of the steps for the `Step` implementation
 macro_rules! combinator {
+	// meta is rustdoc for the combinator struct,
 	// name is the combinator struct name,
 	// append the method name of adding a step (optional)
-	($name:ident, $append:ident) => {
-		/// Combinator step that executes a sequence of steps in order.
+	($(#[$meta:meta])*, $name:ident, $append:ident) => {
+		$(#[$meta])*
 		pub struct $name<P: Platform>(pub Steps<P>);
 
 		impl<P: Platform> CombinatorStep<P> for $name<P> {
@@ -89,8 +90,8 @@ macro_rules! combinator {
 	};
 
 	// default method name for adding a step: append
-	($name:ident) => {
-		combinator!($name, append);
+	($(#[$meta:meta])*, $name:ident) => {
+		combinator!($(#[$meta])*, $name, append);
 	};
 }
 
@@ -122,7 +123,10 @@ impl<P: Platform, S: Step<P>> IntoSteps<P> for S {
 pub mod tests {
 	use {super::*, crate::test_utils::*};
 
-	combinator!(TestCombinator, test_append);
+	combinator!(
+		/// `TestCombinator` doc
+		 , TestCombinator, test_append
+	);
 	impl<P: Platform> Step<P> for TestCombinator<P> {
 		async fn step(
 			self: Arc<Self>,

src/test_utils/mod.rs

@@ -22,7 +22,6 @@ mod platform;
 mod step;
 mod transactions;
 
-#[allow(unused_imports)]
 pub(crate) use step::fake_step;
 pub use {
 	accounts::{FundedAccounts, WithFundedAccounts},
@@ -32,7 +31,14 @@ pub use {
 	node::{ConsensusDriver, LocalNode},
 	platform::{TestNodeFactory, TestablePlatform},
 	rblib_tests_macros::{assert_is_dyn_safe, if_platform, rblib_test},
-	step::{AlwaysBreakStep, AlwaysFailStep, AlwaysOkStep, OneStep},
+	step::{
+		AlwaysBreakStep,
+		AlwaysFailStep,
+		AlwaysOkStep,
+		OkWithEventStep,
+		OneStep,
+		StringEvent,
+	},
 	transactions::{
 		invalid_tx,
 		reverting_tx,