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

# Allure Pytest reference

These are the functions that you can use to integrate your pytest tests with Allure.

Allure Pytest provides more than one way to use some features. In most cases, one way involves using a decorator on the test function, while the other involves a method call inside the test function body. The latter style is called “dynamic” and allows to construct values dynamically.

## Metadata

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

Some metadata fields can be used for selecting which test to run, see [Specify description, links and other metadata](/docs/pytest/#specify-description-links-and-other-metadata) and [Options affecting test selection](/docs/pytest-configuration/#options-affecting-test-selection).

### Title

- `@allure.title(test_title: str)`
- `allure.dynamic.title(test_title: str)`

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

The decorator variant of the function can also be used for [describing pytest fixtures](/docs/pytest/#describe-fixtures).

**Decorators API:**
```python
import allure
import pytest

@allure.title("Test Authentication")
def test_authentication():
    ...
```

**Decorators API on a fixture:**
```python
import allure
import pytest

@pytest.fixture()
@allure.title("Prepare for the test")
def my_fixture():
    ...

def test_with_my_fixture(my_fixture):
    ...
```

**Runtime API:**
```python
import allure
import pytest

def test_authentication():
    allure.dynamic.title("Test Authentication")
    ...
```

If the test function has parameters (see [Parametrized tests](#parametrized-tests) below), you can include the parameters' values in the 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. In addition to the parameters themselves, a special field `{param_id}` is supported for inserting the parameter set ID (see the [pytest documentation](https://docs.pytest.org/en/latest/example/parametrize.html#different-options-for-test-ids)).

Note that the replacement fields are only supported in the decorator variant of the `title()` function.

**Using the parameter name:**
```python
import allure
import pytest

@pytest.mark.parametrize("login", ["johndoe", "johndoe@example.com"])
@allure.title("Test Authentication (as {login})")
def test_authentication(login):
    ...
```

**Using the parameter set ID:**
```python
import allure
import pytest

@pytest.mark.parametrize("login", ["johndoe", "johndoe@example.com"],
                         ids=["using-username", "using-email"])
@allure.title("Test Authentication ({param_id})")
def test_authentication(login):
    ...
```

### Description

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

Set the test's [description](/docs/v2/readability/#description). If not provided, Allure will use the docstring of the test function.

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

**Decorators API:**
```python
import allure

@allure.description("""
    This test attempts to log into the website using a login and a password. Fails if any error happens.

    Note that this test does not test 2-Factor Authentication.
""")
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure

def test_authentication():
    allure.dynamic.description("""
        This test attempts to log into the website using a login and a password. Fails if any error happens.

        Note that this test does not test 2-Factor Authentication.
    """)
    ...
```

**Docstring:**
```python
def test_authentication():
    """
    This test attempts to log into the website using a login and a password. Fails if any error happens.

    Note that this test does not test 2-Factor Authentication.
    """
    ...
```

### Tag

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

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

Both variants of the function can accept as many tags at a time as needed, for example:

**Decorators API:**
```python
import allure

@allure.tag("NewUI", "Essentials", "Authentication")
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure

def test_authentication():
    allure.dynamic.tag("NewUI", "Essentials", "Authentication")
    ...
```

### Severity

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

**Decorators API:**
```python
import allure
from allure_commons.types import Severity

@allure.severity(Severity.CRITICAL)
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure
from allure_commons.types import Severity

def test_authentication():
    allure.dynamic.severity(Severity.CRITICAL)
    ...
```

### Label

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

The first argument of the function is the label name. It can be a constant from the `LabelType` class or any other string.

The second and all remaining arguments are values to be added. For each of the values, the function will add a label with the given name and given value. An example of function that passes to `label()` multiple values at once is [`tag()`](#tag).

**Decorators API:**
```python
import allure
from allure_commons.types import LabelType

@allure.label(LabelType.LANGUAGE, "python")
@allure.label(LabelType.FRAMEWORK, "pytest")
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure
from allure_commons.types import LabelType

def test_authentication():
    allure.dynamic.label(LabelType.LANGUAGE, "python")
    allure.dynamic.label(LabelType.FRAMEWORK, "pytest")
    ...
```

### Allure ID (Allure TestOps)

- `@allure.id(id: str)`
- `allure.dynamic.id(id: str)`

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

**Decorators API:**
```python
import allure

@allure.id("123")
def test_authentication():
    ...
```

### Manual (Allure TestOps)

- `@allure.manual`
- `allure.dynamic.manual()`

Instructs Allure TestOps to create or update a manual test case from the test result.

**Decorators API:**
```python
import allure

@allure.manual
def test_authentication():
    ...
```

### Link

- `@allure.link(url: str, link_type: str = LinkType.LINK, name: str = None)`
- `@allure.issue(url: str, name: str = None)`
- `@allure.testcase(url: str, name: str = None)`
- `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.

Based on the `link_type` (which can be any string), Allure will try to load a corresponding **link pattern** to process the `url`, as defined by the [`--allure-link-pattern`](/docs/pytest-configuration/#allure-link-pattern-⟨type⟩-⟨pattern⟩) configuration option. If no pattern found for the given type, the URL is left unmodified.

The `name` will be used as the link's text. If it is omitted, the unprocessed URL will be used instead.

For convenience, Allure provides shorthand functions and methods with pre-selected link types `issue` and `tms`.

**Decorators API:**
```python
import allure

@allure.link("https://dev.example.com/", name="Website")
@allure.issue("AUTH-123")
@allure.testcase("TMS-456")
def test_authentication():
    ...
```

**Decorators API (custom decorator):**
```python
import allure

def pr(pr_id):
    return allure.link(pr_id, name="PR {}".format(pr_id), link_type="pr")

@pr(123)
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure

def test_authentication():
    allure.dynamic.link("https://dev.example.com/", name="Website")
    allure.dynamic.issue("AUTH-123")
    allure.dynamic.testcase("TMS-456")
    ...
```

## Behavior-based hierarchy

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

**Decorators API:**
```python
import allure

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

**Runtime API:**
```python
import allure

def test_authentication():
    allure.dynamic.epic("Web interface")
    allure.dynamic.feature("Essential features")
    allure.dynamic.story("Authentication")
    ...
```

## Suite-based hierarchy

- `@allure.parent_suite(parent_suite_name)`
- `@allure.suite(suite_name)`
- `@allure.sub_suite(sub_suite_name)`
- `allure.dynamic.parent_suite(parent_suite_name)`
- `allure.dynamic.suite(suite_name)`
- `allure.dynamic.sub_suite(sub_suite_name)`

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

By default, Allure Pytest sets the parent suite and the suite based on the module containing the test. For example, a test in a module named `tests.web.essentials.auth` will get assigned the `tests.web.essentials` parent suite and the `auth` suite.

**Decorators API:**
```python
import allure

@allure.parent_suite("Tests for web interface")
@allure.suite("Tests for essential features")
@allure.sub_suite("Tests for authentication")
def test_authentication():
    ...
```

**Runtime API:**
```python
import allure

def test_authentication():
    allure.dynamic.parent_suite("Tests for web interface")
    allure.dynamic.suite("Tests for essential features")
    allure.dynamic.sub_suite("Tests for authentication")
    ...
```

## 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

def test_example():
    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

def test_example():
    with allure.step("Step 1"):
        ...

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

## Parametrized tests

- `allure.dynamic.parameter(name, value, excluded=None, mode=None)`

Specify a `name` and `value` of a [parameter](/docs/v2/readability/#parametrized-tests) that was used during this test.

This can be used for adding the parameters even to those function that do not use the [pytest's parameterization features](https://docs.pytest.org/en/latest/how-to/parametrize.html). In the second example below, there are no test parameters as far as pytest is concerned, however, the test report will display the “login” parameter.

You can also override display values for the existing parameters. In the third example below, the test report will use the short value for the parameter instead of the full path. Note that changing the display value does not affect the [unique identifier](/docs/history-and-retries/#making-sure-tests-are-identified-correctly) for the tests history.

The parameters can be used in the test's title, see [Title](#title).

If the `excluded` argument is set to True, Allure will not use the parameter when comparing the current test result with previous one in the history. This argument is only used by Allure TestOps.

The `mode` argument affects how the parameter will be displayed in the report. Available options are defined in the `allure.parameter_mode` enumeration:

- `allure.parameter_mode.DEFAULT` (same as not specifying any mode) — the parameter and its value will be shown in a table along with other parameters.
- `allure.parameter_mode.MASKED` — the parameter will be shown in the table, but its value will be hidden. Use this mode for passwords, tokens and other sensitive parameters.
- `allure.parameter_mode.HIDDEN` — the parameter and its value will not be shown in the test report. Note, however, that it is still possible to extract the value from the `allure_results` directory if you publish it.

```python
from os.path import basename, expanduser

import allure
import pytest

@pytest.mark.parametrize("login", [
    "johndoe",
    "johndoe@example.com",
])
def test_authentication(login):
    ...

def test_authentication_with_empty_login():
    allure.dynamic.parameter("login", "(empty)")
    ...

@pytest.mark.parametrize("ssh_key", [
    expanduser("~/.ssh/id_rsa1"),
    expanduser("~/.ssh/id_rsa2"),
    expanduser("~/.ssh/id_rsa3"),
])
def test_authentication_with_ssh_key(ssh_key):
    allure.dynamic.parameter("ssh_key", basename(ssh_key))
    ...
```

Tip:

For more information, you can consult the guide on [Pytest parameterization](/docs/guides/pytest-parameterization/).

## Attachments

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

Tip:

Check out our guides for screenshots and videos in Pytest using Selenium or Playwright plugin:

- [Pytest & Selenium: screenshots](/docs/guides/pytest-selenium-screenshots/)
- [Pytest & Playwright: screenshots](/docs/guides/playwright-pytest-screenshots/)
- [Pytest & Playwright: videos](/docs/guides/pytest-playwright-video/)

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

The example below is of a test that uses the playwright-pytest plugin to load a page and get its screenshot as bytes. The screenshot is then attached to the test result as `full-page.png`.

```python
import allure

def test_attach(page):
    page.goto("https://example.com/")
    png_bytes = page.screenshot()
    allure.attach(
        png_bytes,
        name="full-page",
        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 pathlib import Path

def test_attach_file(page):
    page.goto("https://example.com/")
    png_bytes = page.screenshot()
    Path("full-page.png").write_bytes(png_bytes)
    allure.attach.file(
        "full-page.png",
        name="full-page",
        attachment_type=allure.attachment_type.PNG
    )
```