Struct cucumber::Cucumber

pub struct Cucumber<W, P, I, R, Wr, Cli = Empty> where
    W: World,
    P: Parser<I>,
    R: Runner<W>,
    Wr: Writer<W>,
    Cli: Args,  { /* fields omitted */ }

Top-level Cucumber executor.

Most of the time you don’t need to work with it directly, just use WorldInit::run() or WorldInit::cucumber() on your World deriver to get Cucumber up and running.

Otherwise use Cucumber::new() to get the default Cucumber executor, provide Steps with WorldInit::collection() or by hand with Cucumber::given(), Cucumber::when() and Cucumber::then().

In case you want a custom Parser, Runner or Writer, or some other finer control, use Cucumber::custom() or Cucumber::with_parser(), Cucumber::with_runner() and Cucumber::with_writer() to construct your dream Cucumber executor!

Implementations

impl<W, P, I, R, Wr, Cli> Cucumber<W, P, I, R, Wr, Cli> where
    W: World,
    P: Parser<I>,
    R: Runner<W>,
    Wr: Writer<W>,
    Cli: Args, 

pub fn custom(parser: P, runner: R, writer: Wr) -> Self

Creates a custom Cucumber executor with the provided Parser, Runner and Writer.

pub fn with_parser<NewP, NewI>(
    self,
    parser: NewP
) -> Cucumber<W, NewP, NewI, R, Wr, Cli> where
    NewP: Parser<NewI>, 

Replaces Parser.

pub fn with_runner<NewR>(self, runner: NewR) -> Cucumber<W, P, I, NewR, Wr, Cli> where
    NewR: Runner<W>, 

Replaces Runner.

pub fn with_writer<NewWr>(
    self,
    writer: NewWr
) -> Cucumber<W, P, I, R, NewWr, Cli> where
    NewWr: Writer<W>, 

Replaces Writer.

pub fn repeat_skipped(self) -> Cucumber<W, P, I, R, Repeat<W, Wr>, Cli> where
    Wr: NonTransforming, 

Re-outputs Skipped steps for easier navigation.

Example

Output with a regular Cucumber::run():

Adjust Cucumber to re-output all the Skipped steps at the end:

MyWorld::cucumber()
    .repeat_skipped()
    .run_and_exit("tests/features/readme")
    .await;

pub fn repeat_failed(self) -> Cucumber<W, P, I, R, Repeat<W, Wr>, Cli> where
    Wr: NonTransforming, 

Re-outputs Failed steps for easier navigation.

Example

Output with a regular Cucumber::fail_on_skipped():

MyWorld::cucumber()
    .fail_on_skipped()
    .run_and_exit("tests/features/readme")
    .await;

Adjust Cucumber to re-output all the Failed steps at the end:

MyWorld::cucumber()
    .repeat_failed()
    .fail_on_skipped()
    .run_and_exit("tests/features/readme")
    .await;

pub fn repeat_if<F>(
    self,
    filter: F
) -> Cucumber<W, P, I, R, Repeat<W, Wr, F>, Cli> where
    F: Fn(&Result<Event<Cucumber<W>>>) -> bool,
    Wr: NonTransforming, 

Re-outputs steps by the given filter predicate.

Example

Output with a regular Cucumber::fail_on_skipped():

MyWorld::cucumber()
    .fail_on_skipped()
    .run_and_exit("tests/features/readme")
    .await;

Adjust Cucumber to re-output all the Failed steps ta the end by providing a custom filter predicate:

MyWorld::cucumber()
    .repeat_if(|ev| {
        use cucumber::event::{Cucumber, Feature, Rule, Scenario, Step};

        matches!(
            ev.as_deref(),
            Ok(Cucumber::Feature(
                _,
                Feature::Rule(
                    _,
                    Rule::Scenario(
                        _,
                        Scenario::Step(_, Step::Failed(..))
                            | Scenario::Background(_, Step::Failed(..))
                    )
                ) | Feature::Scenario(
                    _,
                    Scenario::Step(_, Step::Failed(..))
                        | Scenario::Background(_, Step::Failed(..))
                )
            )) | Err(_)
        )
    })
    .fail_on_skipped()
    .run_and_exit("tests/features/readme")
    .await;

impl<W, P, I, R, Wr, Cli> Cucumber<W, P, I, R, Wr, Cli> where
    W: World,
    P: Parser<I>,
    R: Runner<W>,
    Wr: Writer<W> + for<'val> Arbitrary<'val, W, String>,
    Cli: Args, 

pub fn fail_on_skipped(self) -> Cucumber<W, P, I, R, FailOnSkipped<Wr>, Cli>

Consider Skipped steps as Failed if their Scenario isn’t marked with @allow.skipped tag.

It’s useful option for ensuring that all the steps were covered.

Example

Output with a regular Cucumber::run():

To fail all the Skipped steps setup Cucumber like this:

MyWorld::cucumber()
    .fail_on_skipped()
    .run_and_exit("tests/features/readme")
    .await;

