Advanced Guide to Behavior-Driven Development with Behave in Python

Behavior-driven development (BDD) bridges the gap between software development and business expectations, ensuring that the final product meets user needs. In software development, the clarity of communication between stakeholders and developers is paramount. This is where BDD shines, offering a platform for dialogue that focuses on the desired behavior of software. Among the tools that facilitate BDD, Python’s Behave library stands out for its simplicity, effectiveness, and thanks to its use of human-readable Gherkin language for writing tests. In this article, we’ll dive into Behave, guiding you through setting it up, writing tests, and adding a twist by defining a new variable type.

Understanding Behave and BDD

Behavior-driven development is an extension of Test-driven development (TDD) that emphasizes collaboration among project stakeholders. Behave operates on the principle of scenarios, which are written in a natural language that non-programmers can understand. These scenarios describe how a feature should work from the end user’s perspective.

Behave is a BDD framework for Python that follows the principles of writing tests in a human-readable format. It uses Gherkin language to describe software behaviors without detailing how that functionality is implemented.

Key Features of Behave

• Gherkin Language: Enables the definition of application behavior in natural language, which stakeholders can easily understand.
• Scenario Outline: Facilitates data-driven tests, allowing the same scenario to be run multiple times with different data sets.
• Hooks: Offers setup and teardown operations for scenarios or features, improving test management.

In the context of the Gherkin language, terms like Feature, Scenario, Scenario Outline, and some other reserved words, have specific meanings and uses. Understanding these terms is crucial for effectively utilizing BDD frameworks like Behave. Here’s a breakdown of each term:

Feature

A Feature represents a distinct aspect or functionality of the software system under test. It’s a high-level description of a software feature, and it serves as a container for a set of related scenarios. A Feature is described in a .feature file and typically includes:

• A title that summarizes the feature being tested.
• An optional narrative that provides context, stating the role, feature, and benefit. It follows the template: “As a [role], I want [feature] so that [benefit].”
• One or more Scenarios or Scenario Outlines that detail specific examples or use cases of how the feature works.

Example:

Feature: User login
  As an application user
  I want to log into the application
  So that I can access my personal account information

Scenario

A Scenario is a concrete example that illustrates a specific situation or use case of the feature. It is defined by a series of steps that describe an initial context, an event, or action, and an expected outcome. Scenarios are used to verify that the software behaves as intended in particular situations. A Scenario includes:

• A title that briefly describes the situation being tested.
• Step definitions using keywords: Given (describes the initial context), When (describes the action), and Then (describes the expected outcome).

Example:

Scenario: Successful login
  Given I am on the login page
  When I enter valid credentials
  Then I should be redirected to my dashboard

Scenario Outline

A Scenario Outline is used for parameterized tests, allowing you to run the same Scenario multiple times with different data sets. It is especially useful for covering a variety of input conditions or test cases with a single template. A Scenario Outline includes:

• A title that summarizes the test case being parameterized.
• Step definitions that use placeholders.
• An Examples section that contains a table of values to substitute into the placeholders for each iteration.

Example:

Scenario Outline: Login with different user roles
  Given I am on the login page
  When I log in as a "<role>" with valid credentials
  Then I should see the "<dashboard>" specific to my role

Examples:
  | role      | dashboard    |
  | admin     | admin panel  |
  | user      | user home    |
  | guest     | guest access |

In this example, the Scenario Outline will be executed three times, once for each row in the Examples table, substituting the <role> and <dashboard> placeholders with the corresponding values.

Given, When, Then, And, But

• Given: Describes the initial context of the system before the user starts interacting with it. It sets up the scene.
• When: Specifies an action or event that occurs. It describes the key action the user performs.
• Then: Outlines the expected outcome or result, given the context and the event that occurred. It is used to describe an assertion.
• And, But: These are used to add additional information to the previous Given, When, or Then steps without having to repeat the Given, When, or Then keyword. They help make the scenarios more readable and organized.

Tags

