Using Behave
===========

Behave is a Behavior-Driven Development (BDD) testing framework that allows you to write tests in a natural language style using Gherkin syntax. This section explains how to write scenarios with Behave in the Cloud QA project.

Gherkin Syntax
-------------

Behave tests are written in feature files using Gherkin syntax, which follows this structure:

.. code-block:: gherkin

    Feature: Name of the feature
      As a [role]
      I want [feature]
      So that [benefit]

      Scenario: Specific scenario name
        Given [precondition]
        When [action]
        Then [expected result]

The main components are:

* **Feature**: Describes the feature being tested with a business value
* **Scenario**: A specific test case for the feature
* **Given**: Sets up the preconditions
* **When**: Describes the action being performed
* **Then**: Describes the expected outcome
* **And** and **But**: Used for additional conditions

Example Feature File
------------------

Here's an example from the Cloud QA project:

.. code-block:: gherkin

    # features/api/user/user_creation.feature
    Feature: User creation API
      As an admin
      I want to create new users
      So that they can access the platform

      Scenario: Create a new user with valid data
        Given I am logged in as admin
        When I create a user with the following data:
          | username | email           | role    |
          | newuser  | new@example.com | regular |
        Then the response status is "201"
        And the response contains a user with username "newuser"

Writing Scenarios
---------------

When writing scenarios, follow these best practices:

1. **Be specific**: Each scenario should test one thing
2. **Use descriptive names**: Make it clear what is being tested
3. **Focus on behavior**: Test what the feature does, not how it's implemented
4. **Keep it simple**: Avoid complex scenarios with many steps
5. **Use tables for data**: Data tables make tests more readable and maintainable

Running Behave Tests
------------------

To run all tests:

.. code-block:: bash

    behave

To run specific feature:

.. code-block:: bash

    behave features/api/user/user_creation.feature

To run tests with specific tags:

.. code-block:: bash

    behave --tags=user,create

Step Implementation
-----------------

The steps you write in your feature files are implemented in Python files in the `features/steps` directory. For example:

.. code-block:: python

    @given('I am logged in as admin')
    def step_impl(context):
        context.cloud.login_as_admin()

    @when('I create a user with the following data')
    def step_impl(context, table):
        user_data = context.table[0]
        context.response = context.cloud.create_user(user_data)

    @then('the response status is "{status}"')
    def step_impl(context, status):
        assert context.response.status_code == int(status)