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,
{ /* private fields */ }

Top-level Cucumber executor.

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

Otherwise use Cucumber::new() to get the default Cucumber executor, provide Steps with World::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 const 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, RetryableScenario, Rule, Scenario, Step,
        };

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

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

Consider Skipped Background or regular 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 Background or regular 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.
    #[arg(
        long,
        value_parser = 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 fn with_default_cli(self) -> Self

where Opts<P::Cli, R::Cli, Wr::Cli, Cli>: Default,

Initializes Default cli::Opts.

This method allows to omit parsing real cli::Opts, as eagerly initializes Default ones instead.

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, &'a ScenarioFinished, 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 retries(self, retries: impl Into<Option<usize>>) -> Self

Makes failed Scenarios being retried the specified number of times.

pub fn fail_fast(self) -> Self

Makes stop running tests on the first failure.

NOTE: All the already started Scenarios at the moment of failure will be finished.

NOTE: Retried Scenarios are considered as failed, only in case they exhaust all retry attempts and still do fail.

pub fn retry_after(self, after: impl Into<Option<Duration>>) -> Self

Makes failed Scenarios being retried after the specified Duration passes.

pub fn retry_filter( self, tag_expression: impl Into<Option<TagOperation>> ) -> Self

Makes failed Scenarios being retried only if they’re matching the specified tag_expression.

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 retry_options<Retry>(self, func: Retry) -> Self

where Retry: Fn(&Feature, Option<&Rule>, &Scenario, &Cli) -> Option<RetryOptions> + 'static,

Function determining Scenario’s RetryOptions.

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, &'a ScenarioFinished, 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 Step.

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: Stats<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

impl<W, P, I, Wr, Cli, WhichSc, Before, After> Cucumber<W, P, I, Basic<W, WhichSc, Before, After>, Wr, Cli>

where W: World, P: Parser<I>, Basic<W, WhichSc, Before, After>: Runner<W>, Wr: Writer<W>, Cli: Args,

pub fn init_tracing(self) -> Self

Available on crate feature tracing only.

Initializes a global tracing::Subscriber with a default fmt::Layer and LevelFilter::INFO.

pub fn configure_and_init_tracing<Event, Fields, Sub, Conf, Out>( self, fmt_fields: Fields, event_format: Event, configure: Conf ) -> Self

where Fields: for<'a> FormatFields<'a> + 'static, Event: FormatEvent<Sub, SkipScenarioIdSpan<Fields>> + 'static, Sub: Subscriber + for<'a> LookupSpan<'a>, Out: Subscriber + Send + Sync, Conf: FnOnce(Layered<Layer<Sub, SkipScenarioIdSpan<Fields>, AppendScenarioMsg<Event>, CollectorWriter>, RecordScenarioId, Sub>) -> Out,

Available on crate feature tracing only.

Configures a fmt::Layer, additionally wraps it (for example, into a LevelFilter), and initializes as a global tracing::Subscriber.

Example

World::cucumber()
    .configure_and_init_tracing(
        format::DefaultFields::new(),
        Format::default(),
        |fmt_layer| {
            tracing_subscriber::registry()
                .with(LevelFilter::INFO.and_then(fmt_layer))
        },
    )
    .run_and_exit("./tests/features/doctests.feature")
    .await

Trait Implementations

impl<W, P, I, R, Wr, Cli> Clone for Cucumber<W, P, I, R, Wr, Cli>

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

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<W, P, I, R, Wr, Cli> Debug for Cucumber<W, P, I, R, Wr, Cli>

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

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.