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.

If the test function is decorated with the @pytest.mark.parametrize decorator, 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. 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 (login: {login})") def test_authentication(login): ...
Python
import allure import pytest @pytest.mark.parametrize("login", ["johndoe", "[email protected]"]) def test_authentication(login): allure.dynamic.title("Test Authentication (login: " + login + ")") ...

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

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

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(): ...
  • @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.mark.parametrize() decorator. See Parametrized tests for more details.

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
import allure import pytest @pytest.mark.parametrize("login", ["johndoe", "[email protected]"]) @allure.title("Test Authentication (login: {login})") def test_authentication(login): allure.dynamic.parameter("auth_method", "password") ... @allure.title("Test Authentication (login: empty)") def test_authentication_with_empty_login(): allure.dynamic.parameter("auth_method", "password") allure.dynamic.parameter("login", "") ...

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 )
Powered by
logo

Join our newsletter

Join our community

We aim to make Allure Report as reliable and user-friendly as possible, and together with the community, we're here to help when problems arise.

© 2024 Qameta Software Inc. All rights reserved.