Crate cucumber

Cucumber testing framework for Rust

An implementation of the Cucumber testing framework for Rust. Fully native, no external test runners or dependencies.

• Book (current | edge)
• Changelog

Usage

Describe testing scenarios in .feature files:

Feature: Eating too much cucumbers may not be good for you
    
  Scenario: Eating a few isn't a problem
    Given Alice is hungry
    When she eats 3 cucumbers
    Then she is full

Implement World trait and describe steps:

use std::time::Duration;

use cucumber::{given, then, when, World as _};
use tokio::time::sleep;

#[derive(cucumber::World, Debug, Default)]
struct World {
    user: Option<String>,
    capacity: usize,
}

#[given(expr = "{word} is hungry")] // Cucumber Expression
async fn someone_is_hungry(w: &mut World, user: String) {
    sleep(Duration::from_secs(2)).await;
    
    w.user = Some(user);
}

#[when(regex = r"^(?:he|she|they) eats? (\d+) cucumbers?$")]
async fn eat_cucumbers(w: &mut World, count: usize) {
    sleep(Duration::from_secs(2)).await;

    w.capacity += count;
    
    assert!(w.capacity < 4, "{} exploded!", w.user.as_ref().unwrap());
}

#[then("she is full")]
async fn is_full(w: &mut World) {
    sleep(Duration::from_secs(2)).await;

    assert_eq!(w.capacity, 3, "{} isn't full!", w.user.as_ref().unwrap());
}

#[tokio::main]
async fn main() {
    World::run("tests/features/readme").await;
}

Add test to Cargo.toml:

[[test]]
name = "readme"
harness = false  # allows Cucumber to print output instead of libtest

For more examples check out the Book (current | edge).

Cargo features

• macros (default): Enables step attributes and auto-wiring.
• timestamps: Enables timestamps collecting for all Cucumber events.
• output-json (implies timestamps): Enables support for outputting in Cucumber JSON format.
• output-junit (implies timestamps): Enables support for outputting JUnit XML report.
• libtest (implies timestamps): Enables compatibility with Rust libtest’s JSON output format. Useful for IntelliJ Rust plugin integration.
• tracing: Enables integration with tracing crate.

Supporting crates

The full gamut of Cucumber’s Gherkin language is implemented by the gherkin crate. Most features of the Gherkin language are parsed already and accessible via the relevant structs.

Known issues

• Scenario Outline is treated the same as Outline or Example in the parser (gherkin/#19).

License

This project is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Re-exports

• pub use gherkin;

Modules

• cli
  Tools for composing CLI options.
• codegenmacros
  Helper type-level glue for cucumber_codegen crate.
• event
  Key occurrences in a lifecycle of Cucumber execution.
• feature
  gherkin::Feature extension.
• parser
  Tools for parsing Gherkin files.
• runner
  Tools for executing Steps.
• step
  Definitions for a Collection which is used to store Step Fns and corresponding Regex patterns.
• tag
  Extension of a TagOperation.
• tracingtracing
  tracing integration layer.
• writer
  Tools for outputting Cucumber events.

Structs

• Cucumber
  Top-level Cucumber executor.
• Event
  Arbitrary event, optionally paired with additional metadata.

Enums

• ScenarioType
  Type determining whether Scenarios should run concurrently or sequentially.

Traits

• ArbitraryWriter
  Writer that also can output an arbitrary Value in addition to regular Cucumber events.
• Parametermacros
  Custom parameter of a Cucumber Expression.
• Parser
  Source of parsed Features.
• Runner
  Executor of Parser output producing Cucumber events for Writer.
• StatsWriter
  Writer tracking a number of Passed, Skipped, Failed Steps and parsing errors.
• World
  Represents a shared user-defined state for a Cucumber run. It lives on per-scenario basis.
• Writer
  Writer of Cucumber events to some output.
• WriterExt
  Extension of Writer allowing its normalization and summarization.

Type Aliases

• Step
  Alias for a gherkin::Step function that returns a LocalBoxFuture.

Attribute Macros

• givenmacros
  Attribute to auto-wire the test to the World implementer.
• thenmacros
  Attribute to auto-wire the test to the World implementer.
• whenmacros
  Attribute to auto-wire the test to the World implementer.

Derive Macros

• Parametermacros
  In addition to default parameters of Cucumber Expressions, you may implement and use custom ones.
• Worldmacros
  Derive macro for implementing a World trait.