Cucumber (Cucumber v1.0.0)

A behavior-driven development (BDD) testing framework for Elixir using Gherkin syntax.

Cucumber is a testing framework that allows you to write executable specifications in natural language. It bridges the gap between technical and non-technical stakeholders by allowing tests to be written in plain language while being executed as code.

Setup

Add to your test_helper.exs:

Cucumber.compile_features!()

File Structure

By default, Cucumber expects the following structure:

test/
  features/
    authentication.feature
    shopping.feature
    step_definitions/
      authentication_steps.exs
      shopping_steps.exs
      common_steps.exs
    support/
      hooks.exs

Configuration

You can customize paths in config/test.exs:

config :cucumber,
  features: ["test/features/**/*.feature"],
  steps: ["test/features/step_definitions/**/*.exs"]

Setting messages: "cucumber-messages.ndjson" additionally writes a Cucumber Messages NDJSON stream describing the run — see Cucumber.Messages.

Step Definitions

Create step definition modules using Cucumber.StepDefinition:

defmodule AuthenticationSteps do
  use Cucumber.StepDefinition

  step "I am logged in as {string}", %{args: [username]} = context do
    {:ok, Map.put(context, :current_user, username)}
  end
end

Running Tests

Cucumber tests run with mix test and can be filtered using tags:

# Run all tests including Cucumber
mix test

# Run only Cucumber tests
mix test --only cucumber

# Exclude Cucumber tests
mix test --exclude cucumber

Key Features

Auto-discovery of features and step definitions
Integration with ExUnit's tagging system
Context passing between steps
Support for data tables and doc strings
Rich error reporting with suggestions

Summary

Functions

attach(context, data, media_type, opts \\ [])

Attaches data to the current step (or hook execution) for reporting.

compile_features!(opts \\ [])

Discovers and compiles all cucumber features into ExUnit tests.

link(context, uri)

Attaches a link to the current step.

log(context, text)

Attaches a log message to the current step.

Functions

attach(context, data, media_type, opts \\ [])

@spec attach(map(), String.t() | {:bytes, binary()}, String.t(), keyword()) :: map()

Attaches data to the current step (or hook execution) for reporting.

Mirrors the attach API of reference Cucumber implementations: useful for capturing screenshots, response payloads, or logs while a scenario runs. Attachments are recorded against the step that attached them; until a step fails they are invisible, then they are listed in the failure output. (Cucumber Messages formatters will render them in reports, #28.)

data is either a string (attached as-is) or {:bytes, binary} for binary data, which is Base64-encoded — Elixir can't tell text from bytes by type, so binary data is marked explicitly.

Returns the context unchanged, so it composes with any step return style.

Options

:filename - a file name for the attachment (e.g. "screenshot.png")

Examples

step "I take a screenshot", context do
  Cucumber.attach(context, {:bytes, screenshot()}, "image/png",
    filename: "checkout.png"
  )
end

step "the API responds", context do
  context
  |> Cucumber.attach(response.body, "application/json")
  |> Map.put(:response, response)
end