Wrap event::Cucumber in Event to allow metadata

CHANGELOG.md

@@ -29,13 +29,15 @@ All user visible changes to `cucumber` crate will be documented in this file. Th
 - Ability to run `Scenario`s concurrently. ([#128])
 - Highlighting of regex capture groups in terminal output with __bold__ style. ([#136])
 - Error on a step matching multiple step functions ([#143]).
+- `timestamps` Cargo feature that enables collecting of timestamps for all the happened events during tests execution (useful for `Writer`s which format requires them) ([#145]).
 
 [#128]: /../../pull/128
 [#136]: /../../pull/136
 [#137]: /../../pull/137
 [#142]: /../../pull/142
 [#143]: /../../pull/143
 [#144]: /../../pull/144
+[#145]: /../../pull/145
 
 
 

Cargo.toml

@@ -27,13 +27,16 @@ rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
 default = ["macros"]
+# Enables step attributes and auto-wiring.
 macros = ["cucumber-codegen", "inventory"]
+# Enables timestamps collecting for all events.
+timestamps = []
 
 [dependencies]
 async-trait = "0.1.40"
 atty = "0.2.14"
 console = "0.15"
-derive_more = { version = "0.99.16", features = ["deref", "deref_mut", "display", "error", "from"], default_features = false }
+derive_more = { version = "0.99.16", features = ["as_ref", "deref", "deref_mut", "display", "error", "from"], default_features = false }
 either = "1.6"
 futures = "0.3.17"
 gherkin = { package = "gherkin_rust", version = "0.10" }

Makefile

@@ -67,7 +67,7 @@ cargo.fmt:
 #	make cargo.lint
 
 cargo.lint:
-	cargo clippy --workspace -- -D warnings
+	cargo clippy --workspace --all-features -- -D warnings
 
 
 

src/cli.rs

@@ -179,7 +179,7 @@ another one:
 ```rust
 # use async_trait::async_trait;
 # use cucumber::{
-#     cli, event, parser, ArbitraryWriter, FailureWriter, World, Writer,
+#     cli, event, parser, ArbitraryWriter, Event, FailureWriter, World, Writer,
 # };
 # use structopt::StructOpt;
 #
@@ -201,7 +201,7 @@ where
 
     async fn handle_event(
         &mut self,
-        ev: parser::Result<event::Cucumber<W>>,
+        ev: parser::Result<Event<event::Cucumber<W>>>,
         cli: &Self::Cli,
     ) {
         // Some custom logic including `cli.left.custom_option`.

src/cucumber.rs

@@ -25,8 +25,9 @@ use regex::Regex;
 use structopt::{StructOpt, StructOptInternal};
 
 use crate::{
-    cli, event, parser, runner, step, tag::Ext as _, writer, FailureWriter,
-    Parser, Runner, ScenarioType, Step, World, Writer, WriterExt as _,
+    cli, event, parser, runner, step, tag::Ext as _, writer, Event,
+    FailureWriter, Parser, Runner, ScenarioType, Step, World, Writer,
+    WriterExt as _,
 };
 
 /// Top-level [Cucumber] executor.
@@ -387,7 +388,7 @@ where
     ///         use cucumber::event::{Cucumber, Feature, Rule, Scenario, Step};
     ///
     ///         matches!(
-    ///             ev,
+    ///             ev.as_deref(),
     ///             Ok(Cucumber::Feature(
     ///                 _,
     ///                 Feature::Rule(
@@ -434,7 +435,7 @@ where
         filter: F,
     ) -> Cucumber<W, P, I, R, writer::Repeat<W, Wr, F>, Cli>
     where
-        F: Fn(&parser::Result<event::Cucumber<W>>) -> bool,
+        F: Fn(&parser::Result<Event<event::Cucumber<W>>>) -> bool,
     {
         Cucumber {
             parser: self.parser,

src/event.rs

@@ -21,7 +21,10 @@
 
 use std::{any::Any, fmt, sync::Arc};
 
-use derive_more::{Display, Error, From};
+#[cfg(feature = "timestamps")]
+use std::time::SystemTime;
+
+use derive_more::{AsRef, Deref, DerefMut, Display, Error, From};
 
 use crate::{step, writer::basic::coerce_error};
 
@@ -30,6 +33,88 @@ use crate::{step, writer::basic::coerce_error};
 /// [`catch_unwind()`]: std::panic::catch_unwind()
 pub type Info = Arc<dyn Any + Send + 'static>;
 
+/// Arbitrary event, optionally paired with additional metadata.
+///
+/// Any metadata is added by enabling the correspondent library feature:
+/// - `timestamps`: adds time of when this [`Event`] has happened.
+#[derive(AsRef, Clone, Copy, Debug, Deref, DerefMut)]
+#[non_exhaustive]
+pub struct Event<T: ?Sized> {
+    /// [`SystemTime`] when this [`Event`] has happened.
+    #[cfg(feature = "timestamps")]
+    pub at: SystemTime,
+
+    /// Actual value of this [`Event`].
+    #[as_ref]
+    #[deref]
+    #[deref_mut]
+    pub value: T,
+}
+
+impl<T> Event<T> {
+    /// Creates a new [`Event`] out of the given `value`.
+    #[must_use]
+    pub fn new(value: T) -> Self {
+        Self {
+            #[cfg(feature = "timestamps")]
+            at: SystemTime::now(),
+            value,
+        }
+    }
+
+    /// Unwraps the inner [`Event::value`] loosing all the attached metadata.
+    #[allow(clippy::missing_const_for_fn)] // false positive: drop in const
+    #[must_use]
+    pub fn into_inner(self) -> T {
+        self.value
+    }
+
+    /// Splits this [`Event`] to the inner [`Event::value`] and its detached
+    /// metadata.
+    #[must_use]
+    pub fn split(self) -> (T, Metadata) {
+        self.replace(())
+    }
+
+    /// Replaces the inner [`Event::value`] with the given one, dropping the old
+    /// one in place.
+    #[must_use]
+    pub fn insert<V>(self, value: V) -> Event<V> {
+        self.replace(value).1
+    }
+
+    /// Maps the inner [`Event::value`] with the given function.
+    #[must_use]
+    pub fn map<V>(self, f: impl FnOnce(T) -> V) -> Event<V> {
+        let (val, meta) = self.split();
+        meta.insert(f(val))
+    }
+
+    /// Replaces the inner [`Event::value`] with the given one, returning the
+    /// old one along.
+    #[allow(clippy::missing_const_for_fn)] // false positive: drop in const
+    #[must_use]
+    pub fn replace<V>(self, value: V) -> (T, Event<V>) {
+        let event = Event {
+            #[cfg(feature = "timestamps")]
+            at: self.at,
+            value,
+        };
+        (self.value, event)
+    }
+}
+
+/// Shortcut for a detached metadata of an arbitrary [`Event`].
+pub type Metadata = Event<()>;
+
+impl Metadata {
+    /// Wraps the given `value` with this [`Event`] metadata.
+    #[must_use]
+    pub fn wrap<V>(self, value: V) -> Event<V> {
+        self.replace(value).1
+    }
+}
+
 /// Top-level [Cucumber] run event.
 ///
 /// [Cucumber]: https://cucumber.io

src/lib.rs

@@ -126,6 +126,7 @@ pub use cucumber_codegen::{given, then, when, WorldInit};
 #[doc(inline)]
 pub use self::{
     cucumber::Cucumber,
+    event::Event,
     parser::Parser,
     runner::{Runner, ScenarioType},
     step::Step,

src/runner/basic.rs

@@ -39,7 +39,7 @@ use structopt::StructOpt;
 use crate::{
     event::{self, HookType, Info},
     feature::Ext as _,
-    parser, step, Runner, Step, World,
+    parser, step, Event, Runner, Step, World,
 };
 
 // Workaround for overwritten doc-comments.
@@ -387,7 +387,7 @@ where
     type Cli = Cli;
 
     type EventStream =
-        LocalBoxStream<'static, parser::Result<event::Cucumber<W>>>;
+        LocalBoxStream<'static, parser::Result<Event<event::Cucumber<W>>>>;
 
     fn run<S>(self, features: S, cli: Cli) -> Self::EventStream
     where
@@ -442,7 +442,7 @@ async fn insert_features<W, S, F>(
     into: Features,
     features: S,
     which_scenario: F,
-    sender: mpsc::UnboundedSender<parser::Result<event::Cucumber<W>>>,
+    sender: mpsc::UnboundedSender<parser::Result<Event<event::Cucumber<W>>>>,
 ) where
     S: Stream<Item = parser::Result<gherkin::Feature>> + 'static,
     F: Fn(
@@ -476,7 +476,7 @@ async fn execute<W, Before, After>(
     features: Features,
     max_concurrent_scenarios: Option<usize>,
     collection: step::Collection<W>,
-    sender: mpsc::UnboundedSender<parser::Result<event::Cucumber<W>>>,
+    sender: mpsc::UnboundedSender<parser::Result<Event<event::Cucumber<W>>>>,
     before_hook: Option<Before>,
     after_hook: Option<After>,
 ) where
@@ -584,7 +584,7 @@ struct Executor<W, Before, After> {
     /// Sender for notifying state of [`Feature`]s completion.
     ///
     /// [`Feature`]: gherkin::Feature
-    sender: mpsc::UnboundedSender<parser::Result<event::Cucumber<W>>>,
+    sender: mpsc::UnboundedSender<parser::Result<Event<event::Cucumber<W>>>>,
 }
 
 impl<W: World, Before, After> Executor<W, Before, After>
@@ -609,7 +609,9 @@ where
         collection: step::Collection<W>,
         before_hook: Option<Before>,
         after_hook: Option<After>,
-        sender: mpsc::UnboundedSender<parser::Result<event::Cucumber<W>>>,
+        sender: mpsc::UnboundedSender<
+            parser::Result<Event<event::Cucumber<W>>>,
+        >,
     ) -> Self {
         Self {
             features_scenarios_count: HashMap::new(),
@@ -1098,17 +1100,17 @@ where
     fn send(&self, event: event::Cucumber<W>) {
         // If the receiver end is dropped, then no one listens for events
         // so we can just ignore it.
-        drop(self.sender.unbounded_send(Ok(event)));
+        drop(self.sender.unbounded_send(Ok(Event::new(event))));
     }
 
     /// Notifies with the given [`Cucumber`] events.
     ///
     /// [`Cucumber`]: event::Cucumber
     fn send_all(&self, events: impl Iterator<Item = event::Cucumber<W>>) {
-        for ev in events {
+        for v in events {
             // If the receiver end is dropped, then no one listens for events
             // so we can just stop from here.
-            if self.sender.unbounded_send(Ok(ev)).is_err() {
+            if self.sender.unbounded_send(Ok(Event::new(v))).is_err() {
                 break;
             }
         }

src/runner/mod.rs

@@ -19,7 +19,7 @@ pub mod basic;
 use futures::Stream;
 use structopt::StructOptInternal;
 
-use crate::{event, parser};
+use crate::{event, parser, Event};
 
 #[doc(inline)]
 pub use self::basic::{Basic, ScenarioType};
@@ -76,7 +76,9 @@ pub trait Runner<World> {
     type Cli: StructOptInternal;
 
     /// Output events [`Stream`].
-    type EventStream: Stream<Item = parser::Result<event::Cucumber<World>>>;
+    type EventStream: Stream<
+        Item = parser::Result<Event<event::Cucumber<World>>>,
+    >;
 
     /// Executes the given [`Stream`] of [`Feature`]s transforming it into
     /// a [`Stream`] of executed [`Cucumber`] events.

src/writer/basic.rs

@@ -29,7 +29,7 @@ use crate::{
     event::{self, Info},
     parser,
     writer::term::Styles,
-    ArbitraryWriter, World, Writer,
+    ArbitraryWriter, Event, World, Writer,
 };
 
 // Workaround for overwritten doc-comments.
@@ -105,7 +105,7 @@ impl<W: World + Debug> Writer<W> for Basic {
     #[allow(clippy::unused_async)] // false positive: #[async_trait]
     async fn handle_event(
         &mut self,
-        ev: parser::Result<event::Cucumber<W>>,
+        ev: parser::Result<Event<event::Cucumber<W>>>,
         cli: &Self::Cli,
     ) {
         use event::{Cucumber, Feature};
@@ -116,7 +116,7 @@ impl<W: World + Debug> Writer<W> for Basic {
             Coloring::Auto => {}
         };
 
-        match ev {
+        match ev.map(Event::into_inner) {
             Err(err) => self.parsing_failed(&err),
             Ok(Cucumber::Started | Cucumber::Finished) => Ok(()),
             Ok(Cucumber::Feature(f, ev)) => match ev {

src/writer/fail_on_skipped.rs

@@ -19,7 +19,9 @@ use std::sync::Arc;
 use async_trait::async_trait;
 use derive_more::Deref;
 
-use crate::{event, parser, ArbitraryWriter, FailureWriter, World, Writer};
+use crate::{
+    event, parser, ArbitraryWriter, Event, FailureWriter, World, Writer,
+};
 
 /// [`Writer`]-wrapper for transforming [`Skipped`] [`Step`]s into [`Failed`].
 ///
@@ -63,7 +65,7 @@ where
 
     async fn handle_event(
         &mut self,
-        ev: parser::Result<event::Cucumber<W>>,
+        ev: parser::Result<Event<event::Cucumber<W>>>,
         cli: &Self::Cli,
     ) {
         use event::{
@@ -77,23 +79,27 @@ where
                 Step::Skipped
             };
 
-            Ok(Cucumber::scenario(f, r, sc, Scenario::Step(st, event)))
+            Cucumber::scenario(f, r, sc, Scenario::Step(st, event))
         };
 
-        let ev = match ev {
-            Ok(Cucumber::Feature(
-                f,
-                Feature::Rule(
-                    r,
-                    Rule::Scenario(sc, Scenario::Step(st, Step::Skipped)),
-                ),
-            )) => map_failed(f, Some(r), sc, st),
-            Ok(Cucumber::Feature(
-                f,
-                Feature::Scenario(sc, Scenario::Step(st, Step::Skipped)),
-            )) => map_failed(f, None, sc, st),
-            _ => ev,
-        };
+        let ev = ev.map(|ev| {
+            ev.map(|ev| match ev {
+                Cucumber::Feature(
+                    f,
+                    Feature::Rule(
+                        r,
+                        Rule::Scenario(sc, Scenario::Step(st, Step::Skipped)),
+                    ),
+                ) => map_failed(f, Some(r), sc, st),
+                Cucumber::Feature(
+                    f,
+                    Feature::Scenario(sc, Scenario::Step(st, Step::Skipped)),
+                ) => map_failed(f, None, sc, st),
+                Cucumber::Started
+                | Cucumber::Feature(..)
+                | Cucumber::Finished => ev,
+            })
+        });
 
         self.writer.handle_event(ev, cli).await;
     }