Support Cucumber Expressions (#124)

CHANGELOG.md

@@ -29,13 +29,15 @@ All user visible changes to `cucumber` crate will be documented in this file. Th
  - `writer::Normalized` trait required for `Writer`s in `Cucumber` running methods. ([#162])
  - `writer::NonTransforming` trait required for `writer::Repeat`. ([#162])
  - `writer::Summarizable` trait required for `writer::Summarize`. ([#162])
+- Support for [Cucumber Expressions] via `#[given(expr = ...)]`, `#[when(expr = ...)]` and `#[then(expr = ...)]` syntax. ([#157])
 
 ### Fixed
 
 - Template regex in `Scenario Outline` expansion from `<(\S+)>` to `<([^>\s]+)>`. ([#163])
 
 [#147]: /../../pull/147
 [#151]: /../../pull/151
+[#157]: /../../pull/157
 [#159]: /../../pull/159
 [#160]: /../../pull/160
 [#162]: /../../pull/162
@@ -263,4 +265,5 @@ All user visible changes to `cucumber` crate will be documented in this file. Th
 
 [`gherkin_rust`]: https://docs.rs/gherkin_rust
 
+[Cucumber Expressions]: https://cucumber.github.io/cucumber-expressions
 [Semantic Versioning 2.0.0]: https://semver.org

README.md

@@ -53,7 +53,7 @@ impl cucumber::World for World {
  }
 }
 
-#[given(regex = r"^(\S+) is hungry$")]
+#[given(expr = "{word} is hungry")]
 async fn someone_is_hungry(w: &mut World, user: String) {
  sleep(Duration::from_secs(2)).await;
 
@@ -69,7 +69,7 @@ async fn eat_cucumbers(w: &mut World, count: usize) {
  assert!(w.capacity < 4, "{} exploded!", w.user.as_ref().unwrap());
 }
 
-#[then(regex = r"^(?:he|she|they) (?:is|are) full$")]
+#[then(expr = "he/she/they is/are full")]
 async fn is_full(w: &mut World) {
  sleep(Duration::from_secs(2)).await;
 

book/src/Features.md

@@ -173,7 +173,7 @@ async fn cat_is_fed(world: &mut AnimalWorld) {
 <script id="asciicast-o1s4mSMYkkVBy4WAsG8lhYtT8" src="https://asciinema.org/a/o1s4mSMYkkVBy4WAsG8lhYtT8.js" async data-autoplay="true" data-rows="18"></script>
 
 
-### Combining `regex` and `FromStr`
+### Combining `regex`/`cucumber-expressions` and `FromStr`
 
 At parsing stage, `<templates>` are replaced by value from cells. That means you can parse table cells into any type, that implements [`FromStr`](https://doc.rust-lang.org/stable/std/str/trait.FromStr.html).
 
@@ -194,38 +194,42 @@ Feature: Animal feature
 
 ```rust
 # use std::{convert::Infallible, str::FromStr, time::Duration};
-# 
+#
 # use async_trait::async_trait;
 # use cucumber::{given, then, when, World, WorldInit};
 # use tokio::time::sleep;
-# 
-# #[derive(Debug)]
-# struct Cat {
-# pub hungry: bool,
-# }
-# 
-# impl Cat {
-# fn feed(&mut self) {
-# self.hungry = false;
-# }
-# }
-# 
-# #[derive(Debug, WorldInit)]
-# pub struct AnimalWorld {
-# cat: Cat,
-# }
-# 
-# #[async_trait(?Send)]
-# impl World for AnimalWorld {
-# type Error = Infallible;
-# 
-# async fn new() -> Result<Self, Infallible> {
-# Ok(Self {
-# cat: Cat { hungry: false },
-# })
-# }
-# }
-# 
+#
+#[derive(Debug)]
+struct AnimalState {
+ pub hungry: bool
+}
+
+impl AnimalState {
+ fn feed(&mut self) {
+ self.hungry = false;
+ }
+}
+
+#[derive(Debug, WorldInit)]
+pub struct AnimalWorld {
+ cat: AnimalState,
+ dog: AnimalState,
+ ferris: AnimalState,
+}
+
+#[async_trait(?Send)]
+impl World for AnimalWorld {
+ type Error = Infallible;
+
+ async fn new() -> Result<Self, Infallible> {
+ Ok(Self {
+ cat: AnimalState { hungry: false },
+ dog: AnimalState { hungry: false },
+ ferris: AnimalState { hungry: false },
+ })
+ }
+}
+
 enum State {
  Hungry,
  Satiated,
@@ -243,32 +247,65 @@ impl FromStr for State {
  }
 }
 
+enum Animal {
+ Cat,
+ Dog,
+ Ferris,
+}
+
+impl FromStr for Animal {
+ type Err = &'static str;
+
+ fn from_str(s: &str) -> Result<Self, Self::Err> {
+ match s {
+ "cat" => Ok(Self::Cat),
+ "dog" => Ok(Self::Dog),
+ "🦀" => Ok(Self::Ferris),
+ _ => Err("expected 'cat', 'dog' or '🦀'"),
+ }
+ }
+}
+
 #[given(regex = r"^a (\S+) (\S+)$")]
-async fn hungry_cat(world: &mut AnimalWorld, state: State) {
+async fn hungry_cat(world: &mut AnimalWorld, state: State, animal: Animal) {
  sleep(Duration::from_secs(2)).await;
 
- match state {
- State::Hungry => world.cat.hungry = true,
- State::Satiated => world.cat.hungry = false,
- }
+ let hunger = match state {
+ State::Hungry => true,
+ State::Satiated => false,
+ };
+
+ match animal {
+ Animal::Cat => world.cat.hungry = hunger,
+ Animal::Dog => world.dog.hungry = hunger,
+ Animal::Ferris => world.ferris.hungry = hunger,
+ };
 }
 
-#[when(regex = r"^I feed the (?:\S+) (\d+) times?$")]
-async fn feed_cat(world: &mut AnimalWorld, times: usize) {
+#[when(regex = r"^I feed the (\S+) (\d+) times?$")]
+async fn feed_cat(world: &mut AnimalWorld, animal: Animal, times: usize) {
  sleep(Duration::from_secs(2)).await;
 
  for _ in 0..times {
- world.cat.feed();
+ match animal {
+ Animal::Cat => world.cat.feed(),
+ Animal::Dog => world.dog.feed(),
+ Animal::Ferris => world.ferris.feed(),
+ };
  }
 }
 
-#[then(regex = r"^the (\S+) is not hungry$")]
-async fn cat_is_fed(world: &mut AnimalWorld) {
+#[then(expr = "the {word} is not hungry")]
+async fn cat_is_fed(world: &mut AnimalWorld, animal: Animal) {
  sleep(Duration::from_secs(2)).await;
 
- assert!(!world.cat.hungry);
+ match animal {
+ Animal::Cat => assert!(!world.cat.hungry),
+ Animal::Dog => assert!(!world.dog.hungry),
+ Animal::Ferris => assert!(!world.ferris.hungry),
+ };
 }
-# 
+#
 # #[tokio::main]
 # async fn main() {
 # AnimalWorld::run("/tests/features/book/features/scenario_outline_fromstr.feature").await;

book/src/Getting_Started.md

@@ -360,6 +360,64 @@ We surround regex with `^..$` to ensure the __exact__ match. This is much more u
 
 Captured groups are __bold__ to indicate which part of step could be dynamically changed. 
 
+Alternatively, you may use [Cucumber Expressions] for the same purpose (less powerful, but much more readable):
+```rust
+# use std::convert::Infallible;
+#
+# use async_trait::async_trait;
+# use cucumber::{given, then, when, World, WorldInit};
+#
+# #[derive(Debug)]
+# struct Cat {
+# pub hungry: bool,
+# }
+#
+# impl Cat {
+# fn feed(&mut self) {
+# self.hungry = false;
+# }
+# }
+#
+# #[derive(Debug, WorldInit)]
+# pub struct AnimalWorld {
+# cat: Cat,
+# }
+#
+# #[async_trait(?Send)]
+# impl World for AnimalWorld {
+# type Error = Infallible;
+#
+# async fn new() -> Result<Self, Infallible> {
+# Ok(Self {
+# cat: Cat { hungry: false },
+# })
+# }
+# }
+#
+#[given(expr = "a {word} cat")]
+fn hungry_cat(world: &mut AnimalWorld, state: String) {
+ match state.as_str() {
+ "hungry" => world.cat.hungry = true,
+ "satiated" => world.cat.hungry = false,
+ s => panic!("expected 'hungry' or 'satiated', found: {}", s),
+ }
+}
+#
+# #[when("I feed the cat")]
+# fn feed_cat(world: &mut AnimalWorld) {
+# world.cat.feed();
+# }
+#
+# #[then("the cat is not hungry")]
+# fn cat_is_fed(world: &mut AnimalWorld) {
+# assert!(!world.cat.hungry);
+# }
+#
+# fn main() {
+# futures::executor::block_on(AnimalWorld::run("/tests/features/book"));
+# }
+```
+
 A contrived example, but this demonstrates that steps can be reused as long as they are sufficiently precise in both their description and implementation. If, for example, the wording for our `Then` step was `The cat is no longer hungry`, it'd imply something about the expected initial state, when that is not the purpose of a `Then` step, but rather of the `Given` step.
 
 <details>
@@ -540,4 +598,5 @@ Feature: Animal feature
 
 
 [Cucumber]: https://cucumber.io
+[Cucumber Expressions]: https://cucumber.github.io/cucumber-expressions
 [Gherkin]: https://cucumber.io/docs/gherkin/reference

book/src/Test_Modules_Organization.md

@@ -19,7 +19,7 @@ Of course, how you group your step definitions is really up to you and your team
 
 ## Avoid duplication
 
-Avoid writing similar step definitions, as they can lead to clutter. While documenting your steps helps, making use of [`regex` and `FromStr`](Features.md#combining-regex-and-fromstr) can do wonders.
+Avoid writing similar step definitions, as they can lead to clutter. While documenting your steps helps, making use of [`regex`/`cucumber-expressions` and `FromStr`](Features.md#combining-regexcucumber-expressions-and-fromstr) can do wonders.
 
 
 

codegen/CHANGELOG.md

@@ -14,8 +14,10 @@ All user visible changes to `cucumber-codegen` crate will be documented in this
 ### Added
 
 - Unwrapping `Result`s returned by step functions. ([#151])
+- `expr = ...` argument to `#[given(...)]`, `#[when(...)]` and `#[then(...)]` attributes allowing [Cucumber Expressions]. ([#157])
 
 [#151]: /../../pull/151
+[#157]: /../../pull/157
 
 
 
@@ -76,4 +78,5 @@ See `cucumber` crate [changelog](https://github.com/cucumber-rs/cucumber/blob/v0
 
 
 
+[Cucumber Expressions]: https://cucumber.github.io/cucumber-expressions
 [Semantic Versioning 2.0.0]: https://semver.org

codegen/Cargo.toml

@@ -21,6 +21,7 @@ exclude = ["/tests/"]
 proc-macro = true
 
 [dependencies]
+cucumber-expressions = { version = "0.1", features = ["into-regex"] }
 inflections = "1.1"
 itertools = "0.10"
 proc-macro2 = "1.0.28"