cucumber-rs

Cucumber allows you to output test results in several formats to suit different needs, such as human-readable terminal output, machine-readable reports for CI/CD, or integration with specific IDEs.

Available output methods include:

• Terminal: Standard human-readable output in the console.
• JUnit XML report: XML format compatible with JUnit-based test runners and CI tools.
• Cucumber JSON format: Standard Cucumber JSON format for compatibility with other Cucumber ecosystems.
• Multiple outputs: Configuring the runner to emit several formats simultaneously.
• tracing integration: Using the Rust tracing ecosystem for structured logging of test execution.
• IntelliJ Rust (libtest) integration: Formatting output to be compatible with IntelliJ Rust's test runner.

In cucumber, the World is a struct that holds the state for your test scenarios. You implement the cucumber::World trait on your struct using the #[derive(Debug, Default, cucumber::World)] macro. This state is then passed as a mutable reference (&mut World) to your step definitions, allowing you to share data between Given, When, and Then steps.

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

Cucumber is built as a modular framework composed of three primary, replaceable components. This design allows you to extend the framework for exotic requirements (such as sourcing features from a distributed queue or executing them on a remote cluster) by implementing custom versions of these components.

The three core components are:

1. Parser: Responsible for sourcing feature files. The default implementation is parser::Basic, which parses standard .feature files.
2. Runner: Responsible for executing the scenarios provided by a Parser and emitting events. The default implementation is runner::Basic, which executes scenarios concurrently.
3. Writer: Responsible for outputting the events emitted by the Runner. The default implementation is writer::Basic, which outputs to STDOUT.

The Rule keyword is used in Gherkin feature files to represent a specific business rule that needs to be implemented. It serves as a grouping mechanism for one or more Scenarios that illustrate that particular rule.

Note that using Rule in your Gherkin files requires no additional implementation work in your Rust code; it is purely for organizing and providing additional context to your features.

Feature: Animal feature
    
  Rule: Hungry cat becomes satiated
      
    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
    
  Rule: Satiated cat remains the same
      
    Scenario: If we feed a satiated cat it will not become hungry
      Given a satiated cat
      When I feed the cat
      Then the cat is not hungry

Tags applied to higher-level elements are automatically inherited by their children:

• Feature and Rule tags are inherited by Scenario, Scenario Outline, and Examples.
• Scenario Outline tags are inherited by its Examples blocks.

Note that you can also apply specific tags directly to individual Examples blocks within a Scenario Outline to differentiate them.

Important: You cannot place tags above Background or individual steps (Given, When, Then, etc.).

@feature
Feature: Animal feature

  @scenario
  Scenario Outline: If we feed a hungry animal it will no longer be hungry
    Given a hungry <animal>
    When I feed the <animal> <n> times
    Then the <animal> is not hungry

  @home
  Examples:
    | animal | n |
    | cat    | 2 |
    | dog    | 3 |

  @dire
  Examples:
    | animal | n |
    | lion   | 1 |
    | wolf   | 1 |

The World is a shared, mutable state object that holds the data for your test scenario. Cucumber constructs a new instance of your World using Default::default() for every individual scenario, ensuring test isolation.

To define a World, derive the World trait on a struct. Step functions then receive a mutable reference to this struct (&mut MyWorld) to read or modify the state.

#[derive(Debug, Default, World)]
pub struct AnimalWorld {
    cat: Cat,
}

#[given("a hungry cat")]
fn hungry_cat(world: &mut AnimalWorld) {
    world.cat.hungry = true;
}

The Writer sits at the end of the Cucumber execution pipeline. The Runner produces a stream of event::Cucumber<W> events, where W is your World type.

Events follow a hierarchical structure:

1. event::Cucumber: The top-level wrapper for all events.
2. event::Feature: Represents the lifecycle of a Gherkin feature (e.g., Started, Finished).
3. event::Scenario: Nested within a feature, representing scenario lifecycle.
4. event::Step: Nested within a scenario, representing individual step execution (e.g., Started, Passed, Failed, Skipped).

By implementing Writer, you can intercept these specific moments to generate custom reports or real-time console feedback.

The cucumber crate provides built-in support for the @serial tag. Any scenario marked with @serial will be executed in isolation, ensuring no other scenarios are running concurrently during its execution. This is useful for tests that require exclusive access to resources.

Tip: If you want to run your entire test suite serially instead of tagging every feature, use the --concurrency=1 CLI option.

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