To intentionally suppress some Skipped steps failing, use the @allow.skipped tag:

Feature: Animal feature

  Scenario: If we feed a hungry cat it will no longer be hungry
    Given a hungry cat
    When I feed the cat
    Then the cat is not hungry

  @allow.skipped
  Scenario: If we feed a satiated dog it will not become hungry
    Given a satiated dog
    When I feed the dog
    Then the dog is not hungry

pub fn fail_on_skipped_with<Filter>(
    self,
    filter: Filter
) -> Cucumber<W, P, I, R, FailOnSkipped<Wr, Filter>, Cli> where
    Filter: Fn(&Feature, Option<&Rule>, &Scenario) -> bool, 

Consider Skipped steps as Failed if the given filter predicate returns true.

Example

Output with a regular Cucumber::run():

Adjust Cucumber to fail on all Skipped steps, but the ones marked with a @dog tag:

MyWorld::cucumber()
    .fail_on_skipped_with(|_, _, s| !s.tags.iter().any(|t| t == "dog"))
    .run_and_exit("tests/features/readme")
    .await;

Feature: Animal feature

  Scenario: If we feed a hungry cat it will no longer be hungry
    Given a hungry cat
    When I feed the cat
    Then the cat is not hungry

  Scenario: If we feed a satiated dog it will not become hungry
    Given a satiated dog
    When I feed the dog
    Then the dog is not hungry

And to avoid failing, use the @dog tag:

Feature: Animal feature

  Scenario: If we feed a hungry cat it will no longer be hungry
    Given a hungry cat
    When I feed the cat
    Then the cat is not hungry

  @dog
  Scenario: If we feed a satiated dog it will not become hungry
    Given a satiated dog
    When I feed the dog
    Then the dog is not hungry

impl<W, P, I, R, Wr, Cli> Cucumber<W, P, I, R, Wr, Cli> where
    W: World,
    P: Parser<I>,
    R: Runner<W>,
    Wr: Writer<W> + Normalized,
    Cli: Args, 

pub async fn run(self, input: I) -> Wr

Runs Cucumber.

Features sourced from a Parser are fed to a Runner, which produces events handled by a Writer.

pub fn with_cli<CustomCli>(
    self,
    cli: Opts<P::Cli, R::Cli, Wr::Cli, CustomCli>
) -> Cucumber<W, P, I, R, Wr, CustomCli> where
    CustomCli: Args, 

Consumes already parsed cli::Opts.

This method allows to pre-parse cli::Opts for custom needs before using them inside Cucumber.

Also, any additional custom CLI options may be specified as a clap::Args deriving type, used as the last type parameter of cli::Opts.

⚠️ WARNING: Any CLI options of Parser, Runner, Writer or custom ones should not overlap, otherwise cli::Opts will fail to parse on startup.

Example

#[derive(clap::Args)]
struct CustomCli {
    /// Additional time to wait in a before hook.
    #[clap(
        long,
        parse(try_from_str = humantime::parse_duration)
    )]
    before_time: Option<Duration>,
}

let cli = cli::Opts::<_, _, _, CustomCli>::parsed();
let time = cli.custom.before_time.unwrap_or_default();

MyWorld::cucumber()
    .before(move |_, _, _, _| time::sleep(time).boxed_local())
    .with_cli(cli)
    .run_and_exit("tests/features/readme")
    .await;

Feature: Animal feature

  Scenario: If we feed a hungry cat it will no longer be hungry
    Given a hungry cat
    When I feed the cat
    Then the cat is not hungry

Also, specifying --help flag will describe --before-time now.

pub async fn filter_run<F>(self, input: I, filter: F) -> Wr where
    F: Fn(&Feature, Option<&Rule>, &Scenario) -> bool + 'static, 

Runs Cucumber with Scenarios filter.

Features sourced from a Parser are fed to a Runner, which produces events handled by a Writer.

Example

Adjust Cucumber to run only Scenarios marked with @cat tag:

MyWorld::cucumber()
    .filter_run("tests/features/readme", |_, _, sc| {
        sc.tags.iter().any(|t| t == "cat")
    })
    .await;

Feature: Animal feature

  @cat
  Scenario: If we feed a hungry cat it will no longer be hungry
    Given a hungry cat
    When I feed the cat
    Then the cat is not hungry

  @dog
  Scenario: If we feed a satiated dog it will not become hungry
    Given a satiated dog
    When I feed the dog
    Then the dog is not hungry

impl<W, I> Cucumber<W, Basic, I, Basic<W>, Summarize<Normalize<W, Basic>>> where
    W: World + Debug,
    I: AsRef<Path>, 

pub fn new() -> Self

Creates a default Cucumber executor.

• Parser — parser::Basic

• Runner — runner::Basic

  • ScenarioType — Concurrent by default, Serial if @serial tag is present on a Scenario;
  • Allowed to run up to 64 Concurrent Scenarios.

• Writer — Normalize and Summarize writer::Basic.

