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

# Allure Robot Framework reference

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

In most cases, you need to indicate to Allure Robot Framework that a certain property needs to be assigned to the test result. Most properties can be assigned in the suite file, via the Decorators API or via the Runtime API.

- **Suite file**: use the `[Tags]`, `Set Tags` or `Test Tags` keywords in the suite files (see [Tagging test cases](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#tagging-test-cases) in the Robot Framework documentation) to assign various data to tests.

  When using the `[Tags]` or `Test Tags` keyword, the data is guaranteed to be added to the test result regardless of how the test itself runs.

  When using the `Set Tags` keyword, it is recommended to put it as close to the beginning of the test as possible. This way, the data will be added even if the test fails early.

  You can use either a colon or an equal sign to separate the value from the name, e.g., `allure.label.epic:Web interface` is identical to `allure.label.epic=Web interface`.

- **Decorators API**: add a Python decorator to a method that implements a Robot Framework keyword. When using this approach, the data is guaranteed to be added regardless of how the keyword itself runs.

- **Runtime API**: use Allure's functions to add data to the test result during the execution of a keyword. 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 implementation as possible, e.g., in the first lines of the first keyword's implementation. 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

- `[Documentation]`

For the [description](/docs/v2/readability/#description), Allure Robot Framework uses the scenario's `[Documentation]` from the suite file.

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

```
*** Test Cases ***

Test Authentication
    [Documentation]    This test attempts to log into the website.
    # ...
```

### Owner

- `[Tags]  allure.label.owner:⟨VALUE⟩`
- `@allure.label('owner', value: str)`
- `allure.dynamic.label('owner', value: str)`

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

**Suite file:**
```
*** Test Cases ***

Test Authentication
    [Tags]  allure.label.owner:John Doe
    # ...
```

**Decorators API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
@allure.label('owner', 'John Doe')
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    allure.dynamic.label('owner', 'John Doe')
    ...
```

### Tag

- `[Tags]`
- `@allure.tag(*tags: str)`
- `allure.dynamic.tag(*tags: str)`

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

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

**Suite file:**
```
*** Test Cases ***

Test Authentication
    [Tags]  UI    Authentication
    # ...
```

**Decorators API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
@allure.tag('UI')
@allure.tag('Authentication')
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    allure.dynamic.tag('UI')
    allure.dynamic.tag('Authentication')
    ...
```

### Severity

- `[Tags]  allure.label.severity:⟨VALUE⟩`
- `@allure.severity(severity_level: str)`
- `allure.dynamic.severity(severity_level: str)`

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

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

**Suite file:**
```
*** Test Cases ***

Test Authentication
    [Tags]  allure.label.severity:critical
    # ...
```

**Decorators API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
@allure.severity('critical')
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    allure.dynamic.severity('critical')
    ...
```

### Label

- `[Tags]  allure.label.⟨NAME⟩:⟨VALUE⟩`
- `@allure.label(label_type: str, *labels: str)`
- `allure.dynamic.label(label_type: str, *labels: str)`

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.

**Suite file:**
```
*** Test Cases ***

Test Authentication
    [Tags]
    ...  allure.label.layer:web
    ...  allure.label.owner:eroshenkoam
    ...  allure.label.page:/{org}/{repo}/authentication
    ...  allure.label.jira:AE-2
    # ...
```

**Decorators API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
@allure.label('layer', 'web')
@allure.label('owner', 'eroshenkoam')
@allure.label('page', '/{org}/{repo}/authentication')
@allure.label('jira', 'AE-2')
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    allure.dynamic.label('layer', 'web')
    allure.dynamic.label('owner', 'eroshenkoam')
    allure.dynamic.label('page', '/{org}/{repo}/authentication')
    allure.dynamic.label('jira', 'AE-2')
    ...
```

### Allure ID (Allure TestOps)

- `[Tags]  allure.as_id:⟨VALUE⟩`
- `@allure.id(id: str)`

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

**Suite file:**
```
*** Test Cases ***

Test Authentication
    [Tags]  allure.as_id:123
    # ...
```

**Decorators API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
@allure.id('123')
def test_authentication():
    ...
```

### Link

- `[Tags]  allure.link:⟨URL⟩`
- `[Tags]  allure.link.⟨NAME⟩:⟨URL⟩`
- `[Tags]  allure.issue:⟨URL⟩`
- `[Tags]  allure.issue.⟨NAME⟩:⟨URL⟩`
- `[Tags]  allure.tms:⟨URL⟩`
- `[Tags]  allure.tms.⟨NAME⟩:⟨URL⟩`
- `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 suite file, add one of the tags listed above. Each tag indicates a different link type (`link`, `issue`, or `tms`) which affects the icon shown in the test report.

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

**Suite file:**
```
*** Test Cases ***

Test Authentication
    [Tags]
    ...  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
    # ...
```

**Runtime API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    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

- `[Tags]  allure.label.epic:⟨VALUE⟩`
- `[Tags]  allure.label.feature:⟨VALUE⟩`
- `[Tags]  allure.label.story:⟨VALUE⟩`
- `@allure.epic(*epics: str)`
- `@allure.feature(*features: str)`
- `@allure.story(*stories: str)`
- `allure.dynamic.epic(*epics: str)`
- `allure.dynamic.feature(*features: str)`
- `allure.dynamic.story(*stories: str)`

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.

**Suite file:**
```
*** Test Cases ***

Test Authentication
    [Tags]
    ...  allure.label.epic:Web interface
    ...  allure.label.feature:Essential features
    ...  allure.label.story:Authentication
    # ...
```

**Decorators API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
@allure.epic('Web interface')
@allure.feature('Essential features')
@allure.story('Authentication')
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    allure.dynamic.epic('Web interface')
    allure.dynamic.feature('Essential features')
    allure.dynamic.story('Authentication')
    ...
```

## Suite-based hierarchy

- `[Tags]  allure.label.parentSuite:⟨VALUE⟩`
- `[Tags]  allure.label.suite:⟨VALUE⟩`
- `[Tags]  allure.label.subSuite:⟨VALUE⟩`
- `@allure.parent_suite(parent_suite_name: str)`
- `@allure.suite(suite_name: str)`
- `@allure.sub_suite(sub_suite_name: str)`
- `allure.dynamic.parent_suite(parent_suite_name: str)`
- `allure.dynamic.suite(suite_name: str)`
- `allure.dynamic.sub_suite(sub_suite_name: str)`

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).

**Suite file:**
```
*** Test Cases ***

Test Authentication
    [Tags]
    ...  allure.label.parentSuite:Web interface
    ...  allure.label.suite:Essential features
    ...  allure.label.subSuite:Authentication
    # ...
```

**Decorators API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
@allure.parent_suite('Web interface')
@allure.suite('Essential features')
@allure.sub_suite('Authentication')
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    allure.dynamic.parent_suite('Web interface')
    allure.dynamic.suite('Essential features')
    allure.dynamic.sub_suite('Authentication')
    ...
```

## Package-based hierarchy

- `[Tags]  allure.label.package:⟨VALUE⟩`
- `[Tags]  allure.label.testMethod:⟨VALUE⟩`

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

**Suite file:**
```
*** Test Cases ***

Test Authentication
    [Tags]
    ...  allure.label.package:org.example
    ...  allure.label.testMethod:test_authentication()
    # ...
```

**Decorators API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
@allure.label('package', 'org.example')
@allure.label('testMethod', 'test_authentication()')
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    allure.dynamic.label('package', 'org.example')
    allure.dynamic.label('testMethod', 'test_authentication()')
    ...
```

## Test steps

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

Define a [test sub-step](/docs/steps/) within the current step.

There are two ways of defining a sub-step.

- **Decorated sub-steps**

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

  If the function accepts arguments, they will be displayed as step-level parameters in the test report. You can also include their values in the sub-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 sub-steps**

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

**Decorated steps:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    navigate_to_the_website()
    for login, password in [['johndoe', 'qwerty'],
                            ['janedoe', 'pass123']]:
        try_to_authenticate(login, password)

@allure.step('Navigate to the website')
def navigate_to_the_website():
    ...

@allure.step('Try to authenticate as {login}')
def try_to_authenticate(login, password):
    ...
```

**Context steps:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    with allure.step('Navigate to the website'):
        ...

    for login, password in [['johndoe', 'qwerty'],
                            ['janedoe', 'pass123']]:
        with allure.step(f'Try to authenticate as {login}'):
            ...
```

## Parametrized tests

When you pass arguments to a keyword in the suite file, Allure displays them as parameters for the corresponding step in the test report. No additional configuration is required.

Note that due to an implementation detail, Allure Report is only able to show the keyword parameters in the same way as they are given in the corresponding line. This means that if a keyword's argument is a variable (e.g., a value yielded by the Robot Framework's `FOR` loop), Allure Report will display the variable's name, not the actual value it has at runtime.

The example below avoid the issue by implementing a [user keyword with arguments](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#user-keyword-arguments) and then using it with literal values without loops.

```
*** Keywords ***

Try To Authenticate
    [Arguments]    ${login}    ${password}
    Log To Console    Trying to authenticate with ${login} and ${password}...
    # ...

*** Test Cases ***

Test Authentication
    Try To Authenticate    johndoe@example.com    qwerty
    Try To Authenticate    janedoe@example.com    pass123
```

## Attachments

Allure Robot Framework provides multiple ways for [adding attachments](/docs/attachments/) to the current step.

### Attaching content from variables

- `Attach ⟨CONTENT⟩`
- `Attach ⟨CONTENT⟩ name=⟨NAME⟩ attachment_type=⟨TYPE⟩`
- `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`.

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`.

  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`.

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

**Suite file:**
```
*** Settings ***
Library     AllureLibrary
Library     RequestsLibrary

*** Test Cases ***
Test Authentication
    # ...
    ${response}=  GET  https://example.com/image.png
    Attach  ${response.content}
    ...     name=Image  attachment_type=PNG
```

**Runtime API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    ...
    png_bytes = requests.get('https://example.com/image.png').content
    allure.attach(png_bytes, name='img', attachment_type=allure.attachment_type.PNG)
```

### Reading attachments from files

- `Attach File ⟨FILE⟩`
- `Attach File ⟨FILE⟩ name=⟨NAME⟩ attachment_type=⟨TYPE⟩`
- `allure.attach.file(source, name=None, attachment_type=None, extension=None)`

Same as [Attaching content from variables](#attaching-content-from-variables), but the content is loaded from an existing file.

**Suite file:**
```
*** Settings ***
Library     AllureLibrary

*** Test Cases ***
Test Authentication
    # ...
    Attach File  /path/to/image.png
    ...          name=Image  attachment_type=PNG
```

**Runtime API:**
```python
import allure
from robot.api.deco import keyword

@keyword('Test Authentication')
def test_authentication():
    ...
    allure.attach.file('/path/to/image.png', name='img', attachment_type=allure.attachment_type.PNG)
```

### Attaching log messages

By default, Allure Robot Framework automatically creates a text attachment containing the log messages that occurred during a given sub-step.

This behavior can be changed, see the [`ALLURE_MAX_STEP_MESSAGE_COUNT`](/docs/robotframework-configuration/) environment variable.