Cucumber Gherkin

Primary keywords

Feature: Short description
  Optional multi-line description explaining the feature.

  Background:
    Given common setup steps for all scenarios

  Rule: Business rule grouping

    Scenario: Concrete example illustrating the rule
      Given an initial context
      When an action occurs
      Then expected outcome
      And additional step
      But negative assertion

    Scenario Outline: Parameterized scenario
      Given there are <start> items
      When I remove <remove> items
      Then I should have <remaining> items

      Examples:
        | start | remove | remaining |
        | 12    | 5      | 7         |
        | 20    | 5      | 15        |

Step keywords

• Given — setup / precondition
• When — action / trigger
• Then — expected outcome / assertion
• And — continue previous step type
• But — negative continuation
• * — bullet-style step

Examples:

Given I am logged in as "admin"
When I submit the form
Then I should see "Success"
And I should see my dashboard
But I should not see "Error"
* I have eggs

Data structures

Data tables

Given the following users exist:
  | name  | email             | role  |
  | Alice | [email protected] | admin |
  | Bob   | [email protected]   | user  |

Doc strings

Given a blog post with content:
  """markdown
  # My Post Title

  This is the content of my blog post.
  """

Tags

Use tags to slice runs and attach special setup.

@smoke @critical
Feature: User authentication

  @wip
  Scenario: Login with valid credentials
    Given a valid user exists
    When the user logs in
    Then the dashboard is shown

  @slow @database
  Scenario: Bulk user import
    Given a CSV file exists
    When the import runs
    Then all valid users are created

Common tag expressions:

• @smoke and not @slow
• @gui or @api
• (@smoke or @critical) and not @wip

Python step definitions

pytest-bdd examples

from pytest_bdd import scenarios, given, when, then, parsers

scenarios("features/login.feature")

@given("a valid user exists")
def valid_user(db):
    db.create_user(username="bob", password="secret")

@when(parsers.parse('the user logs in as "{username}" with password "{password}"'))
def log_in(client, username, password):
    client.login(username=username, password=password)

@then("the dashboard is shown")
def dashboard_is_shown(client):
    assert client.page_title() == "Dashboard"

pytest-bdd registration gotchas

Bad. Bad. Bad.

If pytest-bdd cannot see the step module, your feature will fail with StepDefinitionNotFoundError even though the decorator exists.

Use one of these patterns:

• import the step module from the test module that calls scenarios(...)
• or import step modules in tests/conftest.py

Example:

# tests/test_bdd_features.py
from tests.bdd.steps import host_steps  # noqa: F401
from pytest_bdd import scenarios

scenarios("bdd/robot_host.feature")

If a Given step needs to feed later steps as a fixture, use target_fixture:

@given("the host is running", target_fixture="active_host")
def given_host_is_running(running_host):
    return running_host

Without target_fixture, later steps may not be able to request that value by fixture name.

behave style

from behave import given, when, then

@given("a valid user exists")
def step_valid_user(context):
    context.user = create_user("bob", "secret")

@when("the user logs in")
def step_login(context):
    context.response = context.client.login("bob", "secret")

@then("the dashboard is shown")
def step_dashboard(context):
    assert "Dashboard" in context.response.text

Hooks

Prefer short hooks. Tag-scoped hooks beat giant global magic.

behave hooks

# features/environment.py

def before_scenario(context, scenario):
    context.client = make_test_client()


def after_scenario(context, scenario):
    context.client.close()

pytest-bdd hook pattern

Use pytest fixtures for setup/teardown instead of trying to stuff everything into hooks.

import pytest

@pytest.fixture
def client():
    client = make_test_client()
    yield client
    client.close()

Best practices

Declarative over imperative

Good:

When "Bob" logs in
Then he sees his dashboard

Avoid:

When I visit "/login"
And I enter "bob" in "username"
And I enter "secret" in "password"
And I click "Login"
Then I should see "Dashboard"

Behavior over implementation

• describe what the system does, not how it is coded
• use domain language stakeholders understand
• keep scenarios short, usually 3 to 5 steps
• one behavior per scenario

Background discipline

• keep Background short, 4 lines max
• use it only for essential shared context
• move implementation detail into step definitions

Scenario outline discipline

Use Scenario Outline only when the same behavior truly repeats with different examples. If examples tell different stories, split them.

Test daemon and socket code without thread hell

For hosts, daemons, and ZMQ services, do not force every BDD scenario through real background threads if the behavior can be tested directly.

A better pattern:

• keep the long-running loop thin
• extract small methods like apply_action() and publish_observation()
• let BDD steps call those methods directly in dry-run mode
• reserve full thread/socket tests for a small smoke layer only

This avoids flaky shutdown bugs, port collisions, and hanging tests while still testing the real behavior.

Anti-patterns

Bad. Bad. Bad.

• UI click-by-click noise in every scenario
• scenarios that test multiple behaviors at once
• giant backgrounds full of junk setup
• step definitions coupled to CSS selectors or internal method names
• vague steps like When I do the thing
• asserting too much in one Then

Running tests

pytest-bdd

pytest -q
pytest tests/test_login.py -q
pytest -k smoke -q

behave

behave
behave features/login.feature
behave --tags=@smoke

Rocky take

Write feature files for humans first. Write step definitions for machines second. If the feature reads like Selenium fan fiction, you screwed it up.