impl<W, I, R, Wr, Cli> Cucumber<W, Basic, I, R, Wr, Cli> where
    W: World,
    R: Runner<W>,
    Wr: Writer<W>,
    Cli: Args,
    I: AsRef<Path>, 

pub fn language(
    self,
    name: impl Into<Cow<'static, str>>
) -> Result<Self, UnsupportedLanguageError>

Sets the provided language of gherkin files.

Errors

If the provided language isn’t supported.

impl<W, I, P, Wr, F, B, A, Cli> Cucumber<W, P, I, Basic<W, F, B, A>, Wr, Cli> where
    W: World,
    P: Parser<I>,
    Wr: Writer<W>,
    Cli: Args,
    F: Fn(&Feature, Option<&Rule>, &Scenario) -> ScenarioType + 'static,
    B: for<'a> Fn(&'a Feature, Option<&'a Rule>, &'a Scenario, &'a mut W) -> LocalBoxFuture<'a, ()> + 'static,
    A: for<'a> Fn(&'a Feature, Option<&'a Rule>, &'a Scenario, Option<&'a mut W>) -> LocalBoxFuture<'a, ()> + 'static, 

pub fn max_concurrent_scenarios(self, max: impl Into<Option<usize>>) -> Self

If max is Some number of concurrently executed Scenarios will be limited.

pub fn which_scenario<Which>(
    self,
    func: Which
) -> Cucumber<W, P, I, Basic<W, Which, B, A>, Wr, Cli> where
    Which: Fn(&Feature, Option<&Rule>, &Scenario) -> ScenarioType + 'static, 

Function determining whether a Scenario is Concurrent or a Serial one.

pub fn before<Before>(
    self,
    func: Before
) -> Cucumber<W, P, I, Basic<W, F, Before, A>, Wr, Cli> where
    Before: for<'a> Fn(&'a Feature, Option<&'a Rule>, &'a Scenario, &'a mut W) -> LocalBoxFuture<'a, ()> + 'static, 

Sets a hook, executed on each Scenario before running all its Steps, including Background ones.

pub fn after<After>(
    self,
    func: After
) -> Cucumber<W, P, I, Basic<W, F, B, After>, Wr, Cli> where
    After: for<'a> Fn(&'a Feature, Option<&'a Rule>, &'a Scenario, Option<&'a mut W>) -> LocalBoxFuture<'a, ()> + 'static, 

Sets a hook, executed on each Scenario after running all its Steps, even after Skipped of Failed Steps.

Last World argument is supplied to the function, in case it was initialized before by running before hook or any non-failed Step. In case the last Scenario’s Step failed, we want to return event with an exact World state. Also, we don’t want to impose additional Clone bounds on World, so the only option left is to pass None to the function.

pub fn steps(self, steps: Collection<W>) -> Self

Replaces Collection of Steps.

pub fn given(self, regex: Regex, step: Step<W>) -> Self

Inserts Given Step.

pub fn when(self, regex: Regex, step: Step<W>) -> Self

Inserts When Step.

pub fn then(self, regex: Regex, step: Step<W>) -> Self

Inserts Then Step.

impl<W, I, P, R, Wr, Cli> Cucumber<W, P, I, R, Wr, Cli> where
    W: World,
    P: Parser<I>,
    R: Runner<W>,
    Wr: Failure<W> + Normalized,
    Cli: Args, 

pub async fn run_and_exit(self, input: I)

Runs Cucumber.

Features sourced from a Parser are fed to a Runner, which produces events handled by a Writer.

Panics

If encountered errors while parsing Features or at least one Step Failed.

pub async fn filter_run_and_exit<Filter>(self, input: I, filter: Filter) where
    Filter: Fn(&Feature, Option<&Rule>, &Scenario) -> bool + 'static, 

Runs Cucumber with Scenarios filter.

Features sourced from a Parser are fed to a Runner, which produces events handled by a Writer.

Panics

If encountered errors while parsing Features or at least one Step Failed.

Example

Adjust Cucumber to run only Scenarios marked with @cat tag:

MyWorld::cucumber()
    .filter_run_and_exit("tests/features/readme", |_, _, sc| {
        sc.tags.iter().any(|t| t == "cat")
    })
    .await;

Feature: Animal feature

  @cat
  Scenario: If we feed a hungry cat it will no longer be hungry
    Given a hungry cat
    When I feed the cat
    Then the cat is not hungry

  @dog
  Scenario: If we feed a satiated dog it will not become hungry
    Given a satiated dog
    When I feed the dog
    Then the dog is not hungry

Trait Implementations

impl<W, P, I, R, Wr, Cli> Debug for Cucumber<W, P, I, R, Wr, Cli> where
    W: World,
    P: Debug + Parser<I>,
    R: Debug + Runner<W>,
    Wr: Debug + Writer<W>,
    Cli: Args, 

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<W, I> Default for Cucumber<W, Basic, I, Basic<W>, Summarize<Normalize<W, Basic>>> where
    W: World + Debug,
    I: AsRef<Path>, 

fn default() -> Self

Returns the “default value” for a type.