Tags are not steps but are important in Gherkin. They are prefixed with an @ symbol and can be applied to Features or Scenarios. Tags allow for filtering specific scenarios to run or to apply certain behaviors through hooks based on the tagged feature or scenario.

Use Cases for Tags in Behave:

• Environment-Based Testing: Suppose you have tests that should only run in specific environments, such as development, staging, or production. Tags allow you to mark these tests and run them selectively.

@development
Feature: New Feature Development
  Scenario: Test new feature in development
    Given I am on the development environment
    When I test the new feature
    Then the feature behaves as expected

@staging
Feature: Staging Feature Testing
  Scenario: Test feature in staging
    Given I am on the staging environment
    When I test the feature
    Then the feature behaves as expected

With the above setup, you can run only the tests tagged with @development or @staging using Behave's command-line options, like so:

behave --tags=@development

• Testing Different Aspects: Tags can differentiate between types of tests, such as @ui, @api, etc. This is useful for running only a subset of tests that are relevant at a certain time.

@api
Scenario: Get info test of a user send get info request

@ui
Scenario: Button click test when clicking the login button

To run only API tests:

behave --tags=@api

• Excluding Tests: Tags can also be used to exclude certain tests from being run, which is particularly useful when you have known issues or long-running tests that you temporarily want to skip.

@skip
Scenario: Test feature that is not ready

To exclude tests tagged with @skip:

behave --tags=~@skip

Data Tables

Data Tables in Behave offer a powerful way to extend the capabilities of your steps by allowing you to include structured, multi-dimensional data directly within your feature files. This feature is particularly useful for scenarios that require a more detailed set of data than what can be succinctly expressed in a single line of step text. Here’s a deeper dive into how Data Tables can enhance your BDD scenarios, including more examples to illustrate their utility.

Purpose of Data Tables:

• Parameterization: They allow you to run the same step with multiple sets of data, making your tests more comprehensive and efficient.
• Clarity: Complex data structures are presented in a readable format, making scenarios easier to understand and maintain.
• Flexibility: They can be used to input data into a system, verify output data, or both, supporting a wide range of testing needs.

Defining Data Tables

Data Tables are defined using the pipe symbol (|) to delineate columns and are placed directly below a step. Each row after the header row represents a set of data corresponding to the columns defined in the header.

Given I have the following products:
  | Name       | Category    | Price |
  | Smartphone | Electronics |   599 |
  | Car toy    | Toys        |   199 |
  | Book       | Books       |   3   |

Accessing Data Tables in Steps

When a step is executed, the Data Table is passed to the step function as an argument. Behave allows you to access this data as either a list of dictionaries (each row becomes a dictionary where the keys are the column headers) or as raw data. Here’s how you might access and use a Data Table in your step definitions (later you will learn more about the step implementation):

from behave import given

@given('I have the following products:')
def step_impl(context):
    for row in context.table:
        # Each row is a dictionary where column names are keys
        product_name = row['Name']
        category = row['Category']
        price = row['Price']
        print(f"Product: {product_name}, Category: {category}, Price: ${price}")

Setting Up Your Behave Project

A well-organized directory structure is crucial for maintaining a Behave project. Here’s how to set up your project:

1. Install Behave: If you haven’t already, install Behave using pip:

python3 -m pip install behave

2. Directory Structure: Organize your project with the following structure:

your_project/
|
|-- features/
|   |__ steps/
|   |   |__ step_definitions.py
│   |__ environment.py
│   |__ your_feature.feature
|
|_ models/
|   |__ custom_models.py
|
|__ requirements.txt

• features/: This directory holds your .feature files, where you define your scenarios in the Gherkin language.
• steps/: Contains Python files with step definitions for the scenarios described in your feature files.
• environment.py: (Optional) Defines setup and teardown functions, among other hooks.
• models/: (Optional) A directory for custom models or types you might use in your steps.
• requirements.txt: Lists the project's dependencies.

Writing Scenarios in Gherkin

