Getting Started with Cucumber for Elixir

View Source

Cucumber for Elixir allows you to write executable specifications using natural language that bridges the gap between technical and non-technical stakeholders.

Overview

The Cucumber framework allows you to write tests in a natural language format using Gherkin syntax. This approach enables:

  • Behavior-driven development (BDD)
  • Clear documentation of application behavior
  • Tests that serve as living documentation

Installation

Add cucumber to your mix.exs dependencies:

def deps do
  [
    {:cucumber, "~> 0.1.0"}
  ]
end

Quick Start

1. Create a Feature File

Feature files use the Gherkin syntax and should be placed in test/features/ with a .feature extension.

# test/features/user_authentication.feature
Feature: User Authentication

Background:
  Given the application is running

Scenario: User signs in with valid credentials
  Given I am on the sign in page
  When I enter "user@example.com" as my email
  And I enter "password123" as my password
  And I click the "Sign In" button
  Then I should be redirected to the dashboard
  And I should see "Welcome back" message

2. Create a Test Module

Create a test module that uses the Cucumber macro:

defmodule UserAuthenticationTest do
  use Cucumber, feature: "user_authentication.feature"
  
  # Step definitions
  defstep "the application is running" do
    # Setup code here
    :ok
  end
  
  defstep "I am on the sign in page", context do
    # Navigate to sign in page
    Map.put(context, :current_page, :sign_in)
  end
  
  defstep "I enter {string} as my email", context do
    email = List.first(context.args)
    # Code to enter email
    Map.put(context, :email, email)
  end

  defstep "I enter {string} as my password", context do
    password = List.first(context.args)
    # Code to enter password
    Map.put(context, :password, password)
  end
  
  defstep "I click the {string} button", context do
    button_text = List.first(context.args)
    # Code to click button
    {:ok, %{clicked: button_text}}
  end
  
  defstep "I should be redirected to the dashboard", context do
    # Assertions for redirection
    assert context.current_page == :dashboard
    :ok
  end
  
  defstep "I should see {string} message", context do
    message = List.first(context.args)
    # Assertion for message
    assert_text(message)
    :ok
  end
end

3. Run Your Tests

Run your tests using the standard mix test command:

mix test test/lib/user_authentication_test.exs

Next Steps

For more detailed information about the Cucumber for Elixir framework, check out these guides: