dream_test - v2.0.0

dream_test/gherkin/feature

Convert Gherkin features into runnable TestSuites.

This module does two related jobs:

Example (file-based)

pub fn tests() {
  // Define step handlers
  let steps =
    steps.new()
    |> step("the server is running", step_server_running)
    |> step("the cart is empty", step_empty_cart)
    |> step("I add {int} items", step_add_items)
    |> step("the cart should have {int} items", step_verify_count)

  // Parse the .feature file
  let assert Ok(feature) = parser.parse_file("test/cart.feature")

  // Convert to TestSuite and run
  let config = FeatureConfig(feature: feature, step_registry: steps)
  to_test_suite(config)
}

Example (inline DSL)

pub fn tests() {
  let steps =
    steps.new()
    |> step("the server is running", step_server_running)
    |> step("the cart is empty", step_empty_cart)
    |> step("I add {int} items", step_add_items)
    |> step("the cart should have {int} items", step_verify_count)

  let bg = background([given("the server is running")])

  feature_with_background("Shopping Cart", steps, bg, [
    scenario("Adding items", [
      given("the cart is empty"),
      when("I add 3 items"),
      then("the cart should have 3 items"),
    ])
      |> with_tags(["smoke"]),
    scenario("Adding more items", [
      given("the cart is empty"),
      when("I add 2 items"),
      and("I add 3 items"),
      then("the cart should have 5 items"),
    ]),
  ])
}

Types

FeatureConfig

</>

Configuration for running a feature.

Contains the parsed feature and step registry needed to execute it.

pub type FeatureConfig {
  FeatureConfig(
    feature: types.Feature,
    step_registry: steps.StepRegistry,
  )
}

Constructors 

  • FeatureConfig(
  feature: types.Feature,
  step_registry: steps.StepRegistry,
)

    Arguments

    feature

    The parsed feature to run

    step_registry

    Registry of step definitions

InlineScenario

</>

Configuration for an inline scenario.

Used with the inline DSL to define scenarios in Gleam code.

pub type InlineScenario {
  InlineScenario(
    name: String,
    steps: List(InlineStep),
    tags: List(String),
  )
}

Constructors 

  • InlineScenario(
  name: String,
  steps: List(InlineStep),
  tags: List(String),
)

    Arguments

    name

    Scenario name

    steps

    List of step text (e.g., [“Given I have 5 items”, “When I add 3”])

    tags

    Tags for filtering (e.g., [“happy-path”, “smoke”])

InlineStep

</>

An inline step for the DSL.

pub type InlineStep {
  InlineStep(keyword: String, text: String)
}

Constructors 

  • InlineStep(keyword: String, text: String)

    Arguments

    keyword

    Step keyword as string (“Given”, “When”, “Then”, “And”, “But”)

    text

    Step text after the keyword

Values

and

</> 
pub fn and(text text: String) -> InlineStep

Create an And step for inline DSL.

Example

      and("I add 3 items"),

background

</> 
pub fn background(
  inline_steps inline_steps: List(InlineStep),
) -> List(types.Step)

Define a background for inline features.

Background steps run before each scenario.

Example

let bg = background([given("the server is running")])

but

</> 
pub fn but(text text: String) -> InlineStep

Create a But step for inline DSL.

Example

      but("I should have 5 items total"),

feature

</> 
pub fn feature(
  name name: String,
  registry registry: steps.StepRegistry,
  scenarios scenarios: List(InlineScenario),
) -> types.Root(Nil)

Define a feature inline in Gleam code.

Creates a TestSuite from inline scenario definitions without needing a .feature file.

Parameters

  • name: Feature name
  • registry: Step registry with step definitions
  • scenarios: List of inline scenarios

Returns

A TestSuite that can be run with runner.new([suite]) |> runner.run().

Example

let steps =
  steps.new()
  |> step("I have {int} items in my cart", step_have_items)
  |> step("I add {int} more items", step_add_items)
  |> step("I should have {int} items total", step_should_have)

feature("Shopping Cart", steps, [
  scenario("Adding items to cart", [
    given("I have 3 items in my cart"),
    when("I add 2 more items"),
    then("I should have 5 items total"),
    but("I should have 5 items total"),
  ]),
])

feature_with_background

</> 
pub fn feature_with_background(
  name name: String,
  registry registry: steps.StepRegistry,
  background_steps background_steps: List(types.Step),
  scenarios scenarios: List(InlineScenario),
) -> types.Root(Nil)

Define a feature with a background.

Parameters

  • name: Feature name
  • registry: Step registry
  • background_steps: Steps to run before each scenario
  • scenarios: List of inline scenarios

Example

let bg = background([given("the server is running")])

feature_with_background("Shopping Cart", steps, bg, [
  scenario("Adding items", [
    given("the cart is empty"),
    when("I add 3 items"),
    then("the cart should have 3 items"),
  ])
    |> with_tags(["smoke"]),
  scenario("Adding more items", [
    given("the cart is empty"),
    when("I add 2 items"),
    and("I add 3 items"),
    then("the cart should have 5 items"),
  ]),
])

given

</> 
pub fn given(text text: String) -> InlineStep

Create a Given step for inline DSL.

Example

      given("the cart is empty"),

scenario

</> 
pub fn scenario(
  name name: String,
  inline_steps inline_steps: List(InlineStep),
) -> InlineScenario

Define an inline scenario.

Parameters

  • name: Scenario name
  • steps: List of inline steps

Example

scenario("Adding items to cart", [
      given("I have 3 items in my cart"),
      when("I add 2 more items"),
      then("I should have 5 items total"),
      but("I should have 5 items total"),
    ]),

then

</> 
pub fn then(text text: String) -> InlineStep

Create a Then step for inline DSL.

Example

      then("the cart should have 3 items"),

to_test_suite

</> 
pub fn to_test_suite(
  config config: FeatureConfig,
) -> types.Root(Nil)

Convert a Feature to a TestSuite.

Creates a TestSuite with one test per scenario. Background steps are prepended to each scenario. ScenarioOutlines are expanded based on their examples table.

Parameters

  • config: FeatureConfig with feature and step registry

Returns

A TestSuite that can be run with runner.new([suite]) |> runner.run().

Example

let config = FeatureConfig(feature: feature, step_registry: steps)
to_test_suite(config)

when

</> 
pub fn when(text text: String) -> InlineStep

Create a When step for inline DSL.

Example

      when("I add 3 items"),

with_tags

</> 
pub fn with_tags(
  inline_scenario inline_scenario: InlineScenario,
  tags tags: List(String),
) -> InlineScenario

Add tags to a Gherkin scenario for filtering.

Example

scenario("Adding items", [
      given("the cart is empty"),
      when("I add 3 items"),
      then("the cart should have 3 items"),
    ])
      |> with_tags(["smoke"]),

Note

This function is for Gherkin scenarios. For unit tests (it), use dream_test/unit.with_tags instead.

✨ Search Document