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.
import allure
import pytest
@allure.title("Test Authentication")
def test_authentication():
...import allure
import pytest
@pytest.fixture()
@allure.title("Prepare for the test")
def my_fixture():
...
def test_with_my_fixture(my_fixture):
...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.
import allure
import pytest
@pytest.mark.parametrize("login", ["johndoe", "[email protected]"])
@allure.title("Test Authentication (as {login})")
def test_authentication(login):
...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.
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():
...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.
""")
...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:
import allure
@allure.tag("NewUI", "Essentials", "Authentication")
def test_authentication():
...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”.
import allure
from allure_commons.types import Severity
@allure.severity(Severity.CRITICAL)
def test_authentication():
...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().
import allure
from allure_commons.types import LabelType
@allure.label(LabelType.LANGUAGE, "python")
@allure.label(LabelType.FRAMEWORK, "pytest")
def test_authentication():
...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.
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.
import allure
@allure.link("https://dev.example.com/", name="Website")
@allure.issue("AUTH-123")
@allure.testcase("TMS-456")
def test_authentication():
...import allure
def pr(pr_id):
return allure.link(pr_id, name="PR {}".format(pr_id), link_type="pr")
@pr(123)
def test_authentication():
...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.
import allure
@allure.epic("Web interface")
@allure.feature("Essential features")
@allure.story("Authentication")
def test_authentication():
...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.
import allure
@allure.parent_suite("Tests for web interface")
@allure.suite("Tests for essential features")
@allure.sub_suite("Tests for authentication")
def test_authentication():
...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 standardstr.format()method.Context steps
Write a test step in-place but use the
with allure.step()statement to create its context.
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):
...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 parameterization 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 theallure_resultsdirectory if you publish it.
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))
...TIP
For more information, you can consult the guide on Pytest parameterization.
Attachments
Functions for adding attachments to test results.
TIP
Check out our guides for screenshots and videos in Pytest using Selenium or Playwright plugin:
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() 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_typeand, optionally, a filename extension asextension. For example:pythonallure.attach( '{"value":100}', attachment_type="application/json", extension="json" )Some popular media types are
image/pngandimage/jpegfor screenshots and other images,application/jsonfor JSON data, andtext/plainfor 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_typeclass asattachment_type. For example:pythonallure.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.
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.
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
)