---
title: Behave reference
description: Reference documentation for Allure Behave integration | How to add sub-steps and additional metadata | Create attachments | Organise tests
---

# Allure Behave reference

These are the attributes and methods that you can use to integrate your behave tests with Allure Report.

In most cases, you need to indicate to Allure Behave that a certain property needs to be assigned to the test result. Most properties can be assigned via Gherkin tags or via the Runtime API.

- **Gherkin tags**: use [Gherkin tags](https://behave.readthedocs.io/en/latest/gherkin/#tags) to assign various data to a particular `Scenario` or a whole `Feature`.

  Most of the tags require values. You can use either a colon or an equal sign to separate the value from the name, e.g., `@allure.label.epic:WebInterface` is identical to `@allure.label.epic=WebInterface`. Note that due to a limitation in the Gherkin syntax, the value cannot contain spaces.

  When using this approach, the data is guaranteed to be added to the test result regardless of how the test itself runs.

- **Runtime API**: use Allure's functions to add data to the test result during the execution of its steps. This approach allows for constructing the data dynamically.

  Note that it is recommended to call the Allure's functions as close to the beginning of the test as possible. This way, the data will be added even if the test fails early.

## Metadata

Assign a test's [description, links and other metadata](/docs/v2/readability/#description-links-and-other-metadata).

### Description

- `allure.dynamic.description(test_description: str)`

Set the test's [description](/docs/v2/readability/#description).

Allure Behave uses a scenario's description from the Gherkin file, if present. Alternatively, use Runtime API to set the description dynamically.

Markdown formatting is allowed. Any HTML formatting, if present, will be stripped for security purposes.

**Gherkin description:**
```gherkin
Feature: Labels

  Scenario: Create new label for authorized user
  This test attempts to create a label with specified title

    When I open labels page
    And I create label with title "hello"
    Then I should see label with title "hello"
```

**Runtime API:**
```python
import allure
from behave import then

@then("I open labels page")
def step_impl(context):
    allure.dynamic.description("This test attempts to create a label with specified title")
    ...
```

### Owner

Set the test's [owner](/docs/v2/readability/#owner).

**Gherkin tags:**
```gherkin
@allure.label.owner:JohnDoe
Feature: Labels

  Scenario: Create new label for authorized user
    When I open labels page
    And I create label with title "hello"
    Then I should see label with title "hello"
```

### Tag

Set the test's [tags](/docs/v2/readability/#tags).

Any Gherkin tag is automatically added to the list of the test's tags, unless it matches one of the known patterns for other labels.

**Gherkin tags:**
```gherkin
@UI @Labels
Feature: Labels

  Scenario: Create new label for authorized user
    When I open labels page
    And I create label with title "hello"
    Then I should see label with title "hello"
```

### Severity

Set the test's [severity](/docs/v2/readability/#severity).

Allowed values are: “trivial”, “minor”, “normal”, “critical”, and “blocker”.

**Gherkin tags:**
```gherkin
Feature: Labels

  @critical
  Scenario: Create new label for authorized user
    When I open labels page
    And I create label with title "hello"
    Then I should see label with title "hello"
```

### Label

Set an arbitrary [label](/docs/v2/readability/#other-labels) for the test. This is the underlying implementation for a lot of Allure's other functions.

**Gherkin tags:**
```gherkin
@allure.label.layer:web
@allure.label.owner:eroshenkoam
@allure.label.page:/{org}/{repo}/labels
@allure.label.jira:AE-2
Feature: Labels

  Scenario: Create new label for authorized user
    When I open labels page
    And I create label with title "hello"
    Then I should see label with title "hello"
```

### Allure ID (Allure TestOps)

Set the test's [ID](/docs/v2/readability/#id).

**Gherkin tags:**
```gherkin
Feature: Labels

  @allure.label.allure_id:123
  Scenario: Create new label for authorized user
    When I open labels page
    And I create label with title "hello"
    Then I should see label with title "hello"
```

### Link

- `allure.dynamic.link(url: str, link_type: str = LinkType.LINK, name: str = None)`
- `allure.dynamic.issue(url: str, name: str = None)`
- `allure.dynamic.testcase(url: str, name: str = None)`

Add a [link](/docs/v2/readability/#links) related to the test.

- In a Gherkin file, use the `@allure.⟨TYPE⟩:⟨URL⟩` or `@allure.⟨TYPE⟩.⟨NAME⟩:⟨URL⟩` tags. If the `⟨URL⟩` does not start with “http” or “https”, it will be processed according to the [`link_pattern`](/docs/behave-configuration/#link-pattern) and [`issue_pattern`](/docs/behave-configuration/#issue-pattern) configuration options. The resulting URL will then be used as both the link target and the link name, unless a custom `⟨NAME⟩` is provided.

- In the Runtime API, use the `allure.dynamic.link()` function with an optional `link_type` argument or its shorthand versions for the `issue` and `tms` link types.

**Gherkin tags:**
```gherkin
@allure.link.MyWebsite:https://dev.example.com/
@allure.issue.UI-123:https://issues.example.com/UI-123
@allure.tms.TMS-456:https://tms.example.com/TMS-456
Feature: Labels

  Scenario: Create new label for authorized user
    When I open labels page
    And I create label with title "hello"
    Then I should see label with title "hello"
```

**Runtime API:**
```python
import allure
from behave import then

@then("I open labels page")
def step_impl(context):
    allure.dynamic.link("https://dev.example.com/", name="Website")
    allure.dynamic.issue("https://issues.example.com/UI-123", name="UI-123")
    allure.dynamic.testcase("https://tms.example.com/TMS-456", name="TMS-456")
    ...
```

## Behavior-based hierarchy

Assign names of **epics**, **features** or **user stories** for a test, as part of Allure's [behavior-based hierarchy](/docs/v2/navigation/#behavior-based-hierarchy).

Each function support setting one or more values at once.

**Gherkin tags:**
```gherkin
@allure.label.epic:WebInterface
Feature: Labels

  @allure.label.story:CreateLabels
  Scenario: Create new label for authorized user
    When I open labels page
    And I create label with title "hello"
    Then I should see label with title "hello"
```

## Suite-based hierarchy

Assign the names of **parent suite**, **suite** or **sub-suite** for a test, as part of Allure's [suite-based hierarchy](/docs/v2/navigation/#suite-based-hierarchy).

**Gherkin tags:**
```gherkin
@allure.label.parentSuite:WebInterface
@allure.label.suite:EssentialFeatures
@allure.label.subSuite:Labels
Feature: Labels

  Scenario: Create new label for authorized user
    When I open labels page
    And I create label with title "hello"
    Then I should see label with title "hello"
```

## Package-based hierarchy

Assign the names of package, test class and test method, as part of Allure's [package-based hierarchy](/docs/v2/navigation/#package-based-hierarchy).

**Gherkin tags:**
```gherkin
@allure.label.package:org.example
@allure.label.testClass:TestMyWebsite
@allure.label.testMethod:TestLabels()
Feature: Labels

  Scenario: Create new label for authorized user
    When I open labels page
    And I create label with title "hello"
    Then I should see label with title "hello"
```

## Test steps

- `@allure.step(title: str)`
- `with allure.step(title: str)`

Define a [test step](/docs/steps/) with the given `title`.

There are two ways of defining a step.

- **Decorated steps**

  Define a function or a method containing a test step and decorate it with `@allure.step()`.

  If it accepts arguments, you can include their values in the step title via **replacement fields**. A replacement field is a parameter name delimited by braces `{}`, as supported by the standard [`str.format()`](https://docs.python.org/3/library/stdtypes.html#str.format) method.

- **Context steps**

  Write a test step in-place but use the `with allure.step()` statement to create its context.

**Decorated steps:**
```python
import allure
from behave import then

@then("I open labels page")
def step_impl(context):
    step1()
    for val in ["val1", "val2", "val3"]:
        step2(val)

@allure.step("Step 1")
def step1():
    ...

@allure.step("Step 2 (with value {val})")
def step2(val):
    ...
```

**Context steps:**
```python
import allure
from behave import then

@then("I open labels page")
def step_impl(context):
    with allure.step("Step 1"):
        ...

    for val in ["val1", "val2", "val3"]:
        with allure.step(f"Step 2 (with value {val})"):
            ...
```

## Parametrized tests

In Gherkin, a [`Scenario Outline`](https://behave.readthedocs.io/en/stable/tutorial/#scenario-outlines) (or a `Scenario Template`) implements the [parametrized tests](/docs/v2/readability/#parametrized-tests) pattern. A scenario outline must contain an `Examples` table, from which behave loads sets of parameters, one row after another. Each set of parameters is being placed into the step declarations according to the placeholders, thus generating a new scenario based on the row. Behave then runs each of them independently, as if it was a separate `Scenario`. The data can then be captured by behave and passed as separate arguments to the Python code.

Allure Behave automatically recognizes this pattern. No additional configuration is required.

The example below shows a Gherkin file and a Python implementation file of a test. In this example, the four parameters for the “I enter my details...” step will be displayed in both instances of the scenario in the test report.

```gherkin
Feature: User management

  Scenario Outline: Registration
    When I go to the registration form
    And I enter my details: <login>, <password>, <name>, <birthday>
    Then the profile should be created

    Examples:
      | login   | password | name     | birthday   |
      | johndoe | qwerty   | John Doe | 1970-01-01 |
      | janedoe | 123456   | Jane Doe | 1111-11-11 |
```

```python
from behave import then, when

@when('I go to the registration form')
def step_impl(context):
    ...

@when('I enter my details: {login}, {password}, {name}, {birthday}')
def step_impl(context, login, password, name, birthday):
    ...

@then('the profile should be created')
def step_impl(context):
    ...
```

## Attachments

Functions for [adding attachments](/docs/attachments/) to test results.

### Attaching content from variables

- `allure.attach(body, name=None, attachment_type="text/plain", extension="attach")`

Add `body` as an attachment to the test result under the given `name` (defaults to a unique pseudo-random string). The `body` must be of type `bytes` or `str`.

Info:
You can use data produced by any function, not necessarily read from an actual file. For attaching contents of existing files, use [`attach.file()`](#reading-attachments-from-files) instead.

To ensure that the reader's web browser will display attachments correctly, it is recommended to specify each attachment's type. There are two ways to do this:

- Pass the media type of the content as `attachment_type` and, optionally, a filename extension as `extension`. For example:

  ```python
  allure.attach('{"value":100}', attachment_type="application/json", extension="json")
  ```

  Some popular media types are `image/png` and `image/jpeg` for screenshots and other images, `application/json` for JSON data, and `text/plain` for text files. The media type affects how the data will be displayed in the test report, while the filename extension is appended to the filename when user wants to save the file.

- Pass a value from the `allure.attachment_type` class as `attachment_type`. For example:

  ```python
  allure.attach('{"value":100}', attachment_type=allure.attachment_type.JSON)
  ```

  This will automatically set the media type and the appropriate filename extension.

```python
import allure
from behave import then

@then("I open labels page")
def step_impl(context):
    ...
    with open('/path/to/image.png', 'rb') as png_file:
        png_bytes = png_file.read()
    allure.attach(png_bytes, name="img", attachment_type=allure.attachment_type.PNG)
```

### Reading attachments from files

- `allure.attach.file(source, name=None, attachment_type=None, extension=None)`

Same as [`attach()`](#attach), but the content is loaded from the existing `source` file.

```python
import allure
from behave import then

@then("I open labels page")
def step_impl(context):
    ...
    allure.attach.file(
        '/path/img.png',
        name="img",
        attachment_type=allure.attachment_type.PNG
    )
```