Gherkin is a key component of Behave, allowing you to write human-readable descriptions of software behaviors. Here’s a breakdown of a Gherkin file:

Feature: Shopping Cart
  As an online shopper
  I want to manage my shopping cart
  So that I can order my desired products

  Scenario Outline: Add a product to the shopping cart
    Given I am on the product page
    When I add "<product>" to the cart
    Then I should see "<product>" in the cart

    Examples:
      | product    |
      | Book       |
      | Smartphone |

This example showcases the use of a Scenario Outline with Examples, allowing the scenario to run multiple times with different inputs.

Implementing Step Definitions

After defining your scenarios, you need to implement the corresponding step definitions in Python. Implement the corresponding steps in features/steps/shopping_cart_steps.py. The naming of these files is flexible, provided they adhere to the Python file extension (.py). There’s no need to manually specify which step files Behave should utilize; it automatically detects and executes all Python scripts present in the “steps” directory.

In Behave, the naming of the function that implements a step (commonly seen as step_impl(context)) is not strictly required to follow the step_impl convention. You can name your step implementation functions anything you like, as long as they are decorated with the appropriate Behave decorator (@given, @when, @then, or @step) and accept at least one argument, usually named context, which is a reference to Behave's context object.

For the above scenario, your step definitions might look like this:

from behave import given, when, then


@given('I am on the product page')
def step_impl(context):
    context.browser.visit_product_page()


@when('I add "{product}" to the cart')
def step_impl(context, product):
    context.browser.add_product_to_cart(product)


@then('I should see "{product}" in the cart')
def step_impl(context, product):
    assert product in context.browser.get_cart_contents()

Defining Custom Types

Behave allows you to extend its functionality by defining new types for use in your step implementations. This feature is particularly useful for matching complex patterns or specific data structures. Here’s an example:

1. Define a New Type in features/steps/type_definitions.py:

from behave import register_type
import parse


class Product(object):
    def __init__(self, i_product_name):
        self.__m_product_name = i_product_name

    @property
    def name(self) -> str:
        return self.__m_product_name


@parse.with_pattern(r"[^\"].+")
def parse_product(text):
    return Product(text)


register_type(Product=parse_product)

2. Use the Custom Type in Your Feature File:

Feature: Custom Product
  Scenario: Adding a product with custom type
    Given I add a product "Laptop" to the cart
    Then the product should be recognized as a Product

3. Implement Step Definitions Using the Custom Type:

from behave import given, then

# Import the Product class from where it's defined, if it's in a different file
from steps.type_definitions import Product

# Assuming you have a context attribute for the cart, which is a list
@given('I add a product "{product_name:Product}" to the cart')
def step_impl(context, product_name):
    context.cart.add_product_to_cart(product_name)


@then('the product should be recognized as a Product')
def step_impl(context):
    # Check the last added product in the cart
    last_added_product = context.cart.cart[-1]
    assert isinstance(last_added_product, Product), "The object is not an instance of Product"

Hooks

Hooks in Behave are special functions that allow you to run code before and after certain events during your tests. These events include the start and end of the entire test run, each feature, and each scenario. Hooks are used for setup and teardown operations, such as preparing test data, clearing caches, or managing resources like database connections and browser sessions. They play a crucial role in test management by ensuring that each test runs in a clean and controlled environment, which helps to maintain test reliability and repeatability.

Types of Hooks in Behave

• before_all: Runs once before all tests.
• after_all: Runs once after all tests.
• before_feature: Runs before each feature file is tested.
• after_feature: Runs after each feature file has been tested.
• before_scenario: Runs before each scenario.
• after_scenario: Runs after each scenario.
• before_step: Runs before each step.
• after_step: Runs after each step.

Implementing Hooks

Hooks are defined in the environment.py file, which should be located in your features directory. Here are examples of how to use some of these hooks:

environment.py

"""Before proceeding, ensure you've imported all necessary modules and 
components. In this context, we're operating under the assumption that 
both database (db) and web browser automation tools (browser) have been 
correctly imported."""


