测试人社区

Pytest-Marking test functions with attributes

By using the pytest.mark helper you can easily set metadata on your
test functions. You can find the full list of builtin markers in the
API Reference<marks ref>{.interpreted-text role=“ref”}. Or you can
list all the markers, including builtin and custom, using the CLI -
pytest --markers.

Here are some of the builtin markers:

  • usefixtures <usefixtures>{.interpreted-text role=“ref”} - use
    fixtures on a test function or class
  • filterwarnings <filterwarnings>{.interpreted-text role=“ref”} -
    filter certain warnings of a test function
  • skip <skip>{.interpreted-text role=“ref”} - always skip a test
    function
  • skipif <skipif>{.interpreted-text role=“ref”} - skip a test
    function if a certain condition is met
  • xfail <xfail>{.interpreted-text role=“ref”} - produce an
    “expected failure” outcome if a certain condition is met
  • parametrize <parametrizemark>{.interpreted-text role=“ref”} -
    perform multiple calls to the same test function.

It’s easy to create custom markers or to apply markers to whole test
classes or modules. Those markers can be used by plugins, and also are
commonly used to select tests <mark run>{.interpreted-text role=“ref”}
on the command-line with the -m option.

See mark examples{.interpreted-text role=“ref”} for examples which
also serve as documentation.

::: {.note}
::: {.title}
Note
:::

Marks can only be applied to tests, having no effect on
fixtures <fixtures>{.interpreted-text role=“ref”}.
:::

Registering marks

You can register custom marks in your pytest.ini file like this:

[pytest]
markers =
    slow: marks tests as slow (deselect with '-m "not slow"')
    serial

or in your pyproject.toml file like this:

[tool.pytest.ini_options]
markers = [
    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
    "serial",
]

Note that everything past the : after the mark name is an optional
description.

Alternatively, you can register new markers programmatically in a
pytest_configure <initialization-hooks>{.interpreted-text role=“ref”}
hook:

def pytest_configure(config):
    config.addinivalue_line(
        "markers", "env(name): mark test to run only on named environment"
    )

Registered marks appear in pytest’s help text and do not emit warnings
(see the next section). It is recommended that third-party plugins
always register their markers <registering-markers>{.interpreted-text
role=“ref”}.

Raising errors on unknown marks {#unknown-marks}

Unregistered marks applied with the @pytest.mark.name_of_the_mark
decorator will always emit a warning in order to avoid silently doing
something surprising due to mistyped names. As described in the previous
section, you can disable the warning for custom marks by registering
them in your pytest.ini file or using a custom pytest_configure
hook.

When the --strict-markers command-line flag is passed, any unknown
marks applied with the @pytest.mark.name_of_the_mark decorator will
trigger an error. You can enforce this validation in your project by
adding --strict-markers to addopts:

[pytest]
addopts = --strict-markers
markers =
    slow: marks tests as slow (deselect with '-m "not slow"')
    serial