Getting Started with Cucumber for Elixir
View SourceCucumber 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
- Auto-discovery of feature files and step definitions
Installation
Add cucumber
to your mix.exs
dependencies:
def deps do
[
{:cucumber, "~> 0.2.0"}
]
end
Quick Start
1. Configure Test Helper
Add Cucumber to your test/test_helper.exs
:
ExUnit.start()
Cucumber.compile_features!()
2. 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
3. Create Step Definitions
Create step definitions in test/features/step_definitions/
with a .exs
extension:
# test/features/step_definitions/authentication_steps.exs
defmodule AuthenticationSteps do
use Cucumber.StepDefinition
import ExUnit.Assertions
# Step definitions
step "the application is running" do
# Setup code here
%{app_started: true}
end
step "I am on the sign in page", context do
# Navigate to sign in page
Map.put(context, :current_page, :sign_in)
end
step "I enter {string} as my email", %{args: [email]} = context do
# Code to enter email
Map.put(context, :email, email)
end
step "I enter {string} as my password", %{args: [password]} = context do
# Code to enter password
Map.put(context, :password, password)
end
step "I click the {string} button", %{args: [button_text]} do
# Code to click button
{:ok, %{clicked: button_text}}
end
step "I should be redirected to the dashboard", context do
# Assertions for redirection
assert context.current_page == :dashboard
context
end
step "I should see {string} message", %{args: [message]} do
# Assertion for message
assert_text(message)
:ok
end
end
4. Run Your Tests
Run your tests using the standard mix test command:
# Run all tests including Cucumber
mix test
# Run only Cucumber tests
mix test --only cucumber
# Run tests for a specific feature
mix test --only feature_user_authentication
File Structure
Cucumber automatically discovers features and steps using this structure:
test/
features/ # Feature files
user_authentication.feature
shopping_cart.feature
step_definitions/ # Step definition files
authentication_steps.exs
shopping_steps.exs
common_steps.exs
Next Steps
For more detailed information about the Cucumber for Elixir framework, check out these guides:
- Feature Files - Learn how to write feature files with Gherkin syntax
- Step Definitions - Learn how to implement step definitions
- Error Handling - Understanding error reporting and debugging
- Best Practices - Best practices and examples