def before_all(context):
    # Setup operation that runs before all tests
    context.browser = browser.start_browser()

def after_all(context):
    # Teardown operation that runs after all tests
    context.browser.quit()

def before_feature(context, feature):
    # Setup operation specific to each feature
    if 'database' in feature.tags:
        db.create_test_database()

def after_feature(context, feature):
    # Teardown operation specific to each feature
    if 'database' in feature.tags:
        db.drop_test_database()

def before_scenario(context, scenario):
    # Setup for each scenario; e.g., logging in a user
    if 'login' in scenario.tags:
        context.user = context.browser.login_user('test_user', 'password')

def after_scenario(context, scenario):
    # Teardown for each scenario; e.g., logging out a user
    if 'logout' in scenario.tags:
        context.browser.logout_user()

In this example, before_all and after_all are used to start and stop a web browser for tests that require UI interaction. before_feature and after_feature manage database setup and teardown for features tagged with database. before_scenario and after_scenario handle user login and logout for scenarios tagged with login and logout, respectively.

By leveraging hooks, you can ensure that your tests are isolated from each other, reducing the chance of interference and making your test suite more reliable and easier to maintain.

Initializing Attributes in the Context

Attributes within the context object can be initialized in various places, but two common approaches are widely used:

1. Initialization in Environment Hooks: Environment hooks such as before_all, before_feature, before_scenario, etc., provide a structured way to initialize attributes before the execution of your tests. For example, you might establish a database connection in before_all and store it in context.db so that it's available to all scenarios:

def before_all(context):
    context.db = MyDatabaseConnection()py

Similarly, a browser instance for web testing can be initiated in a before_scenario hook and added to the context, ensuring that each scenario starts with a fresh browser state:

def before_scenario(context, scenario):
    context.browser = webdriver.Chrome()  # Or any other browser

2. Lazy Initialization Within Steps: Sometimes, you might prefer to initialize certain data only when it’s needed within a specific step. This approach, known as lazy initialization, helps conserve resources and keeps your tests running quickly. To implement lazy initialization, you check for the existence of an attribute and initialize it if it’s not already present:

@given('I am logged into the web application')
def step_impl(context):
    # Initializes the browser if not already done
    if not hasattr(context, 'browser'):
        context.browser = webdriver.Chrome() 
    # Proceed to log into the application

Conclusion

Behave stands out as a powerful tool for implementing Behavior-Driven Development (BDD) in Python projects, offering a framework that bridges the gap between technical specifications and business requirements. By allowing the definition of software behaviors in plain, human-readable language, Behave enables developers, testers, and business stakeholders to collaborate more effectively, ensuring that developed features meet user needs and expectations.

The use of the Gherkin language for writing scenarios, along with the support for step parameters, custom types, data tables, and tags, provides a flexible and expressive way to describe software behavior. This expressiveness, combined with Behave’s capability to share context between steps, facilitates writing clear, maintainable, and reusable test code. Moreover, Behave’s integration with Python allows for leveraging the full ecosystem of Python libraries and tools, making it a robust choice for testing a wide range of applications.

While Behave promotes best practices in software development through BDD, it also encourages a test-first approach that can lead to higher quality code, fewer bugs, and better alignment with business objectives. The framework’s structure and conventions help maintain a clear separation between feature specifications and their technical implementations, fostering a collaborative environment where all project members can contribute to and understand the project’s progress.

Here is the repository that I have created for this article:

GitHub - moraneus/Guide-to-Python-Behave: This repository hosts a concise yet illustrative…

Your Support Means a Lot! 🙌

If you enjoyed this article and found it valuable, please consider giving it a clap to show your support. Feel free to explore my other articles, where I cover a wide range of topics related to Python programming and others. By following me, you’ll stay updated on my latest content and insights. I look forward to sharing more knowledge and connecting with you through future articles. Until then, keep coding, keep learning, and most importantly, enjoy the journey!

Happy programming!

References

Welcome to behave! - behave 1.2.7.dev5 documentation