First Steps

This chapter builds a complete, runnable behave project from scratch: a feature file, its step definitions, and the command to execute them. The goal is a passing scenario that demonstrates the full cycle — Gherkin text on the left, Python code on the right, behave as the glue.

Write the Feature File

Create features/calculator.feature. Scenario steps follow the Given/When/Then pattern: Given establishes initial state, When describes the action under test, and Then states the expected outcome:

Feature: Calculator arithmetic
  Scenario: Add two numbers
    Given I have a calculator
    When I add 2 and 3
    Then the result is 5

Run behave now and it will report the steps as undefined. Behave even prints ready-to-copy skeleton code for missing steps — a fast way to bootstrap implementation:

behave
# 1 feature, 1 scenario passed? no — 3 steps undefined, with snippets shown

Implement the Steps

Create features/steps/calculator_steps.py. Each function is decorated with the Gherkin keyword it should answer. The context argument is behave's shared state object for the running scenario:

from behave import given, when, then

@given("I have a calculator")
def step_calculator(context):
    context.calculator = {"result": 0}

@when("I add 2 and 3")
def step_add(context):
    context.calculator["result"] = 2 + 3

@then("the result is 5")
def step_result(context):
    assert context.calculator["result"] == 5

Run and Read the Output

behave

# Feature: Calculator arithmetic        # features/calculator.feature:1
#   Scenario: Add two numbers
#     Given I have a calculator         # steps/calculator_steps.py:4
#     When I add 2 and 3                # steps/calculator_steps.py:8
#     Then the result is 5              # steps/calculator_steps.py:12
# 1 feature passed, 1 scenario passed, 3 steps passed

Green output means every step matched a definition and passed its assertions. The line numbers in comments help you jump from the feature text to the exact implementing function.

Make the Scenario Parameterized

Duplicating a step for every constant is not sustainable. Use step parameters immediately — this is normal behave practice, not advanced usage:

Feature: Calculator arithmetic
  Scenario: Add two numbers
    Given I have a calculator
    When I add 2 and 3
    Then the result is 5

from behave import when, then

@when("I add {x:d} and {y:d}")
def step_add(context, x, y):
    context.result = x + y

@then("the result is {expected:d}")
def step_result(context, expected):
    assert context.result == expected

The {x:d} placeholders convert captured text to integers automatically (the :d type is parsed by the parse library). The scenario text does not change, so it still reads as plain English.

Running One Scenario or Feature

behave features/calculator.feature               # one file
behave --name "Add two numbers"                  # by scenario name
behave --format=pretty                           # nicer console output

Summary

You wrote a Gherkin feature, let behave generate step skeletons, implemented three Python step functions that communicate through context, and parameterized literals with :d types. This Given/When/Then loop is the core of everyday behave work — later chapters replace literal placeholders with richer data types, tables, and outlines.