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.

Some metadata fields can be used for selecting which test to run, see Specify description, links and other metadata and Options affecting test selection.

Title

• @allure.title(test_title: str)
• allure.dynamic.title(test_title: str)

Set the test's title.

The decorator variant of the function can also be used for describing pytest fixtures.

Python
import allure
import pytest

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

Python
import allure
import pytest

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

def test_with_my_fixture(my_fixture):
    ...

Python
import allure
import pytest

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

If the test function has parameters (see 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() method. In addition to the parameters themselves, a special field {param_id} is supported for inserting the parameter set ID (see the pytest documentation).

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

Python
import allure
import pytest

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

Python
import allure
import pytest

@pytest.mark.parametrize("login", ["johndoe", "[email protected]"],
                         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. 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.

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

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

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.

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

Python
import allure

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

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.

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

Python
import allure
from allure_commons.types import Severity

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

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

Python
import allure
from allure_commons.types import LabelType

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

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.

Python
import allure

@allure.id("123")
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 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 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.

Python
import allure

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

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

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.

Each function support setting one or more values at once.

Python
import allure

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

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.

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.

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

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

• Context steps

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

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

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 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 parametrization features. 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 for the tests history.

The parameters can be used in the test's title, see 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",
    "[email protected]",
])
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))
    ...

Attachments

Functions for adding 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.

You can use data produced by any function, not necessarily read from an actual file. For attaching contents of existing files, use attach.file() 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 MIME 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 MIME types are image/png and image/jpeg for screenshots and other images, application/json for JSON data, and text/plain for text files. The MIME 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 MIME 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(), 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
    )