Skip to content
Back to top

# API Reference

This page contains the full reference to pytest's API.

## Constants

### pytest.__version__

The current pytest version, as a string:

    >>> import pytest
    >>> pytest.__version__
    '7.0.0'

### pytest.HIDDEN_PARAM

Added in version 8.4.

Can be passed to `ids` of `Metafunc.parametrize` or to `id` of `pytest.param()` to hide a parameter set from the test name. Can only be used at most 1 time, as test names need to be unique.

### pytest.version_tuple

Added in version 7.0.

The current pytest version, as a tuple:

    >>> import pytest
    >>> pytest.version_tuple
    (7, 0, 0)

For pre-releases, the last component will be a string with the prerelease version:

    >>> import pytest
    >>> pytest.version_tuple
    (7, 0, '0rc1')

## Functions

### pytest.approx

approx(expected, rel=None, abs=None, nan_ok=False)

  Assert that two numbers (or two ordered sequences of numbers) are equal to each other within some tolerance.

  Due to the Floating-Point Arithmetic: Issues and Limitations, numbers that we would intuitively expect to be equal are not always so:

      >>> 0.1 + 0.2 == 0.3
      False

  This problem is commonly encountered when writing tests, e.g. when making sure that floating-point values are what you expect them to be. One way to deal with this problem is to assert that two floating-point numbers are equal to within some appropriate tolerance:

      >>> abs((0.1 + 0.2) - 0.3) < 1e-6
      True

  However, comparisons like this are tedious to write and difficult to understand. Furthermore, absolute comparisons like the one above are usually discouraged because there's no tolerance that works well for all situations. `1e-6` is good for numbers around `1`, but too small for very big numbers and too big for very small ones. It's better to express the tolerance as a fraction of the expected value, but relative comparisons like that are even more difficult to write correctly and concisely.

  The `approx` class performs floating-point comparisons using a syntax that's as intuitive as possible:

      >>> from pytest import approx
      >>> 0.1 + 0.2 == approx(0.3)
      True

  The same syntax also works for ordered sequences of numbers:

      >>> (0.1 + 0.2, 0.2 + 0.4) == approx((0.3, 0.6))
      True

  `numpy` arrays:

      >>> import numpy as np
      >>> np.array([0.1, 0.2]) + np.array([0.2, 0.4]) == approx(np.array([0.3, 0.6]))
      True

  And for a `numpy` array against a scalar:

      >>> import numpy as np
      >>> np.array([0.1, 0.2]) + np.array([0.2, 0.1]) == approx(0.3)
      True

  Only ordered sequences are supported, because `approx` needs to infer the relative position of the sequences without ambiguity. This means `sets` and other unordered sequences are not supported.

  Finally, dictionary values can also be compared:

      >>> {'a': 0.1 + 0.2, 'b': 0.2 + 0.4} == approx({'a': 0.3, 'b': 0.6})
      True

  The comparison will be true if both mappings have the same keys and their respective values match the expected tolerances.

  Tolerances

  By default, `approx` considers numbers within a relative tolerance of `1e-6` (i.e. one part in a million) of its expected value to be equal. This treatment would lead to surprising results if the expected value was `0.0`, because nothing but `0.0` itself is relatively close to `0.0`. To handle this case less surprisingly, `approx` also considers numbers within an absolute tolerance of `1e-12` of its expected value to be equal. Infinity and NaN are special cases. Infinity is only considered equal to itself, regardless of the relative tolerance. NaN is not considered equal to anything by default, but you can make it be equal to itself by setting the `nan_ok` argument to True. (This is meant to facilitate comparing arrays that use NaN to mean "no data".)

  Both the relative and absolute tolerances can be changed by passing arguments to the `approx` constructor:

      >>> 1.0001 == approx(1)
      False
      >>> 1.0001 == approx(1, rel=1e-3)
      True
      >>> 1.0001 == approx(1, abs=1e-3)
      True

  If you specify `abs` but not `rel`, the comparison will not consider the relative tolerance at all. In other words, two numbers that are within the default relative tolerance of `1e-6` will still be considered unequal if they exceed the specified absolute tolerance. If you specify both `abs` and `rel`, the numbers will be considered equal if either tolerance is met:

      >>> 1 + 1e-8 == approx(1)
      True
      >>> 1 + 1e-8 == approx(1, abs=1e-12)
      False
      >>> 1 + 1e-8 == approx(1, rel=1e-6, abs=1e-12)
      True

  Non-numeric types

  You can also use `approx` to compare non-numeric types, or dicts and sequences containing non-numeric types, in which case it falls back to strict equality. This can be useful for comparing dicts and sequences that can contain optional values:

      >>> {"required": 1.0000005, "optional": None} == approx({"required": 1, "optional": None})
      True
      >>> [None, 1.0000005] == approx([None,1])
      True
      >>> ["foo", 1.0000005] == approx([None,1])
      False

  If you're thinking about using `approx`, then you might want to know how it compares to other good ways of comparing floating-point numbers. All of these algorithms are based on relative and absolute tolerances and should agree for the most part, but they do have meaningful differences:

  - `math.isclose(a, b, rel_tol=1e-9, abs_tol=0.0)`: True if the relative tolerance is met w.r.t. either `a` or `b` or if the absolute tolerance is met. Because the relative tolerance is calculated w.r.t. both `a` and `b`, this test is symmetric (i.e. neither `a` nor `b` is a "reference value"). You have to specify an absolute tolerance if you want to compare to `0.0` because there is no tolerance by default. More information: `math.isclose()`.

  - `numpy.isclose(a, b, rtol=1e-5, atol=1e-8)`: True if the difference between `a` and `b` is less that the sum of the relative tolerance w.r.t. `b` and the absolute tolerance. Because the relative tolerance is only calculated w.r.t. `b`, this test is asymmetric and you can think of `b` as the reference value. Support for comparing sequences is provided by `numpy.allclose()`. More information: numpy.isclose.

  - `unittest.TestCase.assertAlmostEqual(a, b)`: True if `a` and `b` are within an absolute tolerance of `1e-7`. No relative tolerance is considered , so this function is not appropriate for very large or very small numbers. Also, it's only available in subclasses of `unittest.TestCase` and it's ugly because it doesn't follow PEP8. More information: `unittest.TestCase.assertAlmostEqual()`.

  - `a == pytest.approx(b, rel=1e-6, abs=1e-12)`: True if the relative tolerance is met w.r.t. `b` or if the absolute tolerance is met. Because the relative tolerance is only calculated w.r.t. `b`, this test is asymmetric and you can think of `b` as the reference value. In the special case that you explicitly specify an absolute tolerance but not a relative tolerance, only the absolute tolerance is considered.

  Note

  `approx` can handle numpy arrays, but we recommend the specialised test helpers in Test support if you need support for comparisons, NaNs, or ULP-based tolerances.

  To match strings using regex, you can use Matches from the re_assert package.

  Note

  Unlike built-in equality, this function considers booleans unequal to numeric zero or one. For example:

      >>> 1 == approx(True)
      False

  Warning

  Changed in version 3.2.

  In order to avoid inconsistent behavior, `TypeError` is raised for `>`, `>=`, `<` and `<=` comparisons. The example below illustrates the problem:

      assert approx(0.1) > 0.1 + 1e-10  # calls approx(0.1).__gt__(0.1 + 1e-10)
      assert 0.1 + 1e-10 > approx(0.1)  # calls approx(0.1).__lt__(0.1 + 1e-10)

  In the second example one expects `approx(0.1).__le__(0.1 + 1e-10)` to be called. But instead, `approx(0.1).__lt__(0.1 + 1e-10)` is used to comparison. This is because the call hierarchy of rich comparisons follows a fixed behavior. More information: `object.__ge__()`

  Changed in version 3.7.1: `approx` raises `TypeError` when it encounters a dict value or sequence element of non-numeric type.

  Changed in version 6.1.0: `approx` falls back to strict equality for non-numeric types instead of raising `TypeError`.

### pytest.fail

Tutorial: How to use skip and xfail to deal with tests that cannot succeed

fail(reason[, pytrace=True])

  Explicitly fail an executing test with the given message.

  Parameters:

    - reason (str) -- The message to show the user as reason for the failure.

    - pytrace (bool) -- If False, msg represents the full failure information and no python traceback will be reported.

  Raises:

    pytest.fail.Exception -- The exception that is raised.

class pytest.fail.Exception

  The exception raised by `pytest.fail()`.

### pytest.skip

skip(reason[, allow_module_level=False])

  Skip an executing test with the given message.

  This function should be called only during testing (setup, call or teardown) or during collection by using the `allow_module_level` flag. This function can be called in doctests as well.

  Parameters:

    - reason (str) -- The message to show the user as reason for the skip.

    - allow_module_level (bool) --

      Allows this function to be called at module level. Raising the skip exception at module level will stop the execution of the module and prevent the collection of all tests in the module, even those defined before the `skip` call.

      Defaults to False.

  Raises:

    pytest.skip.Exception -- The exception that is raised.

  Note

  It is better to use the pytest.mark.skipif marker when possible to declare a test to be skipped under certain conditions like mismatching platforms or dependencies. Similarly, use the `# doctest: +SKIP` directive (see `doctest.SKIP`) to skip a doctest statically.

class pytest.skip.Exception

  The exception raised by `pytest.skip()`.

### pytest.importorskip

importorskip(modname, minversion=None, reason=None, *, exc_type=None)

  Import and return the requested module `modname`, or skip the current test if the module cannot be imported.

  Parameters:

    - modname (str) -- The name of the module to import.

    - minversion (str | None) -- If given, the imported module's `__version__` attribute must be at least this minimal version, otherwise the test is still skipped.

    - reason (str | None) -- If given, this reason is shown as the message when the module cannot be imported.

    - exc_type (type[ImportError] | None) --

      The exception that should be captured in order to skip modules. Must be `ImportError` or a subclass.

      If the module can be imported but raises `ImportError`, pytest will issue a warning to the user, as often users expect the module not to be found (which would raise `ModuleNotFoundError` instead).

      This warning can be suppressed by passing `exc_type=ImportError` explicitly.

      See pytest.importorskip default behavior regarding ImportError for details.

  Returns:

    The imported module. This should be assigned to its canonical name.

  Raises:

    pytest.skip.Exception -- If the module cannot be imported.

  Return type:

    Any

  Example:

      docutils = pytest.importorskip("docutils")

  Added in version 8.2: The `exc_type` parameter.

### pytest.xfail

xfail(reason='')

  Imperatively xfail an executing test or setup function with the given reason.

  This function should be called only during testing (setup, call or teardown).

  No other code is executed after using `xfail()` (it is implemented internally by raising an exception).

  Parameters:

    reason (str) -- The message to show the user as reason for the xfail.

  Note

  It is better to use the pytest.mark.xfail marker when possible to declare a test to be xfailed under certain conditions like known bugs or missing features.

  Raises:

    pytest.xfail.Exception -- The exception that is raised.

class pytest.xfail.Exception

  The exception raised by `pytest.xfail()`.

### pytest.exit

exit(reason[, returncode=None])

  Exit testing process.

  Parameters:

    - reason (str) -- The message to show as the reason for exiting pytest. reason has a default value only because `msg` is deprecated.

    - returncode (int | None) -- Return code to be used when exiting pytest. None means the same as `0` (no error), same as `sys.exit()`.

  Raises:

    pytest.exit.Exception -- The exception that is raised.

class pytest.exit.Exception

  The exception raised by `pytest.exit()`.

### pytest.main

Tutorial: Calling pytest from Python code

main(args=None, plugins=None)

  Perform an in-process test run.

  Parameters:

    - args (list[str] | PathLike[str] | None) -- List of command line arguments. If `None` or not given, defaults to reading arguments directly from the process command line (`sys.argv`).

    - plugins (Sequence[str | object] | None) -- List of plugin objects to be auto-registered during initialization.

  Returns:

    An exit code.

  Return type:

    int | ExitCode

### pytest.param

param(*values[, id][, marks])

  Specify a parameter in pytest.mark.parametrize calls or parametrized fixtures.

      @pytest.mark.parametrize(
          "test_input,expected",
          [
              ("3+5", 8),
              pytest.param("6*9", 42, marks=pytest.mark.xfail),
          ],
      )
      def test_eval(test_input, expected):
          assert eval(test_input) == expected

  Parameters:

    - values (object) -- Variable args of the values of the parameter set, in order.

    - marks (MarkDecorator | Collection[MarkDecorator | Mark]) --

      A single mark or a list of marks to be applied to this parameter set.

      pytest.mark.usefixtures cannot be added via this parameter.

    - id (str | Literal[pytest.HIDDEN_PARAM] | None) --

      The id to attribute to this parameter set.

      Added in version 8.4: pytest.HIDDEN_PARAM means to hide the parameter set from the test name. Can only be used at most 1 time, as test names need to be unique.

### pytest.raises

Tutorial: Assertions about approximate equality

### pytest.deprecated_call

Tutorial: Ensuring code triggers a deprecation warning

### pytest.register_assert_rewrite

Tutorial: Assertion Rewriting

register_assert_rewrite(*names)

  Register one or more module names to be rewritten on import.

  This function will make sure that this module or all modules inside the package will get their assert statements rewritten. Thus you should make sure to call this before the module is actually imported, usually in your __init__.py if you are a plugin using a package.

  Parameters:

    names (str) -- The module names to register.

### pytest.warns

Tutorial: Asserting warnings with the warns function

### pytest.freeze_includes

Tutorial: Freezing pytest

freeze_includes()

  Return a list of module names used by pytest that should be included by cx_freeze.

## Marks

Marks can be used to apply metadata to test functions (but not fixtures), which can then be accessed by fixtures or plugins.

### pytest.mark.filterwarnings

Tutorial: @pytest.mark.filterwarnings

Add warning filters to marked test items.

pytest.mark.filterwarnings(filter)
  Parameters:

    filter (str) --

    A warning specification string, which is composed of contents of the tuple `(action, message, category, module, lineno)` as specified in The Warnings Filter section of the Python documentation, separated by `":"`. Optional fields can be omitted. Module names passed for filtering are not regex-escaped.

    For example:

        @pytest.mark.filterwarnings("ignore:.*usage will be deprecated.*:DeprecationWarning")
        def test_foo(): ...

### pytest.mark.parametrize

Tutorial: How to parametrize fixtures and test functions

This mark has the same signature as `pytest.Metafunc.parametrize()`; see there.

### pytest.mark.skip

Tutorial: Skipping test functions

Unconditionally skip a test function.

pytest.mark.skip(reason=None)
  Parameters:

    reason (str) -- Reason why the test function is being skipped.

### pytest.mark.skipif

Tutorial: Skipping test functions

Skip a test function if a condition is `True`.

pytest.mark.skipif(condition, *, reason=None)
  Parameters:

    - condition (bool or str) -- `True/False` if the condition should be skipped or a condition string.

    - reason (str) -- Reason why the test function is being skipped.

### pytest.mark.usefixtures

Tutorial: Use fixtures in classes and modules with usefixtures

Mark a test function as using the given fixture names.

pytest.mark.usefixtures(*names)
  Parameters:

    args -- The names of the fixture to use, as strings.

Note

When using `usefixtures` in hooks, it can only load fixtures when applied to a test function before test setup (for example in the `pytest_collection_modifyitems` hook).

Also note that this mark has no effect when applied to fixtures.

### pytest.mark.xfail

Tutorial: XFail: mark test functions as expected to fail

Marks a test function as expected to fail.

pytest.mark.xfail(condition=False, *, reason=None, raises=None, run=True, strict=strict_xfail)
  Parameters:

    - condition (Union[bool, str]) -- Condition for marking the test function as xfail (`True/False` or a condition string). If a `bool`, you also have to specify `reason` (see condition string).

    - reason (str) -- Reason why the test function is marked as xfail.

    - raises (Type[`Exception`]) -- Exception class (or tuple of classes) expected to be raised by the test function; other exceptions will fail the test. Note that subclasses of the classes passed will also result in a match (similar to how the `except` statement works).

    - run (bool) -- Whether the test function should actually be executed. If `False`, the function will always xfail and will not be executed (useful if a function is segfaulting).

    - strict (bool) --

      - If `False` the function will be shown in the terminal output as `xfailed` if it fails and as `xpass` if it passes. In both cases this will not cause the test suite to fail as a whole. This is particularly useful to mark flaky tests (tests that fail at random) to be tackled later.

      - If `True`, the function will be shown in the terminal output as `xfailed` if it fails, but if it unexpectedly passes then it will fail the test suite. This is particularly useful to mark functions that are always failing and there should be a clear indication if they unexpectedly start to pass (for example a new release of a library fixes a known bug).

      Defaults to `strict_xfail`, which is `False` by default.

### Custom marks

Marks are created dynamically using the factory object `pytest.mark` and applied as a decorator.

For example:

    @pytest.mark.timeout(10, "slow", method="thread")
    def test_function(): ...

Will create and attach a `Mark` object to the collected `Item`, which can then be accessed by fixtures or hooks with `Node.iter_markers`. The `mark` object will have the following attributes:

    mark.args == (10, "slow")
    mark.kwargs == {"method": "thread"}

Example for using multiple custom markers:

    @pytest.mark.timeout(10, "slow", method="thread")
    @pytest.mark.slow
    def test_function(): ...

When `Node.iter_markers` or `Node.iter_markers_with_node` is used with multiple markers, the marker closest to the function will be iterated over first. The above example will result in `@pytest.mark.slow` followed by `@pytest.mark.timeout(...)`.

## Fixtures

Tutorial: Fixtures reference

Fixtures are requested by test functions or other fixtures by declaring them as argument names.

Example of a test requiring a fixture:

    def test_output(capsys):
        print("hello")
        out, err = capsys.readouterr()
        assert out == "hello\n"

Example of a fixture requiring another fixture:

    @pytest.fixture
    def db_session(tmp_path):
        fn = tmp_path / "db.file"
        return connect(fn)

For more details, consult the full fixtures docs.

### @pytest.fixture

### capfd

Tutorial: How to capture stdout/stderr output

### capfdbinary

Tutorial: How to capture stdout/stderr output

### caplog

Tutorial: How to manage logging

final class LogCaptureFixture

  Provides access and control of log capturing.

  property handler: LogCaptureHandler

    Get the logging handler used by the fixture.

  get_records(when)

    Get the logging records for one of the possible test phases.

    Parameters:

      when (Literal['setup', 'call', 'teardown']) -- Which test phase to obtain the records from. Valid values are: "setup", "call" and "teardown".

    Returns:

      The list of captured records at the given stage.

    Return type:

      list[LogRecord]

    Added in version 3.4.

  property text: str

    The formatted log text.

  property records: list[LogRecord]

    The list of log records.

  property record_tuples: list[tuple[str, int, str]]

    A list of a stripped down version of log records intended for use in assertion comparison.

    The format of the tuple is:

    > (logger_name, log_level, message)

  property messages: list[str]

    A list of format-interpolated log messages.

    Unlike 'records', which contains the format string and parameters for interpolation, log messages in this list are all interpolated.

    Unlike 'text', which contains the output from the handler, log messages in this list are unadorned with levels, timestamps, etc, making exact comparisons more reliable.

    Note that traceback or stack info (from `logging.exception()` or the `exc_info` or `stack_info` arguments to the logging functions) is not included, as this is added by the formatter in the handler.

    Added in version 3.7.

  clear()

    Reset the list of log records and the captured log text.

  set_level(level, logger=None)

    Set the threshold level of a logger for the duration of a test.

    Logging messages which are less severe than this level will not be captured.

    Changed in version 3.4: The levels of the loggers changed by this function will be restored to their initial values at the end of the test.

    Will enable the requested logging level if it was disabled via `logging.disable()`.

    Parameters:

      - level (int | str) -- The level.

      - logger (str | None) -- The logger to update. If not given, the root logger.

  at_level(level, logger=None)

    Context manager that sets the level for capturing of logs. After the end of the 'with' statement the level is restored to its original value.

    Will enable the requested logging level if it was disabled via `logging.disable()`.

    Parameters:

      - level (int | str) -- The level.

      - logger (str | None) -- The logger to update. If not given, the root logger.

  filtering(filter_)

    Context manager that temporarily adds the given filter to the caplog's `handler()` for the 'with' statement block, and removes that filter at the end of the block.

    Parameters:

      filter -- A custom `logging.Filter` object.

    Added in version 7.5.

### capsys

Tutorial: How to capture stdout/stderr output

class CaptureFixture

  Object returned by the `capsys`, `capsysbinary`, `capfd` and `capfdbinary` fixtures.

  readouterr()

    Read and return the captured output so far, resetting the internal buffer.

    Returns:

      The captured content as a namedtuple with `out` and `err` string attributes.

    Return type:

      CaptureResult

  disabled()

    Temporarily disable capturing while inside the `with` block.

### capteesys

Tutorial: How to capture stdout/stderr output

### capsysbinary

Tutorial: How to capture stdout/stderr output

### config.cache

Tutorial: How to re-run failed tests and maintain state between test runs

The `config.cache` object allows other plugins and fixtures to store and retrieve values across test runs. To access it from fixtures request `pytestconfig` into your fixture and get it with `pytestconfig.cache`.

Under the hood, the cache plugin uses the simple `dumps`/`loads` API of the `json` stdlib module.

`config.cache` is an instance of `pytest.Cache`:

final class Cache

  Instance of the `cache` fixture.

  mkdir(name)

    Return a directory path object with the given name.

    If the directory does not yet exist, it will be created. You can use it to manage files to e.g. store/retrieve database dumps across test sessions.

    Added in version 7.0.

    Parameters:

      name (str) -- Must be a string not containing a `/` separator. Make sure the name contains your plugin or application identifiers to prevent clashes with other cache users.

  get(key, default)

    Return the cached value for the given key.

    If no value was yet cached or the value cannot be read, the specified default is returned.

    Parameters:

      - key (str) -- Must be a `/` separated value. Usually the first name is the name of your plugin or your application.

      - default -- The value to return in case of a cache-miss or invalid cache value.

  set(key, value)

    Save value for the given key.

    Parameters:

      - key (str) -- Must be a `/` separated value. Usually the first name is the name of your plugin or your application.

      - value (object) -- Must be of any combination of basic python types, including nested types like lists of dictionaries.

### doctest_namespace

Tutorial: How to run doctests

doctest_namespace()

  Fixture that returns a `dict` that will be injected into the namespace of doctests.

  Usually this fixture is used in conjunction with another `autouse` fixture:

      @pytest.fixture(autouse=True)
      def add_np(doctest_namespace):
          doctest_namespace["np"] = numpy

  For more details: 'doctest_namespace' fixture.

### monkeypatch

Tutorial: How to monkeypatch/mock modules and environments

final class MonkeyPatch

  Helper to conveniently monkeypatch attributes/items/environment variables/syspath.

  Returned by the `monkeypatch` fixture.

  Changed in version 6.2: Can now also be used directly as `pytest.MonkeyPatch()`, for when the fixture is not available. In this case, use `with MonkeyPatch.context() as mp:` or remember to call `undo()` explicitly.

  classmethod context()

    Context manager that returns a new `MonkeyPatch` object which undoes any patching done inside the `with` block upon exit.

    Example:

        import functools

        def test_partial(monkeypatch):
            with monkeypatch.context() as m:
                m.setattr(functools, "partial", 3)

    Useful in situations where it is desired to undo some patches before the test ends, such as mocking `stdlib` functions that might break pytest itself if mocked (for examples of this see #3290).

  setattr(target: str, name: object, value: ~_pytest.monkeypatch.Notset = <notset>, raising: bool = True) → None
  setattr(target: object, name: str, value: object, raising: bool = True) → None

    Set attribute value on target, memorizing the old value.

    For example:

        import os

        monkeypatch.setattr(os, "getcwd", lambda: "/")

    The code above replaces the `os.getcwd()` function by a `lambda` which always returns `"/"`.

    For convenience, you can specify a string as `target` which will be interpreted as a dotted import path, with the last part being the attribute name:

        monkeypatch.setattr("os.getcwd", lambda: "/")

    Raises `AttributeError` if the attribute does not exist, unless `raising` is set to False.

    Where to patch

    `monkeypatch.setattr` works by (temporarily) changing the object that a name points to with another one. There can be many names pointing to any individual object, so for patching to work you must ensure that you patch the name used by the system under test.

    See the section Where to patch in the `unittest.mock` docs for a complete explanation, which is meant for `unittest.mock.patch()` but applies to `monkeypatch.setattr` as well.

  delattr(target, name=<notset>, raising=True)

    Delete attribute `name` from `target`.

    If no `name` is specified and `target` is a string it will be interpreted as a dotted import path with the last part being the attribute name.

    Raises AttributeError it the attribute does not exist, unless `raising` is set to False.

  setitem(dic, name, value)

    Set dictionary entry `name` to value.

  delitem(dic, name, raising=True)

    Delete `name` from dict.

    Raises `KeyError` if it doesn't exist, unless `raising` is set to False.

  setenv(name, value, prepend=None)

    Set environment variable `name` to `value`.

    If `prepend` is a character, read the current environment variable value and prepend the `value` adjoined with the `prepend` character.

  delenv(name, raising=True)

    Delete `name` from the environment.

    Raises `KeyError` if it does not exist, unless `raising` is set to False.

  syspath_prepend(path)

    Prepend `path` to `sys.path` list of import locations.

  chdir(path)

    Change the current working directory to the specified path.

    Parameters:

      path (str | PathLike[str]) -- The path to change into.

  undo()

    Undo previous changes.

    This call consumes the undo stack. Calling it a second time has no effect unless you do more monkeypatching after the undo call.

    There is generally no need to call `undo()`, since it is called automatically during tear-down.

    Note

    The same `monkeypatch` fixture is used across a single test function invocation. If `monkeypatch` is used both by the test function itself and one of the test fixtures, calling `undo()` will undo all of the changes made in both functions.

    Prefer to use `context()` instead.

### pytestconfig

pytestconfig()

  Session-scoped fixture that returns the session's `pytest.Config` object.

  Example:

      def test_foo(pytestconfig):
          if pytestconfig.get_verbosity() > 0:
              ...

### pytester

Added in version 6.2.

Provides a `Pytester` instance that can be used to run and test pytest itself.

It provides an empty directory where pytest can be executed in isolation, and contains facilities to write tests, configuration files, and match against expected output.

To use it, include in your topmost `conftest.py` file:

    pytest_plugins = "pytester"

final class Pytester

  Facilities to write tests/configuration files, execute pytest in isolation, and match against expected output, perfect for black-box testing of pytest plugins.

  It attempts to isolate the test run from external factors as much as possible, modifying the current working directory to `path` and environment variables during initialization.

  exception TimeoutExpired
  plugins: list[str | object]

    A list of plugins to use with `parseconfig()` and `runpytest()`. Initially this is an empty list but plugins can be added to the list.

    When running in subprocess mode, specify plugins by name (str) - adding plugin objects directly is not supported.

  property path: Path

    Temporary directory path used to create files/run tests from, etc.

  make_hook_recorder(pluginmanager)

    Create a new `HookRecorder` for a `PytestPluginManager`.

  chdir()

    Cd into the temporary directory.

    This is done automatically upon instantiation.

  makefile(ext, *args, **kwargs)

    Create new text file(s) in the test directory.

    Parameters:

      - ext (str) -- The extension the file(s) should use, including the dot, e.g. `.py`.

      - args (str) -- All args are treated as strings and joined using newlines. The result is written as contents to the file. The name of the file is based on the test function requesting this fixture.

      - kwargs (str) -- Each keyword is the name of a file, while the value of it will be written as contents of the file.

    Returns:

      The first created file.

    Return type:

      Path

    Examples:

        pytester.makefile(".txt", "line1", "line2")

        pytester.makefile(".ini", pytest="[pytest]\naddopts=-rs\n")

    To create binary files, use `pathlib.Path.write_bytes()` directly:

        filename = pytester.path.joinpath("foo.bin")
        filename.write_bytes(b"...")

  makeconftest(source)

    Write a conftest.py file.

    Parameters:

      source (str) -- The contents.

    Returns:

      The conftest.py file.

    Return type:

      Path

  makeini(source)

    Write a tox.ini file.

    Parameters:

      source (str) -- The contents.

    Returns:

      The tox.ini file.

    Return type:

      Path

  maketoml(source)

    Write a pytest.toml file.

    Parameters:

      source (str) -- The contents.

    Returns:

      The pytest.toml file.

    Return type:

      Path

    Added in version 9.0.

  getinicfg(source)

    Return the pytest section from the tox.ini config file.

  makepyprojecttoml(source)

    Write a pyproject.toml file.

    Parameters:

      source (str) -- The contents.

    Returns:

      The pyproject.ini file.

    Return type:

      Path

    Added in version 6.0.

  makepyfile(*args, **kwargs)

    Shortcut for .makefile() with a .py extension.

    Defaults to the test name with a '.py' extension, e.g test_foobar.py, overwriting existing files.

    Examples:

        def test_something(pytester):
            # Initial file is created test_something.py.
            pytester.makepyfile("foobar")
            # To create multiple files, pass kwargs accordingly.
            pytester.makepyfile(custom="foobar")
            # At this point, both 'test_something.py' & 'custom.py' exist in the test directory.

  maketxtfile(*args, **kwargs)

    Shortcut for .makefile() with a .txt extension.

    Defaults to the test name with a '.txt' extension, e.g test_foobar.txt, overwriting existing files.

    Examples:

        def test_something(pytester):
            # Initial file is created test_something.txt.
            pytester.maketxtfile("foobar")
            # To create multiple files, pass kwargs accordingly.
            pytester.maketxtfile(custom="foobar")
            # At this point, both 'test_something.txt' & 'custom.txt' exist in the test directory.

  syspathinsert(path=None)

    Prepend a directory to sys.path, defaults to `path`.

    This is undone automatically when this object dies at the end of each test.

    Parameters:

      path (str | PathLike[str] | None) -- The path.

  mkdir(name)

    Create a new (sub)directory.

    Parameters:

      name (str | PathLike[str]) -- The name of the directory, relative to the pytester path.

    Returns:

      The created directory.

    Return type:

      pathlib.Path

  mkpydir(name)

    Create a new python package.

    This creates a (sub)directory with an empty `__init__.py` file so it gets recognised as a Python package.

  copy_example(name=None)

    Copy file from project's directory into the testdir.

    Parameters:

      name (str | None) -- The name of the file to copy.

    Returns:

      Path to the copied directory (inside `self.path`).

    Return type:

      pathlib.Path

  getnode(config, arg)

    Get the collection node of a file.

    Parameters:

      - config (Config) -- A pytest config. See `parseconfig()` and `parseconfigure()` for creating it.

      - arg (str | PathLike[str]) -- Path to the file.

    Returns:

      The node.

    Return type:

      Collector | Item

  getpathnode(path)

    Return the collection node of a file.

    This is like `getnode()` but uses `parseconfigure()` to create the (configured) pytest Config instance.

    Parameters:

      path (str | PathLike[str]) -- Path to the file.

    Returns:

      The node.

    Return type:

      Collector | Item

  genitems(colitems)

    Generate all test items from a collection node.

    This recurses into the collection node and returns a list of all the test items contained within.

    Parameters:

      colitems (Sequence[Item | Collector]) -- The collection nodes.

    Returns:

      The collected items.

    Return type:

      list[Item]

  runitem(source)

    Run the "test_func" Item.

    The calling test instance (class containing the test method) must provide a `.getrunner()` method which should return a runner which can run the test protocol for a single item, e.g. `_pytest.runner.runtestprotocol`.

  inline_runsource(source, *cmdlineargs)

    Run a test module in process using `pytest.main()`.

    This run writes "source" into a temporary file and runs `pytest.main()` on it, returning a `HookRecorder` instance for the result.

    Parameters:

      - source (str) -- The source code of the test module.

      - cmdlineargs -- Any extra command line arguments to use.

  inline_genitems(*args)

    Run `pytest.main(['--collect-only'])` in-process.

    Runs the `pytest.main()` function to run all of pytest inside the test process itself like `inline_run()`, but returns a tuple of the collected items and a `HookRecorder` instance.

  inline_run(*args, plugins=(), no_reraise_ctrlc=False)

    Run `pytest.main()` in-process, returning a HookRecorder.

    Runs the `pytest.main()` function to run all of pytest inside the test process itself. This means it can return a `HookRecorder` instance which gives more detailed results from that run than can be done by matching stdout/stderr from `runpytest()`.

    Parameters:

      - args (str | PathLike[str]) -- Command line arguments to pass to `pytest.main()`.

      - plugins -- Extra plugin instances the `pytest.main()` instance should use.

      - no_reraise_ctrlc (bool) -- Typically we reraise keyboard interrupts from the child run. If True, the KeyboardInterrupt exception is captured.

  runpytest_inprocess(*args, **kwargs)

    Return result of running pytest in-process, providing a similar interface to what self.runpytest() provides.

  runpytest(*args, **kwargs)

    Run pytest inline or in a subprocess, depending on the command line option "--runpytest" and return a `RunResult`.

  parseconfig(*args)

    Return a new pytest `pytest.Config` instance from given commandline args.

    This invokes the pytest bootstrapping code in _pytest.config to create a new `pytest.PytestPluginManager` and call the `pytest_cmdline_parse` hook to create a new `pytest.Config` instance.

    If `plugins` has been populated they should be plugin modules to be registered with the plugin manager.

  parseconfigure(*args)

    Return a new pytest configured Config instance.

    Returns a new `pytest.Config` instance like `parseconfig()`, but also calls the `pytest_configure` hook.

  getitem(source, funcname='test_func')

    Return the test item for a test function.

    Writes the source to a python file and runs pytest's collection on the resulting module, returning the test item for the requested function name.

    Parameters:

      - source (str | PathLike[str]) -- The module source.

      - funcname (str) -- The name of the test function for which to return a test item.

    Returns:

      The test item.

    Return type:

      Item

  getitems(source)

    Return all test items collected from the module.

    Writes the source to a Python file and runs pytest's collection on the resulting module, returning all test items contained within.

  getmodulecol(source, configargs=(), *, withinit=False)

    Return the module collection node for `source`.

    Writes `source` to a file using `makepyfile()` and then runs the pytest collection on it, returning the collection node for the test module.

    Parameters:

      - source (str | PathLike[str]) -- The source code of the module to collect.

      - configargs -- Any extra arguments to pass to `parseconfigure()`.

      - withinit (bool) -- Whether to also write an `__init__.py` file to the same directory to ensure it is a package.

  collect_by_name(modcol, name)

    Return the collection node for name from the module collection.

    Searches a module collection node for a collection node matching the given name.

    Parameters:

      - modcol (Collector) -- A module collection node; see `getmodulecol()`.

      - name (str) -- The name of the node to return.

  popen(cmdargs, stdout=-1, stderr=-1, stdin=NotSetType.token, **kw)

    Invoke `subprocess.Popen`.

    Calls `subprocess.Popen` making sure the current working directory is in `PYTHONPATH`.

    You probably want to use `run()` instead.

  run(*cmdargs, timeout=None, stdin=NotSetType.token)

    Run a command with arguments.

    Run a process using `subprocess.Popen` saving the stdout and stderr.

    Parameters:

      - cmdargs (str | PathLike[str]) -- The sequence of arguments to pass to `subprocess.Popen`, with path-like objects being converted to `str` automatically.

      - timeout (float | None) -- The period in seconds after which to timeout and raise `Pytester.TimeoutExpired`.

      - stdin (_pytest.compat.NotSetType | bytes | IO[Any] | int) --

        Optional standard input.

        - If it is `CLOSE_STDIN` (Default), then this method calls `subprocess.Popen` with `stdin=subprocess.PIPE`, and the standard input is closed immediately after the new command is started.

        - If it is of type `bytes`, these bytes are sent to the standard input of the command.

        - Otherwise, it is passed through to `subprocess.Popen`. For further information in this case, consult the document of the `stdin` parameter in `subprocess.Popen`.

    Returns:

      The result.

    Return type:

      RunResult

  runpython(script)

    Run a python script using sys.executable as interpreter.

  runpython_c(command)

    Run `python -c "command"`.

  runpytest_subprocess(*args, timeout=None)

    Run pytest as a subprocess with given arguments.

    Any plugins added to the `plugins` list will be added using the `-p` command line option. Additionally `--basetemp` is used to put any temporary files and directories in a numbered directory prefixed with "runpytest-" to not conflict with the normal numbered pytest location for temporary files and directories.

    Parameters:

      - args (str | PathLike[str]) -- The sequence of arguments to pass to the pytest subprocess.

      - timeout (float | None) -- The period in seconds after which to timeout and raise `Pytester.TimeoutExpired`.

    Returns:

      The result.

    Return type:

      RunResult

  spawn_pytest(string, expect_timeout=10.0)

    Run pytest using pexpect.

    This makes sure to use the right pytest and sets up the temporary directory locations.

    The pexpect child is returned.

  spawn(cmd, expect_timeout=10.0)

    Run a command using pexpect.

    The pexpect child is returned.

final class RunResult

  The result of running a command from `Pytester`.

  ret: int | ExitCode

    The return value.

  outlines

    List of lines captured from stdout.

  errlines

    List of lines captured from stderr.

  stdout

    `LineMatcher` of stdout.

    Use e.g. `str(stdout)` to reconstruct stdout, or the commonly used `stdout.fnmatch_lines()` method.

  stderr

    `LineMatcher` of stderr.

  duration

    Duration in seconds.

  parseoutcomes()

    Return a dictionary of outcome noun -> count from parsing the terminal output that the test process produced.

    The returned nouns will always be in plural form:

        ======= 1 failed, 1 passed, 1 warning, 1 error in 0.13s ====

    Will return `{"failed": 1, "passed": 1, "warnings": 1, "errors": 1}`.

  classmethod parse_summary_nouns(lines)

    Extract the nouns from a pytest terminal summary line.

    It always returns the plural noun for consistency:

        ======= 1 failed, 1 passed, 1 warning, 1 error in 0.13s ====

    Will return `{"failed": 1, "passed": 1, "warnings": 1, "errors": 1}`.

  assert_outcomes(passed=0, skipped=0, failed=0, errors=0, xpassed=0, xfailed=0, warnings=None, deselected=None)

    Assert that the specified outcomes appear with the respective numbers (0 means it didn't occur) in the text output from a test run.

    `warnings` and `deselected` are only checked if not None.

class LineMatcher

  Flexible matching of text.

  This is a convenience class to test large texts like the output of commands.

  The constructor takes a list of lines without their trailing newlines, i.e. `text.splitlines()`.

  __str__()

    Return the entire original text.

    Added in version 6.2: You can use `str()` in older versions.

  fnmatch_lines_random(lines2)

    Check lines exist in the output in any order (using `fnmatch.fnmatch()`).

  re_match_lines_random(lines2)

    Check lines exist in the output in any order (using `re.match()`).

  get_lines_after(fnline)

    Return all lines following the given line in the text.

    The given line can contain glob wildcards.

  fnmatch_lines(lines2, *, consecutive=False)

    Check lines exist in the output (using `fnmatch.fnmatch()`).

    The argument is a list of lines which have to match and can use glob wildcards. If they do not match a pytest.fail() is called. The matches and non-matches are also shown as part of the error message.

    Parameters:

      - lines2 (Sequence[str]) -- String patterns to match.

      - consecutive (bool) -- Match lines consecutively?

  re_match_lines(lines2, *, consecutive=False)

    Check lines exist in the output (using `re.match()`).

    The argument is a list of lines which have to match using `re.match`. If they do not match a pytest.fail() is called.

    The matches and non-matches are also shown as part of the error message.

    Parameters:

      - lines2 (Sequence[str]) -- string patterns to match.

      - consecutive (bool) -- match lines consecutively?

  no_fnmatch_line(pat)

    Ensure captured lines do not match the given pattern, using `fnmatch.fnmatch`.

    Parameters:

      pat (str) -- The pattern to match lines.

  no_re_match_line(pat)

    Ensure captured lines do not match the given pattern, using `re.match`.

    Parameters:

      pat (str) -- The regular expression to match lines.

  str()

    Return the entire original text.

final class HookRecorder

  Record all hooks called in a plugin manager.

  Hook recorders are created by `Pytester`.

  This wraps all the hook calls in the plugin manager, recording each call before propagating the normal calls.

  getcalls(names)

    Get all recorded calls to hooks with the given names (or name).

  matchreport(inamepart='', names=('pytest_runtest_logreport', 'pytest_collectreport'), when=None)

    Return a testreport whose dotted import path matches.

final class RecordedHookCall

  A recorded call to a hook.

  The arguments to the hook call are set as attributes. For example:

      calls = hook_recorder.getcalls("pytest_runtest_setup")
      # Suppose pytest_runtest_setup was called once with `item=an_item`.
      assert calls[0].item is an_item

### record_property

Tutorial: record_property

record_property()

  Add extra properties to the calling test.

  User properties become part of the test report and are available to the configured reporters, like JUnit XML.

  The fixture is callable with `name, value`. The value is automatically XML-encoded.

  Example:

      def test_function(record_property):
          record_property("example_key", 1)

### record_testsuite_property

Tutorial: record_testsuite_property

record_testsuite_property()

  Record a new `<property>` tag as child of the root `<testsuite>`.

  This is suitable to writing global information regarding the entire test suite, and is compatible with `xunit2` JUnit family.

  This is a `session`-scoped fixture which is called with `(name, value)`. Example:

      def test_foo(record_testsuite_property):
          record_testsuite_property("ARCH", "PPC")
          record_testsuite_property("STORAGE_TYPE", "CEPH")

  Parameters:

    - name -- The property name.

    - value -- The property value. Will be converted to a string.

  Warning

  Currently this fixture does not work with the pytest-xdist plugin. See #7767 for details.

### recwarn

Tutorial: Recording warnings

class WarningsRecorder

  A context manager to record raised warnings.

  Each recorded warning is an instance of `warnings.WarningMessage`.

  Adapted from `warnings.catch_warnings`.

  Note

  `DeprecationWarning` and `PendingDeprecationWarning` are treated differently; see Ensuring code triggers a deprecation warning.

  property list: list[WarningMessage]

    The list of recorded warnings.

  __getitem__(i)

    Get a recorded warning by index.

  __iter__()

    Iterate through the recorded warnings.

  __len__()

    The number of recorded warnings.

  pop(cls=<class 'Warning'>)

    Pop the first recorded warning which is an instance of `cls`, but not an instance of a child class of any other match. Raises `AssertionError` if there is no match.

  clear()

    Clear the list of recorded warnings.

### request

Example: Pass different values to a test function, depending on command line options

The `request` fixture is a special fixture providing information of the requesting test function.

class FixtureRequest

  The type of the `request` fixture.

  A request object gives access to the requesting test context and has a `param` attribute in case the fixture is parametrized.

  fixturename: Final

    Fixture for which this request is being performed.

  property scope: Literal['session', 'package', 'module', 'class', 'function']

    Scope string, one of "function", "class", "module", "package", "session".

  property fixturenames: list[str]

    Names of all active fixtures in this request.

  abstract property node

    Underlying collection node (depends on current request scope).

  property config: Config

    The pytest config object associated with this request.

  property function

    Test function object if the request has a per-function scope.

  property cls

    Class (can be None) where the test function was collected.

  property instance

    Instance (can be None) on which test function was collected.

  property module

    Python module object where the test function was collected.

  property path: Path

    Path where the test function was collected.

  property keywords: MutableMapping[str, Any]

    Keywords/markers dictionary for the underlying node.

  property session: Session

    Pytest session object.

  abstractmethod addfinalizer(finalizer)

    Add finalizer/teardown function to be called without arguments after the last test within the requesting test context finished execution.

  applymarker(marker)

    Apply a marker to a single test function invocation.

    This method is useful if you don't want to have a keyword/marker on all function invocations.

    Parameters:

      marker (str | MarkDecorator) -- An object created by a call to `pytest.mark.NAME(...)`.

  raiseerror(msg)

    Raise a FixtureLookupError exception.

    Parameters:

      msg (str | None) -- An optional custom error message.

  getfixturevalue(argname)

    Dynamically run a named fixture function.

    Declaring fixtures via function argument is recommended where possible. But if you can only decide whether to use another fixture at test setup time, you may use this function to retrieve it inside a fixture or test function body.

    This method can be used during the test setup phase or the test run phase, but during the test teardown phase a fixture's value may not be available.

    Parameters:

      argname (str) -- The fixture name.

    Raises:

      pytest.FixtureLookupError -- If the given fixture could not be found.

### subtests

The `subtests` fixture enables declaring subtests inside test functions.

Tutorial: How to use subtests

class Subtests

  Subtests fixture, enables declaring subtests inside test functions via the `test()` method.

  test(msg=None, **kwargs)

    Context manager for subtests, capturing exceptions raised inside the subtest scope and reporting assertion failures and errors individually.

    #### Usage

        def test(subtests):
            for i in range(5):
                with subtests.test("custom message", i=i):
                    assert i % 2 == 0

    param msg:

      If given, the message will be shown in the test report in case of subtest failure.

    param kwargs:

      Arbitrary values that are also added to the subtest report.

### testdir

Identical to `pytester`, but provides an instance whose methods return legacy `py.path.local` objects instead when applicable.

New code should avoid using `testdir` in favor of `pytester`.

final class Testdir

  Similar to `Pytester`, but this class works with legacy legacy_path objects instead.

  All methods just forward to an internal `Pytester` instance, converting results to `legacy_path` objects as necessary.

  exception TimeoutExpired
  property tmpdir: LocalPath

    Temporary directory where tests are executed.

  make_hook_recorder(pluginmanager)

    See `Pytester.make_hook_recorder()`.

  chdir()

    See `Pytester.chdir()`.

  makefile(ext, *args, **kwargs)

    See `Pytester.makefile()`.

  makeconftest(source)

    See `Pytester.makeconftest()`.

  makeini(source)

    See `Pytester.makeini()`.

  getinicfg(source)

    See `Pytester.getinicfg()`.

  makepyprojecttoml(source)

    See `Pytester.makepyprojecttoml()`.

  makepyfile(*args, **kwargs)

    See `Pytester.makepyfile()`.

  maketxtfile(*args, **kwargs)

    See `Pytester.maketxtfile()`.

  syspathinsert(path=None)

    See `Pytester.syspathinsert()`.

  mkdir(name)

    See `Pytester.mkdir()`.

  mkpydir(name)

    See `Pytester.mkpydir()`.

  copy_example(name=None)

    See `Pytester.copy_example()`.

  getnode(config, arg)

    See `Pytester.getnode()`.

  getpathnode(path)

    See `Pytester.getpathnode()`.

  genitems(colitems)

    See `Pytester.genitems()`.

  runitem(source)

    See `Pytester.runitem()`.

  inline_runsource(source, *cmdlineargs)

    See `Pytester.inline_runsource()`.

  inline_genitems(*args)

    See `Pytester.inline_genitems()`.

  inline_run(*args, plugins=(), no_reraise_ctrlc=False)

    See `Pytester.inline_run()`.

  runpytest_inprocess(*args, **kwargs)

    See `Pytester.runpytest_inprocess()`.

  runpytest(*args, **kwargs)

    See `Pytester.runpytest()`.

  parseconfig(*args)

    See `Pytester.parseconfig()`.

  parseconfigure(*args)

    See `Pytester.parseconfigure()`.

  getitem(source, funcname='test_func')

    See `Pytester.getitem()`.

  getitems(source)

    See `Pytester.getitems()`.

  getmodulecol(source, configargs=(), withinit=False)

    See `Pytester.getmodulecol()`.

  collect_by_name(modcol, name)

    See `Pytester.collect_by_name()`.

  popen(cmdargs, stdout=-1, stderr=-1, stdin=NotSetType.token, **kw)

    See `Pytester.popen()`.

  run(*cmdargs, timeout=None, stdin=NotSetType.token)

    See `Pytester.run()`.

  runpython(script)

    See `Pytester.runpython()`.

  runpython_c(command)

    See `Pytester.runpython_c()`.

  runpytest_subprocess(*args, timeout=None)

    See `Pytester.runpytest_subprocess()`.

  spawn_pytest(string, expect_timeout=10.0)

    See `Pytester.spawn_pytest()`.

  spawn(cmd, expect_timeout=10.0)

    See `Pytester.spawn()`.

### tmp_path

Tutorial: How to use temporary directories and files in tests

### tmp_path_factory

Tutorial: The tmp_path_factory fixture

`tmp_path_factory` is an instance of `TempPathFactory`:

final class TempPathFactory

  Factory for temporary directories under the common base temp directory, as discussed at Temporary directory location and retention.

  mktemp(basename, numbered=True)

    Create a new temporary directory managed by the factory.

    Parameters:

      - basename (str) -- Directory base name, must be a relative path.

      - numbered (bool) -- If `True`, ensure the directory is unique by adding a numbered suffix greater than any existing one: `basename="foo-"` and `numbered=True` means that this function will create directories named `"foo-0"`, `"foo-1"`, `"foo-2"` and so on.

    Returns:

      The path to the new directory.

    Return type:

      Path

  getbasetemp()

    Return the base temporary directory, creating it if needed.

    Returns:

      The base temporary directory.

    Return type:

      Path

### tmpdir

Tutorial: The tmpdir and tmpdir_factory fixtures

### tmpdir_factory

Tutorial: The tmpdir and tmpdir_factory fixtures

`tmpdir_factory` is an instance of `TempdirFactory`:

final class TempdirFactory

  Backward compatibility wrapper that implements `py.path.local` for `TempPathFactory`.

  Note

  These days, it is preferred to use `tmp_path_factory`.

  About the tmpdir and tmpdir_factory fixtures.

  mktemp(basename, numbered=True)

    Same as `TempPathFactory.mktemp()`, but returns a `py.path.local` object.

  getbasetemp()

    Same as `TempPathFactory.getbasetemp()`, but returns a `py.path.local` object.

## Hooks

Tutorial: Writing plugins

Reference to all hooks which can be implemented by conftest.py files and plugins.

### @pytest.hookimpl

### @pytest.hookspec

### Bootstrapping hooks

Bootstrapping hooks called for plugins registered early enough (internal and third-party plugins).

pytest_load_initial_conftests(early_config, parser, args)

  Called to implement the loading of initial conftest files ahead of command line option parsing.

  Parameters:

    - early_config (Config) -- The pytest config object.

    - args (list[str]) -- Arguments passed on the command line.

    - parser (Parser) -- To add command line options.

  #### Use in conftest plugins

  This hook is not called for conftest files.

pytest_cmdline_parse(pluginmanager, args)

  Return an initialized `Config`, parsing the specified args.

  Stops at first non-None result, see firstresult: stop at first non-None result.

  Note

  This hook is only called for plugin classes passed to the `plugins` arg when using pytest.main to perform an in-process test run.

  Parameters:

    - pluginmanager (PytestPluginManager) -- The pytest plugin manager.

    - args (list[str]) -- List of arguments passed on the command line.

  Returns:

    A pytest config object.

  Return type:

    Config | None

  #### Use in conftest plugins

  This hook is not called for conftest files.

pytest_cmdline_main(config)

  Called for performing the main command line action.

  The default implementation will invoke the configure hooks and `pytest_runtestloop`.

  Stops at first non-None result, see firstresult: stop at first non-None result.

  Parameters:

    config (Config) -- The pytest config object.

  Returns:

    The exit code.

  Return type:

    ExitCode | int | None

  #### Use in conftest plugins

  This hook is only called for initial conftests.

### Initialization hooks

Initialization hooks called for plugins and `conftest.py` files.

pytest_addoption(parser, pluginmanager)

  Register argparse-style options and config-style config values, called once at the beginning of a test run.

  Parameters:

    - parser (Parser) -- To add command line options, call `parser.addoption(...)`. To add config-file values call `parser.addini(...)`.

    - pluginmanager (PytestPluginManager) -- The pytest plugin manager, which can be used to install `hookspec()`'s or `hookimpl()`'s and allow one plugin to call another plugin's hooks to change how command line options are added.

  Options can later be accessed through the `config` object, respectively:

  - `config.getoption(name)` to retrieve the value of a command line option.

  - `config.getini(name)` to retrieve a value read from a configuration file.

  The config object is passed around on many internal objects via the `.config` attribute or can be retrieved as the `pytestconfig` fixture.

  Note

  This hook is incompatible with hook wrappers.

  #### Use in conftest plugins

  If a conftest plugin implements this hook, it will be called immediately when the conftest is registered.

  This hook is only called for initial conftests.

pytest_addhooks(pluginmanager)

  Called at plugin registration time to allow adding new hooks via a call to `pluginmanager.add_hookspecs(module_or_class, prefix)`.

  Parameters:

    pluginmanager (PytestPluginManager) -- The pytest plugin manager.

  Note

  This hook is incompatible with hook wrappers.

  #### Use in conftest plugins

  If a conftest plugin implements this hook, it will be called immediately when the conftest is registered.

pytest_configure(config)

  Allow plugins and conftest files to perform initial configuration.

  Note

  This hook is incompatible with hook wrappers.

  Parameters:

    config (Config) -- The pytest config object.

  #### Use in conftest plugins

  This hook is called for every initial conftest file after command line options have been parsed. After that, the hook is called for other conftest files as they are registered.

pytest_unconfigure(config)

  Called before test process is exited.

  Parameters:

    config (Config) -- The pytest config object.

  #### Use in conftest plugins

  Any conftest file can implement this hook.

pytest_sessionstart(session)

  Called after the `Session` object has been created and before performing collection and entering the run test loop.

  Parameters:

    session (Session) -- The pytest session object.

  #### Use in conftest plugins

  This hook is only called for initial conftests.

pytest_sessionfinish(session, exitstatus)

  Called after whole test run finished, right before returning the exit status to the system.

  Parameters:

    - session (Session) -- The pytest session object.

    - exitstatus (int | ExitCode) -- The status which pytest will return to the system.

  #### Use in conftest plugins

  Any conftest file can implement this hook.

pytest_plugin_registered(plugin, plugin_name, manager)

  A new pytest plugin got registered.

  Parameters:

    - plugin (_PluggyPlugin) -- The plugin module or instance.

    - plugin_name (str) -- The name by which the plugin is registered.

    - manager (PytestPluginManager) -- The pytest plugin manager.

  Note

  This hook is incompatible with hook wrappers.

  #### Use in conftest plugins

  If a conftest plugin implements this hook, it will be called immediately when the conftest is registered, once for each plugin registered thus far (including itself!), and for all plugins thereafter when they are registered.

### Collection hooks

`pytest` calls the following hooks for collecting files and directories:

pytest_collection(session)

  Perform the collection phase for the given session.

  Stops at first non-None result, see firstresult: stop at first non-None result. The return value is not used, but only stops further processing.

  The default collection phase is this (see individual hooks for full details):

  1. Starting from `session` as the initial collector:

  > 1. `pytest_collectstart(collector)`

  > 2. `report = pytest_make_collect_report(collector)`

  > 3. `pytest_exception_interact(collector, call, report)` if an interactive exception occurred

  > 4. For each collected node:

  > > 1. If an item, `pytest_itemcollected(item)`

  > > 2. If a collector, recurse into it.

  > 5. `pytest_collectreport(report)`

  2. `pytest_collection_modifyitems(session, config, items)`

  > 1. `pytest_deselected(items)` for any deselected items (may be called multiple times)

  3. `pytest_collection_finish(session)`

  4. Set `session.items` to the list of collected items

  5. Set `session.testscollected` to the number of collected items

  You can implement this hook to only perform some action before collection, for example the terminal plugin uses it to start displaying the collection counter (and returns `None`).

  Parameters:

    session (Session) -- The pytest session object.

  #### Use in conftest plugins

  This hook is only called for initial conftests.

pytest_ignore_collect(collection_path, path, config)

  Return `True` to ignore this path for collection.

  Return `None` to let other plugins ignore the path for collection.

  Returning `False` will forcefully not ignore this path for collection, without giving a chance for other plugins to ignore this path.

  This hook is consulted for all files and directories prior to calling more specific hooks.

  Stops at first non-None result, see firstresult: stop at first non-None result.

  Parameters:

    - collection_path (pathlib.Path) -- The path to analyze.

    - path (LEGACY_PATH) -- The path to analyze (deprecated).

    - config (Config) -- The pytest config object.

  Changed in version 7.0.0: The `collection_path` parameter was added as a `pathlib.Path` equivalent of the `path` parameter. The `path` parameter has been deprecated.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given collection path, only conftest files in parent directories of the collection path are consulted (if the path is a directory, its own conftest file is not consulted - a directory cannot ignore itself!).

pytest_collect_directory(path, parent)

  Create a `Collector` for the given directory, or None if not relevant.

  Added in version 8.0.

  For best results, the returned collector should be a subclass of `Directory`, but this is not required.

  The new node needs to have the specified `parent` as a parent.

  Stops at first non-None result, see firstresult: stop at first non-None result.

  Parameters:

    path (pathlib.Path) -- The path to analyze.

  See Using a custom directory collector for a simple example of use of this hook.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given collection path, only conftest files in parent directories of the collection path are consulted (if the path is a directory, its own conftest file is not consulted - a directory cannot collect itself!).

pytest_collect_file(file_path, path, parent)

  Create a `Collector` for the given path, or None if not relevant.

  For best results, the returned collector should be a subclass of `File`, but this is not required.

  The new node needs to have the specified `parent` as a parent.

  Parameters:

    - file_path (pathlib.Path) -- The path to analyze.

    - path (LEGACY_PATH) -- The path to collect (deprecated).

  Changed in version 7.0.0: The `file_path` parameter was added as a `pathlib.Path` equivalent of the `path` parameter. The `path` parameter has been deprecated.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given file path, only conftest files in parent directories of the file path are consulted.

pytest_pycollect_makemodule(module_path, path, parent)

  Return a `pytest.Module` collector or None for the given path.

  This hook will be called for each matching test module path. The `pytest_collect_file` hook needs to be used if you want to create test modules for files that do not match as a test module.

  Stops at first non-None result, see firstresult: stop at first non-None result.

  Parameters:

    - module_path (pathlib.Path) -- The path of the module to collect.

    - path (LEGACY_PATH) -- The path of the module to collect (deprecated).

  Changed in version 7.0.0: The `module_path` parameter was added as a `pathlib.Path` equivalent of the `path` parameter.

  The `path` parameter has been deprecated in favor of `fspath`.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given parent collector, only conftest files in the collector's directory and its parent directories are consulted.

For influencing the collection of objects in Python modules you can use the following hook:

pytest_pycollect_makeitem(collector, name, obj)

  Return a custom item/collector for a Python object in a module, or None.

  Stops at first non-None result, see firstresult: stop at first non-None result.

  Parameters:

    - collector (Module | Class) -- The module/class collector.

    - name (str) -- The name of the object in the module/class.

    - obj (object) -- The object.

  Returns:

    The created items/collectors.

  Return type:

    None | Item | Collector | list[Item | Collector]

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given collector, only conftest files in the collector's directory and its parent directories are consulted.

pytest_generate_tests(metafunc)

  Generate (multiple) parametrized calls to a test function.

  Parameters:

    metafunc (Metafunc) -- The `Metafunc` helper for the test function.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given function definition, only conftest files in the functions's directory and its parent directories are consulted.

pytest_make_parametrize_id(config, val, argname)

  Return a user-friendly string representation of the given `val` that will be used by @pytest.mark.parametrize calls, or None if the hook doesn't know about `val`.

  The parameter name is available as `argname`, if required.

  Stops at first non-None result, see firstresult: stop at first non-None result.

  Parameters:

    - config (Config) -- The pytest config object.

    - val (object) -- The parametrized value.

    - argname (str) -- The automatic parameter name produced by pytest.

  #### Use in conftest plugins

  Any conftest file can implement this hook.

Hooks for influencing test skipping:

pytest_markeval_namespace(config)

  Called when constructing the globals dictionary used for evaluating string conditions in xfail/skipif markers.

  This is useful when the condition for a marker requires objects that are expensive or impossible to obtain during collection time, which is required by normal boolean conditions.

  Added in version 6.2.

  Parameters:

    config (Config) -- The pytest config object.

  Returns:

    A dictionary of additional globals to add.

  Return type:

    dict[str, Any]

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in parent directories of the item are consulted.

After collection is complete, you can modify the order of items, delete or otherwise amend the test items:

pytest_collection_modifyitems(session, config, items)

  Called after collection has been performed. May filter or re-order the items in-place.

  When items are deselected (filtered out from `items`), the hook `pytest_deselected` must be called explicitly with the deselected items to properly notify other plugins, e.g. with `config.hook.pytest_deselected(items=deselected_items)`.

  Parameters:

    - session (Session) -- The pytest session object.

    - config (Config) -- The pytest config object.

    - items (list[Item]) -- List of item objects.

  #### Use in conftest plugins

  Any conftest plugin can implement this hook.

Note

If this hook is implemented in `conftest.py` files, it always receives all collected items, not only those under the `conftest.py` where it is implemented.

pytest_collection_finish(session)

  Called after collection has been performed and modified.

  Parameters:

    session (Session) -- The pytest session object.

  #### Use in conftest plugins

  Any conftest plugin can implement this hook.

### Test running (runtest) hooks

All runtest related hooks receive a `pytest.Item` object.

pytest_runtestloop(session)

  Perform the main runtest loop (after collection finished).

  The default hook implementation performs the runtest protocol for all items collected in the session (`session.items`), unless the collection failed or the `collectonly` pytest option is set.

  If at any point `pytest.exit()` is called, the loop is terminated immediately.

  If at any point `session.shouldfail` or `session.shouldstop` are set, the loop is terminated after the runtest protocol for the current item is finished.

  Parameters:

    session (Session) -- The pytest session object.

  Stops at first non-None result, see firstresult: stop at first non-None result. The return value is not used, but only stops further processing.

  #### Use in conftest plugins

  Any conftest file can implement this hook.

pytest_runtest_protocol(item, nextitem)

  Perform the runtest protocol for a single test item.

  The default runtest protocol is this (see individual hooks for full details):

  - `pytest_runtest_logstart(nodeid, location)`

  - Setup phase:

      - `call = pytest_runtest_setup(item)` (wrapped in `CallInfo(when="setup")`)

      - `report = pytest_runtest_makereport(item, call)`

      - `pytest_runtest_logreport(report)`

      - `pytest_exception_interact(call, report)` if an interactive exception occurred

  - Call phase, if the setup passed and the `setuponly` pytest option is not set:

      - `call = pytest_runtest_call(item)` (wrapped in `CallInfo(when="call")`)

      - `report = pytest_runtest_makereport(item, call)`

      - `pytest_runtest_logreport(report)`

      - `pytest_exception_interact(call, report)` if an interactive exception occurred

  - Teardown phase:

      - `call = pytest_runtest_teardown(item, nextitem)` (wrapped in `CallInfo(when="teardown")`)

      - `report = pytest_runtest_makereport(item, call)`

      - `pytest_runtest_logreport(report)`

      - `pytest_exception_interact(call, report)` if an interactive exception occurred

  - `pytest_runtest_logfinish(nodeid, location)`

  Parameters:

    - item (Item) -- Test item for which the runtest protocol is performed.

    - nextitem (Item | None) -- The scheduled-to-be-next test item (or None if this is the end my friend).

  Stops at first non-None result, see firstresult: stop at first non-None result. The return value is not used, but only stops further processing.

  #### Use in conftest plugins

  Any conftest file can implement this hook.

pytest_runtest_logstart(nodeid, location)

  Called at the start of running the runtest protocol for a single item.

  See `pytest_runtest_protocol` for a description of the runtest protocol.

  Parameters:

    - nodeid (str) -- Full node ID of the item.

    - location (tuple[str, int | None, str]) -- A tuple of `(filename, lineno, testname)` where `filename` is a file path relative to `config.rootpath` and `lineno` is 0-based.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in the item's directory and its parent directories are consulted.

pytest_runtest_logfinish(nodeid, location)

  Called at the end of running the runtest protocol for a single item.

  See `pytest_runtest_protocol` for a description of the runtest protocol.

  Parameters:

    - nodeid (str) -- Full node ID of the item.

    - location (tuple[str, int | None, str]) -- A tuple of `(filename, lineno, testname)` where `filename` is a file path relative to `config.rootpath` and `lineno` is 0-based.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in the item's directory and its parent directories are consulted.

pytest_runtest_setup(item)

  Called to perform the setup phase for a test item.

  The default implementation runs `setup()` on `item` and all of its parents (which haven't been setup yet). This includes obtaining the values of fixtures required by the item (which haven't been obtained yet).

  Parameters:

    item (Item) -- The item.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in the item's directory and its parent directories are consulted.

pytest_runtest_call(item)

  Called to run the test for test item (the call phase).

  The default implementation calls `item.runtest()`.

  Parameters:

    item (Item) -- The item.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in the item's directory and its parent directories are consulted.

pytest_runtest_teardown(item, nextitem)

  Called to perform the teardown phase for a test item.

  The default implementation runs the finalizers and calls `teardown()` on `item` and all of its parents (which need to be torn down). This includes running the teardown phase of fixtures required by the item (if they go out of scope).

  Parameters:

    - item (Item) -- The item.

    - nextitem (Item | None) -- The scheduled-to-be-next test item (None if no further test item is scheduled). This argument is used to perform exact teardowns, i.e. calling just enough finalizers so that nextitem only needs to call setup functions.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in the item's directory and its parent directories are consulted.

pytest_runtest_makereport(item, call)

  Called to create a `TestReport` for each of the setup, call and teardown runtest phases of a test item.

  See `pytest_runtest_protocol` for a description of the runtest protocol.

  Parameters:

    - item (Item) -- The item.

    - call (CallInfo[None]) -- The `CallInfo` for the phase.

  Stops at first non-None result, see firstresult: stop at first non-None result.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in the item's directory and its parent directories are consulted.

For deeper understanding you may look at the default implementation of these hooks in `_pytest.runner` and maybe also in `_pytest.pdb` which interacts with `_pytest.capture` and its input/output capturing in order to immediately drop into interactive debugging when a test failure occurs.

pytest_pyfunc_call(pyfuncitem)

  Call underlying test function.

  Stops at first non-None result, see firstresult: stop at first non-None result.

  Parameters:

    pyfuncitem (Function) -- The function item.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in the item's directory and its parent directories are consulted.

### Reporting hooks

Session related reporting hooks:

pytest_collectstart(collector)

  Collector starts collecting.

  Parameters:

    collector (Collector) -- The collector.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given collector, only conftest files in the collector's directory and its parent directories are consulted.

pytest_make_collect_report(collector)

  Perform `collector.collect()` and return a `CollectReport`.

  Stops at first non-None result, see firstresult: stop at first non-None result.

  Parameters:

    collector (Collector) -- The collector.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given collector, only conftest files in the collector's directory and its parent directories are consulted.

pytest_itemcollected(item)

  We just collected a test item.

  Parameters:

    item (Item) -- The item.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in the item's directory and its parent directories are consulted.

pytest_collectreport(report)

  Collector finished collecting.

  Parameters:

    report (CollectReport) -- The collect report.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given collector, only conftest files in the collector's directory and its parent directories are consulted.

pytest_deselected(items)

  Called for deselected test items, e.g. by keyword.

  Note that this hook has two integration aspects for plugins:

  - it can be implemented to be notified of deselected items

  - it must be called from `pytest_collection_modifyitems` implementations when items are deselected (to properly notify other plugins).

  May be called multiple times.

  Parameters:

    items (Sequence[Item]) -- The items.

  #### Use in conftest plugins

  Any conftest file can implement this hook.

pytest_report_header(config, start_path, startdir)

  Return a string or list of strings to be displayed as header info for terminal reporting.

  Parameters:

    - config (Config) -- The pytest config object.

    - start_path (pathlib.Path) -- The starting dir.

    - startdir (LEGACY_PATH) -- The starting dir (deprecated).

  Note

  Lines returned by a plugin are displayed before those of plugins which ran before it. If you want to have your line(s) displayed first, use trylast=True.

  Changed in version 7.0.0: The `start_path` parameter was added as a `pathlib.Path` equivalent of the `startdir` parameter. The `startdir` parameter has been deprecated.

  #### Use in conftest plugins

  This hook is only called for initial conftests.

pytest_report_collectionfinish(config, start_path, startdir, items)

  Return a string or list of strings to be displayed after collection has finished successfully.

  These strings will be displayed after the standard "collected X items" message.

  Added in version 3.2.

  Parameters:

    - config (Config) -- The pytest config object.

    - start_path (pathlib.Path) -- The starting dir.

    - startdir (LEGACY_PATH) -- The starting dir (deprecated).

    - items (Sequence[Item]) -- List of pytest items that are going to be executed; this list should not be modified.

  Note

  Lines returned by a plugin are displayed before those of plugins which ran before it. If you want to have your line(s) displayed first, use trylast=True.

  Changed in version 7.0.0: The `start_path` parameter was added as a `pathlib.Path` equivalent of the `startdir` parameter. The `startdir` parameter has been deprecated.

  #### Use in conftest plugins

  Any conftest plugin can implement this hook.

pytest_report_teststatus(report, config)

  Return result-category, shortletter and verbose word for status reporting.

  The result-category is a category in which to count the result, for example "passed", "skipped", "error" or the empty string.

  The shortletter is shown as testing progresses, for example ".", "s", "E" or the empty string.

  The verbose word is shown as testing progresses in verbose mode, for example "PASSED", "SKIPPED", "ERROR" or the empty string.

  pytest may style these implicitly according to the report outcome. To provide explicit styling, return a tuple for the verbose word, for example `"rerun", "R", ("RERUN", {"yellow": True})`.

  Parameters:

    - report (CollectReport | TestReport) -- The report object whose status is to be returned.

    - config (Config) -- The pytest config object.

  Returns:

    The test status.

  Return type:

    TestShortLogReport | tuple[str, str, str | tuple[str, Mapping[str, bool]]]

  Stops at first non-None result, see firstresult: stop at first non-None result.

  #### Use in conftest plugins

  Any conftest plugin can implement this hook.

pytest_report_to_serializable(config, report)

  Serialize the given report object into a data structure suitable for sending over the wire, e.g. converted to JSON.

  Parameters:

    - config (Config) -- The pytest config object.

    - report (CollectReport | TestReport) -- The report.

  #### Use in conftest plugins

  Any conftest file can implement this hook. The exact details may depend on the plugin which calls the hook.

pytest_report_from_serializable(config, data)

  Restore a report object previously serialized with `pytest_report_to_serializable`.

  Parameters:

    config (Config) -- The pytest config object.

  #### Use in conftest plugins

  Any conftest file can implement this hook. The exact details may depend on the plugin which calls the hook.

pytest_terminal_summary(terminalreporter, exitstatus, config)

  Add a section to terminal summary reporting.

  Parameters:

    - terminalreporter (TerminalReporter) -- The internal terminal reporter object.

    - exitstatus (ExitCode) -- The exit status that will be reported back to the OS.

    - config (Config) -- The pytest config object.

  Added in version 4.2: The `config` parameter.

  #### Use in conftest plugins

  Any conftest plugin can implement this hook.

pytest_fixture_setup(fixturedef, request)

  Perform fixture setup execution.

  Parameters:

    - fixturedef (FixtureDef[Any]) -- The fixture definition object.

    - request (SubRequest) -- The fixture request object.

  Returns:

    The return value of the call to the fixture function.

  Return type:

    object | None

  Stops at first non-None result, see firstresult: stop at first non-None result.

  Note

  If the fixture function returns None, other implementations of this hook function will continue to be called, according to the behavior of the firstresult: stop at first non-None result option.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given fixture, only conftest files in the fixture scope's directory and its parent directories are consulted.

pytest_fixture_post_finalizer(fixturedef, request)

  Called after fixture teardown, but before the cache is cleared, so the fixture result `fixturedef.cached_result` is still available (not `None`).

  Parameters:

    - fixturedef (FixtureDef[Any]) -- The fixture definition object.

    - request (SubRequest) -- The fixture request object.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given fixture, only conftest files in the fixture scope's directory and its parent directories are consulted.

pytest_warning_recorded(warning_message, when, nodeid, location)

  Process a warning captured by the internal pytest warnings plugin.

  Parameters:

    - warning_message (warnings.WarningMessage) -- The captured warning. This is the same object produced by `warnings.catch_warnings`, and contains the same attributes as the parameters of `warnings.showwarning()`.

    - when (Literal['config', 'collect', 'runtest']) --

      Indicates when the warning was captured. Possible values:

      - `"config"`: during pytest configuration/initialization stage.

      - `"collect"`: during test collection.

      - `"runtest"`: during test execution.

    - nodeid (str) -- Full id of the item. Empty string for warnings that are not specific to a particular node.

    - location (tuple[str, int, str] | None) -- When available, holds information about the execution context of the captured warning (filename, linenumber, function). `function` evaluates to <module> when the execution context is at the module level.

  Added in version 6.0.

  #### Use in conftest plugins

  Any conftest file can implement this hook. If the warning is specific to a particular node, only conftest files in parent directories of the node are consulted.

Central hook for reporting about test execution:

pytest_runtest_logreport(report)

  Process the `TestReport` produced for each of the setup, call and teardown runtest phases of an item.

  See `pytest_runtest_protocol` for a description of the runtest protocol.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in the item's directory and its parent directories are consulted.

Assertion related hooks:

pytest_assertrepr_compare(config, op, left, right)

  Return explanation for comparisons in failing assert expressions.

  Return None for no custom explanation, otherwise return a list of strings. The strings will be joined by newlines but any newlines in a string will be escaped. Note that all but the first line will be indented slightly, the intention is for the first line to be a summary.

  Parameters:

    - config (Config) -- The pytest config object.

    - op (str) -- The operator, e.g. `"=="`, `"!="`, `"not in"`.

    - left (object) -- The left operand.

    - right (object) -- The right operand.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in the item's directory and its parent directories are consulted.

pytest_assertion_pass(item, lineno, orig, expl)

  Called whenever an assertion passes.

  Added in version 5.0.

  Use this hook to do some processing after a passing assertion. The original assertion information is available in the `orig` string and the pytest introspected assertion information is available in the `expl` string.

  This hook must be explicitly enabled by the `enable_assertion_pass_hook` configuration option:

  toml

      [pytest]
      enable_assertion_pass_hook = true

  ini

      [pytest]
      enable_assertion_pass_hook = true

  You need to clean the .pyc files in your project directory and interpreter libraries when enabling this option, as assertions will require to be re-written.

  Parameters:

    - item (Item) -- pytest item object of current test.

    - lineno (int) -- Line number of the assert statement.

    - orig (str) -- String with the original assertion.

    - expl (str) -- String with the assert explanation.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given item, only conftest files in the item's directory and its parent directories are consulted.

### Debugging/Interaction hooks

There are few hooks which can be used for special reporting or interaction with exceptions:

pytest_internalerror(excrepr, excinfo)

  Called for internal errors.

  Return True to suppress the fallback handling of printing an INTERNALERROR message directly to sys.stderr.

  Parameters:

    - excrepr (ExceptionRepr) -- The exception repr object.

    - excinfo (ExceptionInfo[BaseException]) -- The exception info.

  #### Use in conftest plugins

  Any conftest plugin can implement this hook.

pytest_keyboard_interrupt(excinfo)

  Called for keyboard interrupt.

  Parameters:

    excinfo (ExceptionInfo[KeyboardInterrupt | Exit]) -- The exception info.

  #### Use in conftest plugins

  Any conftest plugin can implement this hook.

pytest_exception_interact(node, call, report)

  Called when an exception was raised which can potentially be interactively handled.

  May be called during collection (see `pytest_make_collect_report`), in which case `report` is a `CollectReport`.

  May be called during runtest of an item (see `pytest_runtest_protocol`), in which case `report` is a `TestReport`.

  This hook is not called if the exception that was raised is an internal exception like `skip.Exception`.

  Parameters:

    - node (Item | Collector) -- The item or collector.

    - call (CallInfo[Any]) -- The call information. Contains the exception.

    - report (CollectReport | TestReport) -- The collection or test report.

  #### Use in conftest plugins

  Any conftest file can implement this hook. For a given node, only conftest files in parent directories of the node are consulted.

pytest_enter_pdb(config, pdb)

  Called upon pdb.set_trace().

  Can be used by plugins to take special action just before the python debugger enters interactive mode.

  Parameters:

    - config (Config) -- The pytest config object.

    - pdb (pdb.Pdb) -- The Pdb instance.

  #### Use in conftest plugins

  Any conftest plugin can implement this hook.

pytest_leave_pdb(config, pdb)

  Called when leaving pdb (e.g. with continue after pdb.set_trace()).

  Can be used by plugins to take special action just after the python debugger leaves interactive mode.

  Parameters:

    - config (Config) -- The pytest config object.

    - pdb (pdb.Pdb) -- The Pdb instance.

  #### Use in conftest plugins

  Any conftest plugin can implement this hook.

## Collection tree objects

These are the collector and item classes (collectively called "nodes") which make up the collection tree.

### Node

class Node

  Bases: `ABC`

  Base class of `Collector` and `Item`, the components of the test collection tree.

  `Collector`'s are the internal nodes of the tree, and `Item`'s are the leaf nodes.

  fspath: LEGACY_PATH

    A `LEGACY_PATH` copy of the `path` attribute. Intended for usage for methods not migrated to `pathlib.Path` yet, such as `Item.reportinfo`. Will be deprecated in a future release, prefer using `path` instead.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  config: Config

    The pytest config object.

  session: Session

    The pytest session this node is part of.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  keywords: MutableMapping[str, Any]

    Keywords/markers collected from all scopes.

  own_markers: list[Mark]

    The marker objects belonging to this node.

  extra_keyword_matches: set[str]

    Allow adding of extra keywords to use for matching.

  stash: Stash

    A place where plugins can store information on the node for their own use.

  classmethod from_parent(parent, **kw)

    Public constructor for Nodes.

    This indirection got introduced in order to enable removing the fragile logic from the node constructors.

    Subclasses can use `super().from_parent(...)` when overriding the construction.

    Parameters:

      parent (Node) -- The parent node of this Node.

  property ihook: HookRelay

    fspath-sensitive hook proxy used to call pytest hooks.

  warn(warning)

    Issue a warning for this Node.

    Warnings will be displayed after the test session, unless explicitly suppressed.

    Parameters:

      warning (Warning) -- The warning instance to issue.

    Raises:

      ValueError -- If `warning` instance is not a subclass of Warning.

    Example usage:

        node.warn(PytestWarning("some message"))
        node.warn(UserWarning("some message"))

    Changed in version 6.2: Any subclass of `Warning` is now accepted, rather than only `PytestWarning` subclasses.

  property nodeid: str

    A ::-separated string denoting its collection tree address.

  iter_parents()

    Iterate over all parent collectors starting from and including self up to the root of the collection tree.

    Added in version 8.1.

  listchain()

    Return a list of all parent collectors starting from the root of the collection tree down to and including self.

  add_marker(marker, append=True)

    Dynamically add a marker object to the node.

    Parameters:

      - marker (str | MarkDecorator) -- The marker.

      - append (bool) -- Whether to append the marker, or prepend it.

  iter_markers(name=None)

    Iterate over all markers of the node.

    Parameters:

      name (str | None) -- If given, filter the results by the name attribute.

    Returns:

      An iterator of the markers of the node.

    Return type:

      Iterator[Mark]

  iter_markers_with_node(name=None)

    Iterate over all markers of the node.

    Parameters:

      name (str | None) -- If given, filter the results by the name attribute.

    Returns:

      An iterator of (node, mark) tuples.

    Return type:

      Iterator[tuple[Node, Mark]]

  get_closest_marker(name: str) → Mark | None
  get_closest_marker(name: str, default: Mark) → Mark

    Return the first marker matching the name, from closest (for example function) to farther level (for example module level).

    Parameters:

      - default -- Fallback return value if no marker was found.

      - name -- Name to filter by.

  listextrakeywords()

    Return a set of all extra keywords in self and any parents.

  addfinalizer(fin)

    Register a function to be called without arguments when this node is finalized.

    This method can only be called when this node is active in a setup chain, for example during self.setup().

  getparent(cls)

    Get the closest parent node (including self) which is an instance of the given class.

    Parameters:

      cls (type[_NodeType]) -- The node class to search for.

    Returns:

      The node, if found.

    Return type:

      _NodeType | None

  repr_failure(excinfo, style=None)

    Return a representation of a collection or test failure.

    See also

    Working with non-python tests

    Parameters:

      excinfo (ExceptionInfo[BaseException]) -- Exception information for the failure.

### Collector

class Collector

  Bases: `Node`, `ABC`

  Base class of all collectors.

  Collector create children through `collect()` and thus iteratively build the collection tree.

  exception CollectError

    Bases: `Exception`

    An error during collection, contains a custom message.

  abstractmethod collect()

    Collect children (items and collectors) for this collector.

  repr_failure(excinfo)

    Return a representation of a collection failure.

    Parameters:

      excinfo (ExceptionInfo[BaseException]) -- Exception information for the failure.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  session: Session

    The pytest session this node is part of.

### Item

class Item

  Bases: `Node`, `ABC`

  Base class of all test invocation items.

  Note that for a single function there might be multiple test invocation items.

  user_properties: list[tuple[str, object]]

    A list of tuples (name, value) that holds user defined properties for this test.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  session: Session

    The pytest session this node is part of.

  abstractmethod runtest()

    Run the test case for this item.

    Must be implemented by subclasses.

    See also

    Working with non-python tests

  add_report_section(when, key, content)

    Add a new report section, similar to what's done internally to add stdout and stderr captured output:

        item.add_report_section("call", "stdout", "report section contents")

    Parameters:

      - when (str) -- One of the possible capture states, `"setup"`, `"call"`, `"teardown"`.

      - key (str) -- Name of the section, can be customized at will. Pytest uses `"stdout"` and `"stderr"` internally.

      - content (str) -- The full contents as a string.

  reportinfo()

    Get location information for this item for test reports.

    Returns a tuple with three elements:

    - The path of the test (default `self.path`)

    - The 0-based line number of the test (default `None`)

    - A name of the test to be shown (default `""`)

    See also

    Working with non-python tests

  property location: tuple[str, int | None, str]

    Returns a tuple of `(relfspath, lineno, testname)` for this item where `relfspath` is file path relative to `config.rootpath` and lineno is a 0-based line number.

### File

class File

  Bases: `FSCollector`, `ABC`

  Base class for collecting tests from a file.

  Working with non-python tests.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  session: Session

    The pytest session this node is part of.

### FSCollector

class FSCollector

  Bases: `Collector`, `ABC`

  Base class for filesystem collectors.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  classmethod from_parent(parent, *, fspath=None, path=None, **kw)

    The public constructor.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  session: Session

    The pytest session this node is part of.

### Session

final class Session

  Bases: `Collector`

  The root of the collection tree.

  `Session` collects the initial paths given as arguments to pytest.

  exception Interrupted

    Bases: `KeyboardInterrupt`

    Signals that the test run was interrupted.

  exception Failed

    Bases: `Exception`

    Signals a stop as failed test run.

  property startpath: Path

    The path from which pytest was invoked.

    Added in version 7.0.0.

  isinitpath(path, *, with_parents=False)

    Is path an initial path?

    An initial path is a path explicitly given to pytest on the command line.

    Parameters:

      with_parents (bool) -- If set, also return True if the path is a parent of an initial path.

    Changed in version 8.0: Added the `with_parents` parameter.

  perform_collect(args: Sequence[str] | None = None, genitems: Literal[True] = True) → Sequence[Item]
  perform_collect(args: Sequence[str] | None = None, genitems: bool = True) → Sequence[Item | Collector]

    Perform the collection phase for this session.

    This is called by the default `pytest_collection` hook implementation; see the documentation of this hook for more details. For testing purposes, it may also be called directly on a fresh `Session`.

    This function normally recursively expands any collectors collected from the session to their items, and only items are returned. For testing purposes, this may be suppressed by passing `genitems=False`, in which case the return value contains these collectors unexpanded, and `session.items` is empty.

  collect()

    Collect children (items and collectors) for this collector.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  session: Session

    The pytest session this node is part of.

### Package

class Package

  Bases: `Directory`

  Collector for files and directories in a Python packages -- directories with an `__init__.py` file.

  Note

  Directories without an `__init__.py` file are instead collected by `Dir` by default. Both are `Directory` collectors.

  Changed in version 8.0: Now inherits from `Directory`.

  collect()

    Collect children (items and collectors) for this collector.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  session: Session

    The pytest session this node is part of.

### Module

class Module

  Bases: `File`, `PyCollector`

  Collector for test classes and functions in a Python module.

  collect()

    Collect children (items and collectors) for this collector.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  session: Session

    The pytest session this node is part of.

### Class

class Class

  Bases: `PyCollector`

  Collector for test methods (and nested classes) in a Python class.

  classmethod from_parent(parent, *, name, obj=None, **kw)

    The public constructor.

  collect()

    Collect children (items and collectors) for this collector.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  session: Session

    The pytest session this node is part of.

### Function

class Function

  Bases: `PyobjMixin`, `Item`

  Item responsible for setting up and executing a Python test function.

  Parameters:

    - name -- The full function name, including any decorations like those added by parametrization (`my_func[my_param]`).

    - parent -- The parent Node.

    - config -- The pytest Config object.

    - callspec -- If given, this function has been parametrized and the callspec contains meta information about the parametrization.

    - callobj -- If given, the object which will be called when the Function is invoked, otherwise the callobj will be obtained from `parent` using `originalname`.

    - keywords -- Keywords bound to the function object for "-k" matching.

    - session -- The pytest Session object.

    - fixtureinfo -- Fixture information already resolved at this fixture node..

    - originalname -- The attribute name to use for accessing the underlying function object. Defaults to `name`. Set this if name is different from the original name, for example when it contains decorations like those added by parametrization (`my_func[my_param]`).

  originalname

    Original function name, without any decorations (for example parametrization adds a `"[...]"` suffix to function names), used to access the underlying function object from `parent` (in case `callobj` is not given explicitly).

    Added in version 3.0.

  classmethod from_parent(parent, **kw)

    The public constructor.

  property function

    Underlying python 'function' object.

  property instance

    Python instance object the function is bound to.

    Returns None if not a test method, e.g. for a standalone test function, a class or a module.

  runtest()

    Execute the underlying test function.

  repr_failure(excinfo)

    Return a representation of a collection or test failure.

    See also

    Working with non-python tests

    Parameters:

      excinfo (ExceptionInfo[BaseException]) -- Exception information for the failure.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  session: Session

    The pytest session this node is part of.

### FunctionDefinition

class FunctionDefinition

  Bases: `Function`

  This class is a stop gap solution until we evolve to have actual function definition nodes and manage to get rid of `metafunc`.

  runtest()

    Execute the underlying test function.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  session: Session

    The pytest session this node is part of.

  setup()

    Execute the underlying test function.

## Objects

Objects accessible from fixtures or hooks or importable from `pytest`.

### CallInfo

final class CallInfo

  Result/Exception info of a function invocation.

  excinfo: ExceptionInfo[BaseException] | None

    The captured exception of the call, if it raised.

  start: float

    The system time when the call started, in seconds since the epoch.

  stop: float

    The system time when the call ended, in seconds since the epoch.

  duration: float

    The call duration, in seconds.

  when: Literal['collect', 'setup', 'call', 'teardown']

    The context of invocation: "collect", "setup", "call" or "teardown".

  property result: TResult

    The return value of the call, if it didn't raise.

    Can only be accessed if excinfo is None.

  classmethod from_call(func, when, reraise=None)

    Call func, wrapping the result in a CallInfo.

    Parameters:

      - func (Callable[[], _pytest.runner.TResult]) -- The function to call. Called without arguments.

      - when (Literal['collect', 'setup', 'call', 'teardown']) -- The phase in which the function is called.

      - reraise (type[BaseException] | tuple[type[BaseException], ...] | None) -- Exception or exceptions that shall propagate if raised by the function, instead of being wrapped in the CallInfo.

### CollectReport

final class CollectReport

  Bases: `BaseReport`

  Collection report object.

  Reports can contain arbitrary extra attributes.

  nodeid: str

    Normalized collection nodeid.

  outcome: Literal['passed', 'failed', 'skipped']

    Test outcome, always one of "passed", "failed", "skipped".

  longrepr: None | ExceptionInfo[BaseException] | tuple[str, int, str] | str | TerminalRepr

    None or a failure representation.

  result

    The collected items and collection nodes.

  sections: list[tuple[str, str]]

    Tuples of str `(heading, content)` with extra information for the test report. Used by pytest to add text captured from `stdout`, `stderr`, and intercepted logging events. May be used by other plugins to add arbitrary information to reports.

  property caplog: str

    Return captured log lines, if log capturing is enabled.

    Added in version 3.5.

  property capstderr: str

    Return captured text from stderr, if capturing is enabled.

    Added in version 3.0.

  property capstdout: str

    Return captured text from stdout, if capturing is enabled.

    Added in version 3.0.

  property count_towards_summary: bool

    Experimental Whether this report should be counted towards the totals shown at the end of the test session: "1 passed, 1 failure, etc".

    Note

    This function is considered experimental, so beware that it is subject to changes even in patch releases.

  property failed: bool

    Whether the outcome is failed.

  property fspath: str

    The path portion of the reported node, as a string.

  property head_line: str | None

    Experimental The head line shown with longrepr output for this report, more commonly during traceback representation during failures:

        ________ Test.foo ________

    In the example above, the head_line is "Test.foo".

    Note

    This function is considered experimental, so beware that it is subject to changes even in patch releases.

  property longreprtext: str

    Read-only property that returns the full string representation of `longrepr`.

    Added in version 3.0.

  property passed: bool

    Whether the outcome is passed.

  property skipped: bool

    Whether the outcome is skipped.

### Config

final class Config

  Access to configuration values, pluginmanager and plugin hooks.

  Parameters:

    - pluginmanager (PytestPluginManager) -- A pytest PluginManager.

    - invocation_params (InvocationParams) -- Object containing parameters regarding the `pytest.main()` invocation.

  final class InvocationParams(*, args, plugins, dir)

    Holds parameters passed during `pytest.main()`.

    The object attributes are read-only.

    Added in version 5.1.

    Note

    Note that the environment variable `PYTEST_ADDOPTS` and the `addopts` configuration option are handled by pytest, not being included in the `args` attribute.

    Plugins accessing `InvocationParams` must be aware of that.

    args: tuple[str, ...]

      The command-line arguments as passed to `pytest.main()`.

    plugins: Sequence[str | object] | None

      Extra plugins, might be `None`.

    dir: Path

      The directory from which `pytest.main()` was invoked.

  class ArgsSource(*values)

    Indicates the source of the test arguments.

    Added in version 7.2.

    ARGS = 1

      Command line arguments.

    INVOCATION_DIR = 2

      Invocation directory.

    TESTPATHS = 3

      'testpaths' configuration value.

  option

    Access to command line option as attributes.

    Type:

      argparse.Namespace

  invocation_params

    The parameters with which pytest was invoked.

    Type:

      InvocationParams

  pluginmanager

    The plugin manager handles plugin registration and hook invocation.

    Type:

      PytestPluginManager

  stash

    A place where plugins can store information on the config for their own use.

    Type:

      Stash

  property rootpath: Path

    The path to the rootdir.

    Added in version 6.1.

  property inipath: Path | None

    The path to the configfile.

    Added in version 6.1.

  add_cleanup(func)

    Add a function to be called when the config object gets out of use (usually coinciding with pytest_unconfigure).

  classmethod fromdictargs(option_dict, args)

    Constructor usable for subprocesses.

  issue_config_time_warning(warning, stacklevel)

    Issue and handle a warning during the "configure" stage.

    During `pytest_configure` we can't capture warnings using the `catch_warnings_for_item` function because it is not possible to have hook wrappers around `pytest_configure`.

    This function is mainly intended for plugins that need to issue warnings during `pytest_configure` (or similar stages).

    Parameters:

      - warning (Warning) -- The warning instance.

      - stacklevel (int) -- stacklevel forwarded to warnings.warn.

  addinivalue_line(name, line)

    Add a line to a configuration option. The option must have been declared but might not yet be set in which case the line becomes the first line in its value.

  getini(name)

    Return configuration value the an configuration file.

    If a configuration value is not defined in a configuration file, then the `default` value provided while registering the configuration through `parser.addini` will be returned. Please note that you can even provide `None` as a valid default value.

    If `default` is not provided while registering using `parser.addini`, then a default value based on the `type` parameter passed to `parser.addini` will be returned. The default values based on `type` are: `paths`, `pathlist`, `args` and `linelist` : empty list `[]` `bool` : `False` `string` : empty string `""` `int` : `0` `float` : `0.0`

    If neither the `default` nor the `type` parameter is passed while registering the configuration through `parser.addini`, then the configuration is treated as a string and a default empty string '' is returned.

    If the specified name hasn't been registered through a prior `parser.addini` call (usually from a plugin), a ValueError is raised.

  getoption(name, default=<NOTSET>, skip=False)

    Return command line option value.

    Parameters:

      - name (str) -- Name of the option. You may also specify the literal `--OPT` option instead of the "dest" option name.

      - default (Any) -- Fallback value if no option of that name is declared via `pytest_addoption`. Note this parameter will be ignored when the option is declared even if the option's value is `None`.

      - skip (bool) -- If `True`, raise `pytest.skip()` if option is undeclared or has a `None` value. Note that even if `True`, if a default was specified it will be returned instead of a skip.

  getvalue(name, path=None)

    Deprecated, use getoption() instead.

  getvalueorskip(name, path=None)

    Deprecated, use getoption(skip=True) instead.

  VERBOSITY_ASSERTIONS: Final = 'assertions'

    Verbosity type for failed assertions (see `verbosity_assertions`).

  VERBOSITY_TEST_CASES: Final = 'test_cases'

    Verbosity type for test case execution (see `verbosity_test_cases`).

  VERBOSITY_SUBTESTS: Final = 'subtests'

    Verbosity type for failed subtests (see `verbosity_subtests`).

  get_verbosity(verbosity_type=None)

    Retrieve the verbosity level for a fine-grained verbosity type.

    Parameters:

      verbosity_type (str | None) -- Verbosity type to get level for. If a level is configured for the given type, that value will be returned. If the given type is not a known verbosity type, the global verbosity level will be returned. If the given type is None (default), the global verbosity level will be returned.

    To configure a level for a fine-grained verbosity type, the configuration file should have a setting for the configuration name and a numeric value for the verbosity level. A special value of "auto" can be used to explicitly use the global verbosity level.

    Example:

    toml

        [tool.pytest]
        verbosity_assertions = 2

    ini

        [pytest]
        verbosity_assertions = 2

        pytest -v

        print(config.get_verbosity())  # 1
        print(config.get_verbosity(Config.VERBOSITY_ASSERTIONS))  # 2

### Dir

final class Dir

  Collector of files in a file system directory.

  Added in version 8.0.

  Note

  Python directories with an `__init__.py` file are instead collected by `Package` by default. Both are `Directory` collectors.

  classmethod from_parent(parent, *, path)

    The public constructor.

    Parameters:

      - parent (nodes.Collector) -- The parent collector of this Dir.

      - path (pathlib.Path) -- The directory's path.

  collect()

    Collect children (items and collectors) for this collector.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  session: Session

    The pytest session this node is part of.

### Directory

class Directory

  Base class for collecting files from a directory.

  A basic directory collector does the following: goes over the files and sub-directories in the directory and creates collectors for them by calling the hooks `pytest_collect_directory` and `pytest_collect_file`, after checking that they are not ignored using `pytest_ignore_collect`.

  The default directory collectors are `Dir` and `Package`.

  Added in version 8.0.

  Using a custom directory collector.

  config: Config

    The pytest config object.

  name: str

    A unique name within the scope of the parent node.

  parent

    The parent collector node.

  path: pathlib.Path

    Filesystem path where this node was collected from (can be None).

  session: Session

    The pytest session this node is part of.

### ExceptionInfo

final class ExceptionInfo

  Wraps sys.exc_info() objects and offers help for navigating the traceback.

  classmethod from_exception(exception, exprinfo=None)

    Return an ExceptionInfo for an existing exception.

    The exception must have a non-`None` `__traceback__` attribute, otherwise this function fails with an assertion error. This means that the exception must have been raised, or added a traceback with the `with_traceback()` method.

    Parameters:

      exprinfo (str | None) -- A text string helping to determine if we should strip `AssertionError` from the output. Defaults to the exception message/`__str__()`.

    Added in version 7.4.

  classmethod from_exc_info(exc_info, exprinfo=None)

    Like `from_exception()`, but using old-style exc_info tuple.

  classmethod from_current(exprinfo=None)

    Return an ExceptionInfo matching the current traceback.

    Warning

    Experimental API

    Parameters:

      exprinfo (str | None) -- A text string helping to determine if we should strip `AssertionError` from the output. Defaults to the exception message/`__str__()`.

  classmethod for_later()

    Return an unfilled ExceptionInfo.

  fill_unfilled(exc_info)

    Fill an unfilled ExceptionInfo created with `for_later()`.

  property type: type[E]

    The exception class.

  property value: E

    The exception value.

  property tb: TracebackType

    The exception raw traceback.

  property typename: str

    The type name of the exception.

  property traceback: Traceback

    The traceback.

  exconly(tryshort=False)

    Return the exception as a string.

    When 'tryshort' resolves to True, and the exception is an AssertionError, only the actual exception part of the exception representation is returned (so 'AssertionError: ' is removed from the beginning).

  errisinstance(exc)

    Return True if the exception is an instance of exc.

    Consider using `isinstance(excinfo.value, exc)` instead.

  getrepr(showlocals=False, style='long', abspath=False, tbfilter=True, funcargs=False, truncate_locals=True, truncate_args=True, chain=True)

    Return str()able representation of this exception info.

    Parameters:

      - showlocals (bool) -- Show locals per traceback entry. Ignored if `style=="native"`.

      - style (str) -- long|short|line|no|native|value traceback style.

      - abspath (bool) -- If paths should be changed to absolute or left unchanged.

      - tbfilter (bool | Callable[[ExceptionInfo[BaseException]], Traceback]) --

        A filter for traceback entries.

        - If false, don't hide any entries.

        - If true, hide internal entries and entries that contain a local variable `__tracebackhide__ = True`.

        - If a callable, delegates the filtering to the callable.

        Ignored if `style` is `"native"`.

      - funcargs (bool) -- Show fixtures ("funcargs" for legacy purposes) per traceback entry.

      - truncate_locals (bool) -- With `showlocals==True`, make sure locals can be safely represented as strings.

      - truncate_args (bool) -- With `showargs==True`, make sure args can be safely represented as strings.

      - chain (bool) -- If chained exceptions in Python 3 should be shown.

    Changed in version 3.9: Added the `chain` parameter.

  match(regexp)

    Check whether the regular expression `regexp` matches the string representation of the exception using `re.search()`.

    If it matches `True` is returned, otherwise an `AssertionError` is raised.

  group_contains(expected_exception, *, match=None, depth=None)

    Check whether a captured exception group contains a matching exception.

    Parameters:

      - expected_exception (Type[BaseException] | Tuple[Type[BaseException]]) -- The expected exception type, or a tuple if one of multiple possible exception types are expected.

      - match (str | re.Pattern[str] | None) --

        If specified, a string containing a regular expression, or a regular expression object, that is tested against the string representation of the exception and its `PEP-678 <https://peps.python.org/pep-0678/>` `__notes__` using `re.search()`.

        To match a literal string that may contain special characters, the pattern can first be escaped with `re.escape()`.

      - depth (Optional[int]) -- If `None`, will search for a matching exception at any nesting depth. If >= 1, will only match an exception if it's at the specified depth (depth = 1 being the exceptions contained within the topmost exception group).

    Added in version 8.0.

    Warning

    This helper makes it easy to check for the presence of specific exceptions, but it is very bad for checking that the group does not contain any other exceptions. You should instead consider using `pytest.RaisesGroup`

### ExitCode

class ExitCode(*values)

  Encodes the valid exit codes by pytest.

  Currently users and plugins may supply other exit codes as well.

  Added in version 5.0.

### FixtureDef

class FixtureDef

  Bases: `Generic`[`FixtureValue`]

  A container for a fixture definition.

  Note: At this time, only explicitly documented fields and methods are considered public stable API.

  property scope: Literal['session', 'package', 'module', 'class', 'function']

    Scope string, one of "function", "class", "module", "package", "session".

  execute(request)

    Return the value of this fixture, executing it if not cached.

### MarkDecorator

class MarkDecorator

  A decorator for applying a mark on test functions and classes.

  `MarkDecorators` are created with `pytest.mark`:

      mark1 = pytest.mark.NAME  # Simple MarkDecorator
      mark2 = pytest.mark.NAME(name1=value)  # Parametrized MarkDecorator

  and can then be applied as decorators to test functions:

      @mark2
      def test_function():
          pass

  When a `MarkDecorator` is called, it does the following:

  1. If called with a single class as its only positional argument and no additional keyword arguments, it attaches the mark to the class so it gets applied automatically to all test cases found in that class.

  2. If called with a single function as its only positional argument and no additional keyword arguments, it attaches the mark to the function, containing all the arguments already stored internally in the `MarkDecorator`.

  3. When called in any other case, it returns a new `MarkDecorator` instance with the original `MarkDecorator`'s content updated with the arguments passed to this call.

  Note: The rules above prevent a `MarkDecorator` from storing only a single function or class reference as its positional argument with no additional keyword or positional arguments. You can work around this by using `with_args()`.

  property name: str

    Alias for mark.name.

  property args: tuple[Any, ...]

    Alias for mark.args.

  property kwargs: Mapping[str, Any]

    Alias for mark.kwargs.

  with_args(*args, **kwargs)

    Return a MarkDecorator with extra arguments added.

    Unlike calling the MarkDecorator, with_args() can be used even if the sole argument is a callable/class.

### MarkGenerator

final class MarkGenerator

  Factory for `MarkDecorator` objects - exposed as a `pytest.mark` singleton instance.

  Example:

      import pytest

      @pytest.mark.slowtest
      def test_function():
          pass

  applies a 'slowtest' `Mark` on `test_function`.

### Mark

final class Mark

  A pytest mark.

  name: str

    Name of the mark.

  args: tuple[Any, ...]

    Positional arguments of the mark decorator.

  kwargs: Mapping[str, Any]

    Keyword arguments of the mark decorator.

  combined_with(other)

    Return a new Mark which is a combination of this Mark and another Mark.

    Combines by appending args and merging kwargs.

    Parameters:

      other (Mark) -- The mark to combine with.

    Return type:

      Mark

### Metafunc

final class Metafunc

  Objects passed to the `pytest_generate_tests` hook.

  They help to inspect a test function and to generate tests according to test configuration or values specified in the class or module where a test function is defined.

  definition

    Access to the underlying `_pytest.python.FunctionDefinition`.

  config

    Access to the `pytest.Config` object for the test session.

  module

    The module object where the test function is defined in.

  function

    Underlying Python test function.

  fixturenames

    Set of fixture names required by the test function.

  cls

    Class object where the test function is defined in or `None`.

  parametrize(argnames, argvalues, indirect=False, ids=None, scope=None, *, _param_mark=None)

    Add new invocations to the underlying test function using the list of argvalues for the given argnames. Parametrization is performed during the collection phase. If you need to setup expensive resources see about setting `indirect` to do it at test setup time instead.

    Can be called multiple times per test function (but only on different argument names), in which case each call parametrizes all previous parametrizations, e.g.

        unparametrized:         t
        parametrize ["x", "y"]: t[x], t[y]
        parametrize [1, 2]:     t[x-1], t[x-2], t[y-1], t[y-2]

    Parameters:

      - argnames (str | Sequence[str]) -- A comma-separated string denoting one or more argument names, or a list/tuple of argument strings.

      - argvalues (Iterable[ParameterSet | Sequence[object] | object]) --

        The list of argvalues determines how often a test is invoked with different argument values.

        If only one argname was specified argvalues is a list of values. If N argnames were specified, argvalues must be a list of N-tuples, where each tuple-element specifies a value for its respective argname.

      - indirect (bool | Sequence[str]) -- A list of arguments' names (subset of argnames) or a boolean. If True the list contains all names from the argnames. Each argvalue corresponding to an argname in this list will be passed as request.param to its respective argname fixture function so that it can perform more expensive setups during the setup phase of a test rather than at collection time.

      - ids (Iterable[object | None] | Callable[[Any], object | None] | None) --

        Sequence of (or generator for) ids for `argvalues`, or a callable to return part of the id for each argvalue.

        With sequences (and generators like `itertools.count()`) the returned ids should be of type `string`, `int`, `float`, `bool`, or `None`. They are mapped to the corresponding index in `argvalues`. `None` means to use the auto-generated id.

        Added in version 8.4: pytest.HIDDEN_PARAM means to hide the parameter set from the test name. Can only be used at most 1 time, as test names need to be unique.

        If it is a callable it will be called for each entry in `argvalues`, and the return value is used as part of the auto-generated id for the whole set (where parts are joined with dashes ("-")). This is useful to provide more specific ids for certain items, e.g. dates. Returning `None` will use an auto-generated id.

        If no ids are provided they will be generated automatically from the argvalues.

      - scope (Literal['session', 'package', 'module', 'class', 'function'] | None) -- If specified it denotes the scope of the parameters. The scope is used for grouping tests by parameter instances. It will also override any fixture-function defined scope, allowing to set a dynamic scope using test context or configuration.

### Parser

final class Parser

  Parser for command line arguments and config-file values.

  Variables:

    extra_info -- Dict of generic param -> value to display in case there's an error processing the command line arguments.

  getgroup(name, description='', after=None)

    Get (or create) a named option Group.

    Parameters:

      - name (str) -- Name of the option group.

      - description (str) -- Long description for --help output.

      - after (str | None) -- Name of another group, used for ordering --help output.

    Returns:

      The option group.

    Return type:

      OptionGroup

    The returned group object has an `addoption` method with the same signature as `parser.addoption` but will be shown in the respective group in the output of `pytest --help`.

  addoption(*opts, **attrs)

    Register a command line option.

    Parameters:

      - opts (str) -- Option names, can be short or long options.

      - attrs (Any) -- Same attributes as the argparse library's `add_argument()` function accepts.

    After command line parsing, options are available on the pytest config object via `config.option.NAME` where `NAME` is usually set by passing a `dest` attribute, for example `addoption("--long", dest="NAME", ...)`.

  parse_known_args(args, namespace=None)

    Parse the known arguments at this point.

    Returns:

      An argparse namespace object.

    Return type:

      Namespace

  parse_known_and_unknown_args(args, namespace=None)

    Parse the known arguments at this point, and also return the remaining unknown flag arguments.

    Returns:

      A tuple containing an argparse namespace object for the known arguments, and a list of unknown flag arguments.

    Return type:

      tuple[Namespace, list[str]]

  addini(name, help, type=None, default=<notset>, *, aliases=())

    Register a configuration file option.

    Parameters:

      - name (str) -- Name of the configuration.

      - type (Literal['string', 'paths', 'pathlist', 'args', 'linelist', 'bool', 'int', 'float'] | None) --

        Type of the configuration. Can be:

        > - `string`: a string

        > - `bool`: a boolean

        > - `args`: a list of strings, separated as in a shell

        > - `linelist`: a list of strings, separated by line breaks

        > - `paths`: a list of `pathlib.Path`, separated as in a shell

        > - `pathlist`: a list of `py.path`, separated as in a shell

        > - `int`: an integer

        > - `float`: a floating-point number

        > Added in version 8.4: The `float` and `int` types.

        For `paths` and `pathlist` types, they are considered relative to the config-file. In case the execution is happening without a config-file defined, they will be considered relative to the current working directory (for example with `--override-ini`).

        Added in version 7.0: The `paths` variable type.

        Added in version 8.1: Use the current working directory to resolve `paths` and `pathlist` in the absence of a config-file.

        Defaults to `string` if `None` or not passed.

      - default (Any) -- Default value if no config-file option exists but is queried.

      - aliases (Sequence[str]) --

        Additional names by which this option can be referenced. Aliases resolve to the canonical name.

        Added in version 9.0: The `aliases` parameter.

    The value of configuration keys can be retrieved via a call to `config.getini(name)`.

### OptionGroup

class OptionGroup

  A group of options shown in its own section.

  addoption(*opts, **attrs)

    Add an option to this group.

    If a shortened version of a long option is specified, it will be suppressed in the help. `addoption('--twowords', '--two-words')` results in help showing `--two-words` only, but `--twowords` gets accepted and the automatic destination is in `args.twowords`.

    Parameters:

      - opts (str) -- Option names, can be short or long options.

      - attrs (Any) -- Same attributes as the argparse library's `add_argument()` function accepts.

### PytestPluginManager

final class PytestPluginManager

  Bases: `PluginManager`

  A `pluggy.PluginManager` with additional pytest-specific functionality:

  - Loading plugins from the command line, `PYTEST_PLUGINS` env variable and `pytest_plugins` global variables found in plugins being loaded.

  - `conftest.py` loading during start-up.

  register(plugin, name=None)

    Register a plugin and return its name.

    Parameters:

      name (str | None) -- The name under which to register the plugin. If not specified, a name is generated using `get_canonical_name()`.

    Returns:

      The plugin name. If the name is blocked from registering, returns `None`.

    Return type:

      str | None

    If the plugin is already registered, raises a `ValueError`.

  getplugin(name)
  hasplugin(name)

    Return whether a plugin with the given name is registered.

  import_plugin(modname, consider_entry_points=False)

    Import a plugin with `modname`.

    If `consider_entry_points` is True, entry point names are also considered to find a plugin.

  add_hookcall_monitoring(before, after)

    Add before/after tracing functions for all hooks.

    Returns an undo function which, when called, removes the added tracers.

    `before(hook_name, hook_impls, kwargs)` will be called ahead of all hook calls and receive a hookcaller instance, a list of HookImpl instances and the keyword arguments for the hook call.

    `after(outcome, hook_name, hook_impls, kwargs)` receives the same arguments as `before` but also a `Result` object which represents the result of the overall hook call.

  add_hookspecs(module_or_class)

    Add new hook specifications defined in the given `module_or_class`.

    Functions are recognized as hook specifications if they have been decorated with a matching `HookspecMarker`.

  check_pending()

    Verify that all hooks which have not been verified against a hook specification are optional, otherwise raise `PluginValidationError`.

  enable_tracing()

    Enable tracing of hook calls.

    Returns an undo function which, when called, removes the added tracing.

  get_canonical_name(plugin)

    Return a canonical name for a plugin object.

    Note that a plugin may be registered under a different name specified by the caller of `register(plugin, name)`. To obtain the name of a registered plugin use `get_name(plugin)` instead.

  get_hookcallers(plugin)

    Get all hook callers for the specified plugin.

    Returns:

      The hook callers, or `None` if `plugin` is not registered in this plugin manager.

    Return type:

      list[HookCaller] | None

  get_name(plugin)

    Return the name the plugin is registered under, or `None` if is isn't.

  get_plugin(name)

    Return the plugin registered under the given name, if any.

  get_plugins()

    Return a set of all registered plugin objects.

  has_plugin(name)

    Return whether a plugin with the given name is registered.

  is_blocked(name)

    Return whether the given plugin name is blocked.

  is_registered(plugin)

    Return whether the plugin is already registered.

  list_name_plugin()

    Return a list of (name, plugin) pairs for all registered plugins.

  list_plugin_distinfo()

    Return a list of (plugin, distinfo) pairs for all setuptools-registered plugins.

  load_setuptools_entrypoints(group, name=None)

    Load modules from querying the specified setuptools `group`.

    Parameters:

      - group (str) -- Entry point group to load plugins.

      - name (str | None) -- If given, loads only plugins with the given `name`.

    Returns:

      The number of plugins loaded by this call.

    Return type:

      int

  set_blocked(name)

    Block registrations of the given name, unregister if already registered.

  subset_hook_caller(name, remove_plugins)

    Return a proxy `HookCaller` instance for the named method which manages calls to all registered plugins except the ones from remove_plugins.

  unblock(name)

    Unblocks a name.

    Returns whether the name was actually blocked.

  unregister(plugin=None, name=None)

    Unregister a plugin and all of its hook implementations.

    The plugin can be specified either by the plugin object or the plugin name. If both are specified, they must agree.

    Returns the unregistered plugin, or `None` if not found.

  project_name: Final

    The project name.

  hook: Final

    The "hook relay", used to call a hook on all registered plugins. See calling.

  trace: Final[_tracing.TagTracerSub]

    The tracing entry point. See tracing.

### RaisesExc

final class RaisesExc

  Added in version 8.4.

  This is the class constructed when calling `pytest.raises()`, but may be used directly as a helper class with `RaisesGroup` when you want to specify requirements on sub-exceptions.

  You don't need this if you only want to specify the type, since `RaisesGroup` accepts `type[BaseException]`.

  Parameters:

    - expected_exception (type[BaseException] | tuple[type[BaseException]] | None) --

      The expected type, or one of several possible types. May be `None` in order to only make use of `match` and/or `check`

      The type is checked with `isinstance()`, and does not need to be an exact match. If that is wanted you can use the `check` parameter.

    - match (str | Pattern[str]) -- A regex to match.

    - check (Callable[[BaseException], bool]) -- If specified, a callable that will be called with the exception as a parameter after checking the type and the match regex if specified. If it returns `True` it will be considered a match, if not it will be considered a failed match.

  `RaisesExc.matches()` can also be used standalone to check individual exceptions.

  Examples:

      with RaisesGroup(RaisesExc(ValueError, match="string"))
          ...
      with RaisesGroup(RaisesExc(check=lambda x: x.args == (3, "hello"))):
          ...
      with RaisesGroup(RaisesExc(check=lambda x: type(x) is ValueError)):
          ...

  fail_reason

    Set after a call to `matches()` to give a human-readable reason for why the match failed. When used as a context manager the string will be printed as the reason for the test failing.

  matches(exception)

    Check if an exception matches the requirements of this `RaisesExc`. If it fails, `RaisesExc.fail_reason` will be set.

    Examples:

        assert RaisesExc(ValueError).matches(my_exception):
        # is equivalent to
        assert isinstance(my_exception, ValueError)

        # this can be useful when checking e.g. the ``__cause__`` of an exception.
        with pytest.raises(ValueError) as excinfo:
            ...
        assert RaisesExc(SyntaxError, match="foo").matches(excinfo.value.__cause__)
        # above line is equivalent to
        assert isinstance(excinfo.value.__cause__, SyntaxError)
        assert re.search("foo", str(excinfo.value.__cause__)

### RaisesGroup

Tutorial: Assertions about expected exception groups

final class RaisesGroup

  Added in version 8.4.

  Contextmanager for checking for an expected `ExceptionGroup`. This works similar to `pytest.raises()`, but allows for specifying the structure of an `ExceptionGroup`. `ExceptionInfo.group_contains()` also tries to handle exception groups, but it is very bad at checking that you didn't get unexpected exceptions.

  The catching behaviour differs from except*, being much stricter about the structure by default. By using `allow_unwrapped=True` and `flatten_subgroups=True` you can match except* fully when expecting a single exception.

  Parameters:

    - args --

      Any number of exception types, `RaisesGroup` or `RaisesExc` to specify the exceptions contained in this exception. All specified exceptions must be present in the raised group, and no others.

      If you expect a variable number of exceptions you need to use `pytest.raises(ExceptionGroup)` and manually check the contained exceptions. Consider making use of `RaisesExc.matches()`.

      It does not care about the order of the exceptions, so `RaisesGroup(ValueError, TypeError)` is equivalent to `RaisesGroup(TypeError, ValueError)`.

    - match (str | re.Pattern[str] | None) --

      If specified, a string containing a regular expression, or a regular expression object, that is tested against the string representation of the exception group and its PEP 678 `__notes__` using `re.search()`.

      To match a literal string that may contain special characters, the pattern can first be escaped with `re.escape()`.

      Note that " (5 subgroups)" will be stripped from the `repr` before matching.

    - check (Callable[[E], bool]) -- If specified, a callable that will be called with the group as a parameter after successfully matching the expected exceptions. If it returns `True` it will be considered a match, if not it will be considered a failed match.

    - allow_unwrapped (bool) --

      If expecting a single exception or `RaisesExc` it will match even if the exception is not inside an exceptiongroup.

      Using this together with `match`, `check` or expecting multiple exceptions will raise an error.

    - flatten_subgroups (bool) -- "flatten" any groups inside the raised exception group, extracting all exceptions inside any nested groups, before matching. Without this it expects you to fully specify the nesting structure by passing `RaisesGroup` as expected parameter.

  Examples:

      with RaisesGroup(ValueError):
          raise ExceptionGroup("", (ValueError(),))
      # match
      with RaisesGroup(
          ValueError,
          ValueError,
          RaisesExc(TypeError, match="^expected int$"),
          match="^my group$",
      ):
          raise ExceptionGroup(
              "my group",
              [
                  ValueError(),
                  TypeError("expected int"),
                  ValueError(),
              ],
          )
      # check
      with RaisesGroup(
          KeyboardInterrupt,
          match="^hello$",
          check=lambda x: isinstance(x.__cause__, ValueError),
      ):
          raise BaseExceptionGroup("hello", [KeyboardInterrupt()]) from ValueError
      # nested groups
      with RaisesGroup(RaisesGroup(ValueError)):
          raise ExceptionGroup("", (ExceptionGroup("", (ValueError(),)),))

      # flatten_subgroups
      with RaisesGroup(ValueError, flatten_subgroups=True):
          raise ExceptionGroup("", (ExceptionGroup("", (ValueError(),)),))

      # allow_unwrapped
      with RaisesGroup(ValueError, allow_unwrapped=True):
          raise ValueError

  `RaisesGroup.matches()` can also be used directly to check a standalone exception group.

  The matching algorithm is greedy, which means cases such as this may fail:

      with RaisesGroup(ValueError, RaisesExc(ValueError, match="hello")):
          raise ExceptionGroup("", (ValueError("hello"), ValueError("goodbye")))

  even though it generally does not care about the order of the exceptions in the group. To avoid the above you should specify the first `ValueError` with a `RaisesExc` as well.

  Note

  When raised exceptions don't match the expected ones, you'll get a detailed error message explaining why. This includes `repr(check)` if set, which in Python can be overly verbose, showing memory locations etc etc.

  If installed and imported (in e.g. `conftest.py`), the `hypothesis` library will monkeypatch this output to provide shorter & more readable repr's.

  fail_reason

    Set after a call to `matches()` to give a human-readable reason for why the match failed. When used as a context manager the string will be printed as the reason for the test failing.

  matches(exception: BaseException | None) → TypeGuard[ExceptionGroup[ExcT_1]]
  matches(exception: BaseException | None) → TypeGuard[BaseExceptionGroup[BaseExcT_1]]

    Check if an exception matches the requirements of this RaisesGroup. If it fails, `RaisesGroup.fail_reason` will be set.

    Example:

        with pytest.raises(TypeError) as excinfo:
            ...
        assert RaisesGroup(ValueError).matches(excinfo.value.__cause__)
        # the above line is equivalent to
        myexc = excinfo.value.__cause
        assert isinstance(myexc, BaseExceptionGroup)
        assert len(myexc.exceptions) == 1
        assert isinstance(myexc.exceptions[0], ValueError)

### TerminalReporter

final class TerminalReporter(config, file=None)
  wrap_write(content, *, flush=False, margin=8, line_sep='\n', **markup)

    Wrap message with margin for progress info.

  rewrite(line, **markup)

    Rewinds the terminal cursor to the beginning and writes the given line.

    Parameters:

      erase -- If True, will also add spaces until the full terminal width to ensure previous lines are properly erased.

    The rest of the keyword arguments are markup instructions.

  build_summary_stats_line()

    Build the parts used in the last summary stats line.

    The summary stats line is the line shown at the end, "=== 12 passed, 2 errors in Xs===".

    This function builds a list of the "parts" that make up for the text in that line, in the example above it would be:

        [
            ("12 passed", {"green": True}),
            ("2 errors", {"red": True}
        ]

    That last dict for each line is a "markup dictionary", used by TerminalWriter to color output.

    The final color of the line is also determined by this function, and is the second element of the returned tuple.

### TestReport

class TestReport

  Bases: `BaseReport`

  Basic test report object (also used for setup and teardown calls if they fail).

  Reports can contain arbitrary extra attributes.

  nodeid: str

    Normalized collection nodeid.

  location: tuple[str, int | None, str]

    A (filesystempath, lineno, domaininfo) tuple indicating the actual location of a test item - it might be different from the collected one e.g. if a method is inherited from a different module. The filesystempath may be relative to `config.rootdir`. The line number is 0-based.

  keywords: Mapping[str, Any]

    A name -> value dictionary containing all keywords and markers associated with a test invocation.

  outcome: Literal['passed', 'failed', 'skipped']

    Test outcome, always one of "passed", "failed", "skipped".

  longrepr: None | ExceptionInfo[BaseException] | tuple[str, int, str] | str | TerminalRepr

    None or a failure representation.

  when: Literal['setup', 'call', 'teardown']

    One of 'setup', 'call', 'teardown' to indicate runtest phase.

  user_properties

    User properties is a list of tuples (name, value) that holds user defined properties of the test.

  sections: list[tuple[str, str]]

    Tuples of str `(heading, content)` with extra information for the test report. Used by pytest to add text captured from `stdout`, `stderr`, and intercepted logging events. May be used by other plugins to add arbitrary information to reports.

  duration: float

    Time it took to run just the test.

  start: float

    The system time when the call started, in seconds since the epoch.

  stop: float

    The system time when the call ended, in seconds since the epoch.

  classmethod from_item_and_call(item, call)

    Create and fill a TestReport with standard item and call info.

    Parameters:

      - item (Item) -- The item.

      - call (CallInfo[None]) -- The call info.

  property caplog: str

    Return captured log lines, if log capturing is enabled.

    Added in version 3.5.

  property capstderr: str

    Return captured text from stderr, if capturing is enabled.

    Added in version 3.0.

  property capstdout: str

    Return captured text from stdout, if capturing is enabled.

    Added in version 3.0.

  property count_towards_summary: bool

    Experimental Whether this report should be counted towards the totals shown at the end of the test session: "1 passed, 1 failure, etc".

    Note

    This function is considered experimental, so beware that it is subject to changes even in patch releases.

  property failed: bool

    Whether the outcome is failed.

  property fspath: str

    The path portion of the reported node, as a string.

  property head_line: str | None

    Experimental The head line shown with longrepr output for this report, more commonly during traceback representation during failures:

        ________ Test.foo ________

    In the example above, the head_line is "Test.foo".

    Note

    This function is considered experimental, so beware that it is subject to changes even in patch releases.

  property longreprtext: str

    Read-only property that returns the full string representation of `longrepr`.

    Added in version 3.0.

  property passed: bool

    Whether the outcome is passed.

  property skipped: bool

    Whether the outcome is skipped.

### TestShortLogReport

class TestShortLogReport

  Used to store the test status result category, shortletter and verbose word. For example `"rerun", "R", ("RERUN", {"yellow": True})`.

  Variables:

    - category -- The class of result, for example `“passed”`, `“skipped”`, `“error”`, or the empty string.

    - letter -- The short letter shown as testing progresses, for example `"."`, `"s"`, `"E"`, or the empty string.

    - word -- Verbose word is shown as testing progresses in verbose mode, for example `"PASSED"`, `"SKIPPED"`, `"ERROR"`, or the empty string.

  category: str

    Alias for field number 0

  letter: str

    Alias for field number 1

  word: str | tuple[str, Mapping[str, bool]]

    Alias for field number 2

### Result

Result object used within hook wrappers, see `Result in the pluggy documentation` for more information.

### Stash

class Stash

  `Stash` is a type-safe heterogeneous mutable mapping that allows keys and value types to be defined separately from where it (the `Stash`) is created.

  Usually you will be given an object which has a `Stash`, for example `Config` or a `Node`:

      stash: Stash = some_object.stash

  If a module or plugin wants to store data in this `Stash`, it creates `StashKey`s for its keys (at the module level):

      # At the top-level of the module
      some_str_key = StashKey[str]()
      some_bool_key = StashKey[bool]()

  To store information:

      # Value type must match the key.
      stash[some_str_key] = "value"
      stash[some_bool_key] = True

  To retrieve the information:

      # The static type of some_str is str.
      some_str = stash[some_str_key]
      # The static type of some_bool is bool.
      some_bool = stash[some_bool_key]

  Added in version 7.0.

  __setitem__(key, value)

    Set a value for key.

  __getitem__(key)

    Get the value for key.

    Raises `KeyError` if the key wasn't set before.

  get(key, default)

    Get the value for key, or return default if the key wasn't set before.

  setdefault(key, default)

    Return the value of key if already set, otherwise set the value of key to default and return default.

  __delitem__(key)

    Delete the value for key.

    Raises `KeyError` if the key wasn't set before.

  __contains__(key)

    Return whether key was set.

  __len__()

    Return how many items exist in the stash.

class StashKey

  Bases: `Generic`[`T`]

  `StashKey` is an object used as a key to a `Stash`.

  A `StashKey` is associated with the type `T` of the value of the key.

  A `StashKey` is unique and cannot conflict with another key.

  Added in version 7.0.

## Global Variables

pytest treats some global variables in a special manner when defined in a test module or `conftest.py` files.

collect_ignore

Tutorial: Customizing test collection

Can be declared in conftest.py files to exclude test directories or modules. Needs to be a list of paths (`str`, `pathlib.Path` or any `os.PathLike`).

    collect_ignore = ["setup.py"]

collect_ignore_glob

Tutorial: Customizing test collection

Can be declared in conftest.py files to exclude test directories or modules with Unix shell-style wildcards. Needs to be `list[str]` where `str` can contain glob patterns.

    collect_ignore_glob = ["*_ignore.py"]

pytest_plugins

Tutorial: Requiring/Loading plugins in a test module or conftest file

Can be declared at the global level in test modules and conftest.py files to register additional plugins. Can be either a `str` or `Sequence[str]`.

    pytest_plugins = "myapp.testsupport.myplugin"

    pytest_plugins = ("myapp.testsupport.tools", "myapp.testsupport.regression")

pytestmark

Tutorial: Marking whole classes or modules

Can be declared at the global level in test modules to apply one or more marks to all test functions and methods. Can be either a single mark or a list of marks (applied in left-to-right order).

    import pytest

    pytestmark = pytest.mark.webtest

    import pytest

    pytestmark = [pytest.mark.integration, pytest.mark.slow]

## Environment Variables

Environment variables that can be used to change pytest's behavior.

CI

When set to a non-empty value, pytest acknowledges that is running in a CI process. See also CI Pipelines.

BUILD_NUMBER

When set to a non-empty value, pytest acknowledges that is running in a CI process. Alternative to `CI`. See also CI Pipelines.

PYTEST_ADDOPTS

This contains a command-line (parsed by the py:mod:`shlex` module) that will be prepended to the command line given by the user, see Builtin configuration file options for more information.

PYTEST_VERSION

This environment variable is defined at the start of the pytest session and is undefined afterwards. It contains the value of `pytest.__version__`, and among other things can be used to easily check if a code is running from within a pytest run.

PYTEST_CURRENT_TEST

This is not meant to be set by users, but is set by pytest internally with the name of the current test so other processes can inspect it, see PYTEST_CURRENT_TEST environment variable for more information.

PYTEST_DEBUG

When set, pytest will print tracing and debug information.

PYTEST_DEBUG_TEMPROOT

Root for temporary directories produced by fixtures like `tmp_path` as discussed in Temporary directory location and retention.

PYTEST_DISABLE_PLUGIN_AUTOLOAD

When set, disables plugin auto-loading through entry point packaging metadata. Only plugins explicitly specified in `PYTEST_PLUGINS` or with `-p` will be loaded. See also --disable-plugin-autoload.

PYTEST_PLUGINS

Contains comma-separated list of modules that should be loaded as plugins:

    export PYTEST_PLUGINS=mymodule.plugin,xdist

See also `-p`.

PYTEST_THEME

Sets a pygment style to use for the code output.

PYTEST_THEME_MODE

Sets the `PYTEST_THEME` to be either dark or light.

PY_COLORS

When set to `1`, pytest will use color in terminal output. When set to `0`, pytest will not use color. `PY_COLORS` takes precedence over `NO_COLOR` and `FORCE_COLOR`.

NO_COLOR

When set to a non-empty string (regardless of value), pytest will not use color in terminal output. `PY_COLORS` takes precedence over `NO_COLOR`, which takes precedence over `FORCE_COLOR`. See no-color.org for other libraries supporting this community standard.

FORCE_COLOR

When set to a non-empty string (regardless of value), pytest will use color in terminal output. `PY_COLORS` and `NO_COLOR` take precedence over `FORCE_COLOR`.

## Exceptions

exception UsageError

  Bases: `Exception`

  Error in pytest usage or invocation.

final exception FixtureLookupError

  Bases: `LookupError`

  Could not return a requested fixture (missing or invalid).

## Warnings

Custom warnings generated in some situations such as improper usage or deprecated features.

class PytestWarning

  Bases: `UserWarning`

  Base class for all warnings emitted by pytest.

class PytestAssertRewriteWarning

  Bases: `PytestWarning`

  Warning emitted by the pytest assert rewrite module.

class PytestCacheWarning

  Bases: `PytestWarning`

  Warning emitted by the cache plugin in various situations.

class PytestCollectionWarning

  Bases: `PytestWarning`

  Warning emitted when pytest is not able to collect a file or symbol in a module.

class PytestConfigWarning

  Bases: `PytestWarning`

  Warning emitted for configuration issues.

class PytestDeprecationWarning

  Bases: `PytestWarning`, `DeprecationWarning`

  Warning class for features that will be removed in a future version.

class PytestExperimentalApiWarning

  Bases: `PytestWarning`, `FutureWarning`

  Warning category used to denote experiments in pytest.

  Use sparingly as the API might change or even be removed completely in a future version.

class PytestReturnNotNoneWarning

  Bases: `PytestWarning`

  Warning emitted when a test function returns a value other than `None`.

  See Returning non-None value in test functions for details.

class PytestRemovedIn9Warning

  Bases: `PytestDeprecationWarning`

  Warning class for features that will be removed in pytest 9.

class PytestUnknownMarkWarning

  Bases: `PytestWarning`

  Warning emitted on use of unknown markers.

  See How to mark test functions with attributes for details.

class PytestUnraisableExceptionWarning

  Bases: `PytestWarning`

  An unraisable exception was reported.

  Unraisable exceptions are exceptions raised in `__del__` implementations and similar situations when the exception cannot be raised as normal.

class PytestUnhandledThreadExceptionWarning

  Bases: `PytestWarning`

  An unhandled exception occurred in a `Thread`.

  Such exceptions don't propagate normally.

Consult the Internal pytest warnings section in the documentation for more information.

## Configuration Options

Here is a list of builtin configuration options that may be written in a `pytest.ini` (or `.pytest.ini`), `pyproject.toml`, `tox.ini`, or `setup.cfg` file, usually located at the root of your repository.

To see each file format in details, see Configuration file formats.

Warning

Usage of `setup.cfg` is not recommended except for very simple use cases. `.cfg` files use a different parser than `pytest.ini` and `tox.ini` which might cause hard to track down problems. When possible, it is recommended to use the latter files, or `pytest.toml` or `pyproject.toml`, to hold your pytest configuration.

Configuration options may be overwritten in the command-line by using `-o/--override-ini`, which can also be passed multiple times. The expected format is `name=value`. For example:

    pytest -o console_output_style=classic -o cache_dir=/tmp/mycache

addopts

  Add the specified `OPTS` to the set of command line arguments as if they had been specified by the user. Example: if you have this configuration file content:

      # content of pytest.toml
      [pytest]
      addopts = ["--maxfail=2", "-rf"]  # exit after 2 failures, report fail info

  issuing `pytest test_hello.py` actually means:

      pytest --maxfail=2 -rf test_hello.py

  Default is to add no options.

cache_dir

  Sets the directory where the cache plugin's content is stored. Default directory is `.pytest_cache` which is created in rootdir. Directory may be relative or absolute path. If setting relative path, then directory is created relative to rootdir. Additionally, a path may contain environment variables, that will be expanded. For more information about cache plugin please refer to How to re-run failed tests and maintain state between test runs.

collect_imported_tests

  Added in version 8.4.

  Setting this to `false` will make pytest collect classes/functions from test files only if they are defined in that file (as opposed to imported there).

  toml

      [pytest]
      collect_imported_tests = false

  ini

      [pytest]
      collect_imported_tests = false

  Default: `true`

  pytest traditionally collects classes/functions in the test module namespace even if they are imported from another file.

  For example:

      # contents of src/domain.py
      class Testament: ...

      # contents of tests/test_testament.py
      from domain import Testament

      def test_testament(): ...

  In this scenario, with the default options, pytest will collect the class `Testament` from `tests/test_testament.py` because it starts with `Test`, even though in this case it is a production class being imported in the test module namespace.

  Set `collected_imported_tests` to `false` in the configuration file prevents that.

consider_namespace_packages

  Controls if pytest should attempt to identify namespace packages when collecting Python modules. Default is `False`.

  Set to `True` if the package you are testing is part of a namespace package. Namespace packages are also supported as `--pyargs` target.

  Only native namespace packages are supported, with no plans to support legacy namespace packages.

  Added in version 8.1.

console_output_style

  Sets the console output style while running tests:

  - `classic`: classic pytest output.

  - `progress`: like classic pytest output, but with a progress indicator.

  - `progress-even-when-capture-no`: allows the use of the progress indicator even when `capture=no`.

  - `count`: like progress, but shows progress as the number of tests completed instead of a percent.

  - `times`: show tests duration.

  The default is `progress`, but you can fallback to `classic` if you prefer or the new mode is causing unexpected problems:

  toml

      [pytest]
      console_output_style = "classic"

  ini

      [pytest]
      console_output_style = classic

disable_test_id_escaping_and_forfeit_all_rights_to_community_support

  Added in version 4.4.

  pytest by default escapes any non-ascii characters used in unicode strings for the parametrization because it has several downsides. If however you would like to use unicode strings in parametrization and see them in the terminal as is (non-escaped), use this option in your configuration file:

  toml

      [pytest]
      disable_test_id_escaping_and_forfeit_all_rights_to_community_support = true

  ini

      [pytest]
      disable_test_id_escaping_and_forfeit_all_rights_to_community_support = true

  Keep in mind however that this might cause unwanted side effects and even bugs depending on the OS used and plugins currently installed, so use it at your own risk.

  Default: `False`.

  See @pytest.mark.parametrize: parametrizing test functions.

doctest_encoding

  Default encoding to use to decode text files with docstrings. See how pytest handles doctests.

doctest_optionflags

  One or more doctest flag names from the standard `doctest` module. See how pytest handles doctests.

empty_parameter_set_mark

  Allows to pick the action for empty parametersets in parameterization

  - `skip` skips tests with an empty parameterset (default)

  - `xfail` marks tests with an empty parameterset as xfail(run=False)

  - `fail_at_collect` raises an exception if parametrize collects an empty parameter set

  toml

      [pytest]
      empty_parameter_set_mark = "xfail"

  ini

      [pytest]
      empty_parameter_set_mark = xfail

  Note

  The default value of this option is planned to change to `xfail` in future releases as this is considered less error prone, see #3155 for more details.

enable_assertion_pass_hook

  Enables the `pytest_assertion_pass` hook. Make sure to delete any previously generated `.pyc` cache files.

  toml

      [pytest]
      enable_assertion_pass_hook = true

  ini

      [pytest]
      enable_assertion_pass_hook = true

faulthandler_exit_on_timeout

  Exit the pytest process after the per-test timeout is reached by passing `exit=True` to the `faulthandler.dump_traceback_later()` function. This is particularly useful to avoid wasting CI resources for test suites that are prone to putting the main Python interpreter into a deadlock state.

  This option is set to 'false' by default.

  toml

      [pytest]
      faulthandler_timeout = 5
      faulthandler_exit_on_timeout = true

  ini

      [pytest]
      faulthandler_timeout = 5
      faulthandler_exit_on_timeout = true

faulthandler_timeout

  Dumps the tracebacks of all threads if a test takes longer than `X` seconds to run (including fixture setup and teardown). Implemented using the `faulthandler.dump_traceback_later()` function, so all caveats there apply.

  toml

      [pytest]
      faulthandler_timeout = 5

  ini

      [pytest]
      faulthandler_timeout = 5

  For more information please refer to Fault Handler. For more information please refer to Fault Handler.

filterwarnings

  Sets a list of filters and actions that should be taken for matched warnings. By default all warnings emitted during the test session will be displayed in a summary at the end of the test session.

  toml

      [pytest]
      filterwarnings = ["error", "ignore::DeprecationWarning"]

  ini

      [pytest]
      filterwarnings =
          error
          ignore::DeprecationWarning

  This tells pytest to ignore deprecation warnings and turn all other warnings into errors. For more information please refer to How to capture warnings.

junit_duration_report

  Added in version 4.1.

  Configures how durations are recorded into the JUnit XML report:

  - `total` (the default): duration times reported include setup, call, and teardown times.

  - `call`: duration times reported include only call times, excluding setup and teardown.

  toml

      [pytest]
      junit_duration_report = "call"

  ini

      [pytest]
      junit_duration_report = call

junit_family

  Added in version 4.2.

  Changed in version 6.1: Default changed to `xunit2`.

  Configures the format of the generated JUnit XML file. The possible options are:

  - `xunit1` (or `legacy`): produces old style output, compatible with the xunit 1.0 format.

  - `xunit2`: produces xunit 2.0 style output, which should be more compatible with latest Jenkins versions. This is the default.

  toml

      [pytest]
      junit_family = "xunit2"

  ini

      [pytest]
      junit_family = xunit2

junit_log_passing_tests

  Added in version 4.6.

  If `junit_logging != "no"`, configures if the captured output should be written to the JUnit XML file for passing tests. Default is `True`.

  toml

      [pytest]
      junit_log_passing_tests = false

  ini

      [pytest]
      junit_log_passing_tests = False

junit_logging

  Added in version 3.5.

  Changed in version 5.4: `log`, `all`, `out-err` options added.

  Configures if captured output should be written to the JUnit XML file. Valid values are:

  - `log`: write only `logging` captured output.

  - `system-out`: write captured `stdout` contents.

  - `system-err`: write captured `stderr` contents.

  - `out-err`: write both captured `stdout` and `stderr` contents.

  - `all`: write captured `logging`, `stdout` and `stderr` contents.

  - `no` (the default): no captured output is written.

  toml

      [pytest]
      junit_logging = "system-out"

  ini

      [pytest]
      junit_logging = system-out

junit_suite_name

  To set the name of the root test suite xml item, you can configure the `junit_suite_name` option in your config file:

  toml

      [pytest]
      junit_suite_name = "my_suite"

  ini

      [pytest]
      junit_suite_name = my_suite

log_auto_indent

  Allow selective auto-indentation of multiline log messages.

  Supports command line option `--log-auto-indent=[value]` and config option `log_auto_indent = [value]` to set the auto-indentation behavior for all logging.

  `[value]` can be:

    - True or "On" - Dynamically auto-indent multiline log messages

    - False or "Off" or 0 - Do not auto-indent multiline log messages (the default behavior)

    - [positive integer] - auto-indent multiline log messages by [value] spaces

  toml

      [pytest]
      log_auto_indent = false

  ini

      [pytest]
      log_auto_indent = false

  Supports passing kwarg `extra={"auto_indent": [value]}` to calls to `logging.log()` to specify auto-indentation behavior for a specific entry in the log. `extra` kwarg overrides the value specified on the command line or in the config.

log_cli

  Enable log display during test run (also known as "live logging"). The default is `False`.

  toml

      [pytest]
      log_cli = true

  ini

      [pytest]
      log_cli = true

log_cli_date_format

  Sets a `time.strftime()`-compatible string that will be used when formatting dates for live logging.

  toml

      [pytest]
      log_cli_date_format = "%Y-%m-%d %H:%M:%S"

  ini

      [pytest]
      log_cli_date_format = %Y-%m-%d %H:%M:%S

  For more information, see Live Logs.

log_cli_format

  Sets a `logging`-compatible string used to format live logging messages.

  toml

      [pytest]
      log_cli_format = "%(asctime)s %(levelname)s %(message)s"

  ini

      [pytest]
      log_cli_format = %(asctime)s %(levelname)s %(message)s

  For more information, see Live Logs.

log_cli_level

  Sets the minimum log message level that should be captured for live logging. The integer value or the names of the levels can be used.

  toml

      [pytest]
      log_cli_level = "INFO"

  ini

      [pytest]
      log_cli_level = INFO

  For more information, see Live Logs.

log_date_format

  Sets a `time.strftime()`-compatible string that will be used when formatting dates for logging capture.

  toml

      [pytest]
      log_date_format = "%Y-%m-%d %H:%M:%S"

  ini

      [pytest]
      log_date_format = %Y-%m-%d %H:%M:%S

  For more information, see How to manage logging.

log_file

  Sets a file name relative to the current working directory where log messages should be written to, in addition to the other logging facilities that are active.

  toml

      [pytest]
      log_file = "logs/pytest-logs.txt"

  ini

      [pytest]
      log_file = logs/pytest-logs.txt

  For more information, see How to manage logging.

log_file_date_format

  Sets a `time.strftime()`-compatible string that will be used when formatting dates for the logging file.

  toml

      [pytest]
      log_file_date_format = "%Y-%m-%d %H:%M:%S"

  ini

      [pytest]
      log_file_date_format = %Y-%m-%d %H:%M:%S

  For more information, see How to manage logging.

log_file_format

  Sets a `logging`-compatible string used to format logging messages redirected to the logging file.

  toml

      [pytest]
      log_file_format = "%(asctime)s %(levelname)s %(message)s"

  ini

      [pytest]
      log_file_format = %(asctime)s %(levelname)s %(message)s

  For more information, see How to manage logging.

log_file_level

  Sets the minimum log message level that should be captured for the logging file. The integer value or the names of the levels can be used.

  toml

      [pytest]
      log_file_level = "INFO"

  ini

      [pytest]
      log_file_level = INFO

  For more information, see How to manage logging.

log_file_mode

  Sets the mode that the logging file is opened with. The options are `"w"` to recreate the file (the default) or `"a"` to append to the file.

  toml

      [pytest]
      log_file_mode = "a"

  ini

      [pytest]
      log_file_mode = a

  For more information, see How to manage logging.

log_format

  Sets a `logging`-compatible string used to format captured logging messages.

  toml

      [pytest]
      log_format = "%(asctime)s %(levelname)s %(message)s"

  ini

      [pytest]
      log_format = %(asctime)s %(levelname)s %(message)s

  For more information, see How to manage logging.

log_level

  Sets the minimum log message level that should be captured for logging capture. The integer value or the names of the levels can be used.

  toml

      [pytest]
      log_level = "INFO"

  ini

      [pytest]
      log_level = INFO

  For more information, see How to manage logging.

markers

  When the `strict_markers` configuration option is set, only known markers - defined in code by core pytest or some plugin - are allowed.

  You can list additional markers in this setting to add them to the whitelist, in which case you probably want to set `strict_markers` to `true` to avoid future regressions:

  toml

      [pytest]
      addopts = ["--strict-markers"]
      markers = ["slow", "serial"]

  ini

      [pytest]
      strict_markers = true
      markers =
          slow
          serial

minversion

  Specifies a minimal pytest version required for running tests.

  toml

      [pytest]
      minversion = 3.0  # will fail if we run with pytest-2.8

  ini

      [pytest]
      minversion = 3.0  # will fail if we run with pytest-2.8

norecursedirs

  Set the directory basename patterns to avoid when recursing for test discovery. The individual (fnmatch-style) patterns are applied to the basename of a directory to decide if to recurse into it. Pattern matching characters:

      *       matches everything
      ?       matches any single character
      [seq]   matches any character in seq
      [!seq]  matches any char not in seq

  Default patterns are `'*.egg'`, `'.*'`, `'_darcs'`, `'build'`, `'CVS'`, `'dist'`, `'node_modules'`, `'venv'`, `'{arch}'`. Setting a `norecursedirs` replaces the default. Here is an example of how to avoid certain directories:

  toml

      [pytest]
      norecursedirs = [".svn", "_build", "tmp*"]

  ini

      [pytest]
      norecursedirs = .svn _build tmp*

  This would tell `pytest` to not look into typical subversion or sphinx-build directories or into any `tmp` prefixed directory.

  Additionally, `pytest` will attempt to intelligently identify and ignore a virtualenv. Any directory deemed to be the root of a virtual environment will not be considered during test collection unless `--collect-in-virtualenv` is given. Note also that `norecursedirs` takes precedence over `--collect-in-virtualenv`; e.g. if you intend to run tests in a virtualenv with a base directory that matches `'.*'` you must override `norecursedirs` in addition to using the `--collect-in-virtualenv` flag.

python_classes

  One or more name prefixes or glob-style patterns determining which classes are considered for test collection. Search for multiple glob patterns by adding a space between patterns. By default, pytest will consider any class prefixed with `Test` as a test collection. Here is an example of how to collect tests from classes that end in `Suite`:

  toml

      [pytest]
      python_classes = ["*Suite"]

  ini

      [pytest]
      python_classes = *Suite

  Note that `unittest.TestCase` derived classes are always collected regardless of this option, as `unittest`'s own collection framework is used to collect those tests.

python_files

  One or more Glob-style file patterns determining which python files are considered as test modules. Search for multiple glob patterns by adding a space between patterns:

  toml

      [pytest]
      python_files = ["test_*.py", "check_*.py", "example_*.py"]

  ini

      [pytest]
      python_files = test_*.py check_*.py example_*.py

  Or one per line:

      [pytest]
      python_files =
          test_*.py
          check_*.py
          example_*.py

  By default, files matching `test_*.py` and `*_test.py` will be considered test modules.

python_functions

  One or more name prefixes or glob-patterns determining which test functions and methods are considered tests. Search for multiple glob patterns by adding a space between patterns. By default, pytest will consider any function prefixed with `test` as a test. Here is an example of how to collect test functions and methods that end in `_test`:

  toml

      [pytest]
      python_functions = ["*_test"]

  ini

      [pytest]
      python_functions = *_test

  Note that this has no effect on methods that live on a `unittest.TestCase` derived class, as `unittest`'s own collection framework is used to collect those tests.

  See Changing naming conventions for more detailed examples.

pythonpath

  Sets list of directories that should be added to the python search path. Directories will be added to the head of `sys.path`. Similar to the `PYTHONPATH` environment variable, the directories will be included in where Python will look for imported modules. Paths are relative to the rootdir directory. Directories remain in path for the duration of the test session.

  toml

      [pytest]
      pythonpath = ["src1", "src2"]

  ini

      [pytest]
      pythonpath = src1 src2

required_plugins

  A space separated list of plugins that must be present for pytest to run. Plugins can be listed with or without version specifiers directly following their name. Whitespace between different version specifiers is not allowed. If any one of the plugins is not found, emit an error.

  toml

      [pytest]
      required_plugins = ["pytest-django>=3.0.0,<4.0.0", "pytest-html", "pytest-xdist>=1.0.0"]

  ini

      [pytest]
      required_plugins = pytest-django>=3.0.0,<4.0.0 pytest-html pytest-xdist>=1.0.0

strict

  If set to `true`, enable "strict mode", which enables the following options:

  - `strict_config`

  - `strict_markers`

  - `strict_parametrization_ids`

  - `strict_xfail`

  Plugins may also enable their own strictness options.

  If you explicitly set an individual strictness option, it takes precedence over `strict`.

  Note

  If pytest adds new strictness options in the future, they will also be enabled in strict mode. Therefore, you should only enable strict mode if you use a pinned/locked version of pytest, or if you want to proactively adopt new strictness options as they are added.

  toml

      [pytest]
      strict = true

  ini

      [pytest]
      strict = true

  Added in version 9.0.

strict_config

  If set to `true`, any warnings encountered while parsing the `pytest` section of the configuration file will raise errors.

  toml

      [pytest]
      strict_config = true

  ini

      [pytest]
      strict_config = true

  You can also enable this option via the `strict` option.

strict_markers

  If set to `true`, markers not registered in the `markers` section of the configuration file will raise errors.

  toml

      [pytest]
      strict_markers = true

  ini

      [pytest]
      strict_markers = true

  You can also enable this option via the `strict` option.

strict_parametrization_ids

  If set to `true`, pytest emits an error if it detects non-unique parameter set IDs.

  If not set (the default), pytest automatically handles this by adding `0`, `1`, ... to duplicate IDs, making them unique.

  toml

      [pytest]
      strict_parametrization_ids = true

  ini

      [pytest]
      strict_parametrization_ids = true

  You can also enable this option via the `strict` option.

  For example,

      import pytest

      @pytest.mark.parametrize("letter", ["a", "a"])
      def test_letter_is_ascii(letter):
          assert letter.isascii()

  will emit an error because both cases (parameter sets) have the same auto-generated ID "a".

  To fix the error, if you decide to keep the duplicates, explicitly assign unique IDs:

      import pytest

      @pytest.mark.parametrize("letter", ["a", "a"], ids=["a0", "a1"])
      def test_letter_is_ascii(letter):
          assert letter.isascii()

  See `parametrize` and `pytest.param()` for other ways to set IDs.

strict_xfail

  If set to `true`, tests marked with `@pytest.mark.xfail` that actually succeed will by default fail the test suite. For more information, see strict parameter.

  toml

      [pytest]
      strict_xfail = true

  ini

      [pytest]
      strict_xfail = true

  You can also enable this option via the `strict` option.

  Changed in version 9.0: Renamed from `xfail_strict` to `strict_xfail`. `xfail_strict` is accepted as an alias for `strict_xfail`.

testpaths

  Sets list of directories that should be searched for tests when no specific directories, files or test ids are given in the command line when executing pytest from the rootdir directory. File system paths may use shell-style wildcards, including the recursive `**` pattern.

  Useful when all project tests are in a known location to speed up test collection and to avoid picking up undesired tests by accident.

  toml

      [pytest]
      testpaths = ["testing", "doc"]

  ini

      [pytest]
      testpaths = testing doc

  This configuration means that executing:

      pytest

  has the same practical effects as executing:

      pytest testing doc

tmp_path_retention_count

  How many sessions should we keep the `tmp_path` directories, according to `tmp_path_retention_policy`.

  toml

      [pytest]
      tmp_path_retention_count = "3"

  ini

      [pytest]
      tmp_path_retention_count = 3

  Default: `3`

tmp_path_retention_policy

  Controls which directories created by the `tmp_path` fixture are kept around, based on test outcome.

  > - `all`: retains directories for all tests, regardless of the outcome.

  > - `failed`: retains directories only for tests with outcome `error` or `failed`.

  > - `none`: directories are always removed after each test ends, regardless of the outcome.

  toml

      [pytest]
      tmp_path_retention_policy = "all"

  ini

      [pytest]
      tmp_path_retention_policy = all

  Default: `all`

truncation_limit_chars

  Controls maximum number of characters to truncate assertion message contents.

  Setting value to `0` disables the character limit for truncation.

  toml

      [pytest]
      truncation_limit_chars = 640

  ini

      [pytest]
      truncation_limit_chars = 640

  pytest truncates the assert messages to a certain limit by default to prevent comparison with large data to overload the console output.

  Default: `640`

  Note

  If pytest detects it is running on CI, truncation is disabled automatically.

truncation_limit_lines

  Controls maximum number of linesto truncate assertion message contents.

  Setting value to `0` disables the lines limit for truncation.

  toml

      [pytest]
      truncation_limit_lines = 8

  ini

      [pytest]
      truncation_limit_lines = 8

  pytest truncates the assert messages to a certain limit by default to prevent comparison with large data to overload the console output.

  Default: `8`

  Note

  If pytest detects it is running on CI, truncation is disabled automatically.

usefixtures

  List of fixtures that will be applied to all test functions; this is semantically the same to apply the `@pytest.mark.usefixtures` marker to all test functions.

  toml

      [pytest]
      usefixtures = ["clean_db"]

  ini

      [pytest]
      usefixtures =
          clean_db

verbosity_assertions

  Set a verbosity level specifically for assertion related output, overriding the application wide level.

  toml

      [pytest]
      verbosity_assertions = "2"

  ini

      [pytest]
      verbosity_assertions = 2

  If not set, defaults to application wide verbosity level (via the `-v` command-line option). A special value of `"auto"` can be used to explicitly use the global verbosity level.

verbosity_subtests

  Set the verbosity level specifically for passed subtests.

  toml

      [pytest]
      verbosity_subtests = "1"

  ini

      [pytest]
      verbosity_subtests = 1

  A value of `1` or higher will show output for passed subtests (failed subtests are always reported). Passed subtests output can be suppressed with the value `0`, which overwrites the `-v` command-line option.

  If not set, defaults to application wide verbosity level (via the `-v` command-line option). A special value of `"auto"` can be used to explicitly use the global verbosity level.

  See also: How to use subtests.

verbosity_test_cases

  Set a verbosity level specifically for test case execution related output, overriding the application wide level.

  toml

      [pytest]
      verbosity_test_cases = "2"

  ini

      [pytest]
      verbosity_test_cases = 2

  If not set, defaults to application wide verbosity level (via the `-v` command-line option). A special value of `"auto"` can be used to explicitly use the global verbosity level.

## Command-line Flags

This section documents all command-line options provided by pytest's core plugins.

Note

External plugins can add their own command-line options. This reference documents only the options from pytest's core plugins. To see all available options including those from installed plugins, run `pytest --help`.

### Test Selection

-k EXPRESSION

  Only run tests which match the given substring expression. An expression is a Python evaluable expression where all names are substring-matched against test names and their parent classes.

  Examples:

      pytest -k "test_method or test_other"  # matches names containing 'test_method' OR 'test_other'
      pytest -k "not test_method"            # matches names NOT containing 'test_method'
      pytest -k "not test_method and not test_other"  # excludes both

  The matching is case-insensitive. Keywords are also matched to classes and functions containing extra names in their `extra_keyword_matches` set.

  See Specifying which tests to run for more information and examples.

-m MARKEXPR

  Only run tests matching given mark expression. Supports `and`, `or`, and `not` operators.

  Examples:

      pytest -m slow                  # run tests marked with @pytest.mark.slow
      pytest -m "not slow"            # run tests NOT marked slow
      pytest -m "mark1 and not mark2" # run tests marked mark1 but not mark2

  See How to mark test functions with attributes for more information on markers.

--markers

  Show all available markers (builtin, plugin, and per-project markers defined in configuration).

### Test Execution Control

-x, --exitfirst

  Exit instantly on first error or failed test.

--maxfail=NUM

  Exit after first `num` failures or errors. Useful for CI environments where you want to fail fast but see a few failures.

--last-failed, --lf

  Rerun only the tests that failed at the last run. If no tests failed (or no cached data exists), all tests are run. See also `cache_dir` and How to re-run failed tests and maintain state between test runs.

--failed-first, --ff

  Run all tests, but run the last failures first. This may re-order tests and thus lead to repeated fixture setup/teardown.

--new-first, --nf

  Run tests from new files first, then the rest of the tests sorted by file modification time.

--stepwise, --sw

  Exit on test failure and continue from last failing test next time. Useful for fixing multiple test failures one at a time.

  See Stepwise for more information.

--stepwise-skip, --sw-skip

  Ignore the first failing test but stop on the next failing test. Implicitly enables `--stepwise`.

--stepwise-reset, --sw-reset

  Resets stepwise state, restarting the stepwise workflow. Implicitly enables `--stepwise`.

--last-failed-no-failures, --lfnf

  With `--last-failed`, determines whether to execute tests when there are no previously known failures or when no cached `lastfailed` data was found.

  - `all` (default): runs the full test suite again

  - `none`: just emits a message about no known failures and exits successfully

--runxfail

  Report the results of xfail tests as if they were not marked. Useful for debugging xfailed tests. See XFail: mark test functions as expected to fail.

### Collection

--collect-only, --co

  Only collect tests, don't execute them. Shows which tests would be collected and run.

--pyargs

  Try to interpret all arguments as Python packages. Useful for running tests of installed packages:

      pytest --pyargs pkg.testing

--ignore=PATH

  Ignore path during collection (multi-allowed). Can be specified multiple times.

--ignore-glob=PATTERN

  Ignore path pattern during collection (multi-allowed). Supports glob patterns.

--deselect=NODEID_PREFIX

  Deselect item (via node id prefix) during collection (multi-allowed).

--confcutdir=DIR

  Only load `conftest.py` files relative to specified directory.

--noconftest

  Don't load any `conftest.py` files.

--keep-duplicates

  Keep duplicate tests. By default, pytest removes duplicate test items.

--collect-in-virtualenv

  Don't ignore tests in a local virtualenv directory. By default, pytest skips tests in virtualenv directories.

--continue-on-collection-errors

  Force test execution even if collection errors occur.

--import-mode

  Prepend/append to sys.path when importing test modules and conftest files.

  - `prepend` (default): prepend to sys.path

  - `append`: append to sys.path

  - `importlib`: use importlib to import test modules

  See pytest import mechanisms and sys.path/PYTHONPATH for more information.

### Fixtures

--fixtures, --funcargs

  Show available fixtures, sorted by plugin appearance. Fixtures with leading `_` are only shown with `--verbose`.

--fixtures-per-test

  Show fixtures per test.

--setup-only

  Only setup fixtures, do not execute tests. See How to use fixtures.

--setup-show

  Show setup of fixtures while executing tests.

--setup-plan

  Show what fixtures and tests would be executed but don't execute anything.

### Debugging

--pdb

  Start the interactive Python debugger on errors or KeyboardInterrupt. See Using python:library/pdb with pytest.

--pdbcls=MODULENAME:CLASSNAME

  Specify a custom interactive Python debugger for use with `--pdb`.

  Example:

      pytest --pdbcls=IPython.terminal.debugger:TerminalPdb

--trace

  Immediately break when running each test.

  See Dropping to pdb at the start of a test for more information.

--full-trace

  Don't cut any tracebacks (default is to cut).

  See Modifying Python traceback printing for more information.

--debug, --debug=DEBUG_FILE_NAME

  Store internal tracing debug information in this log file. This file is opened with `'w'` and truncated as a result, care advised. Default file name if not specified: `pytestdebug.log`.

--trace-config

  Trace considerations of conftest.py files.

### Output and Reporting

-v, --verbose

  Increase verbosity. Can be specified multiple times (e.g., `-vv`) for even more verbose output.

  See Fine-grained verbosity for fine-grained control over verbosity.

-q, --quiet

  Decrease verbosity.

--verbosity=NUM

  Set verbosity level explicitly. Default: 0.

-r CHARS

  Show extra test summary info as specified by chars:

  - `f`: failed

  - `E`: error

  - `s`: skipped

  - `x`: xfailed

  - `X`: xpassed

  - `p`: passed

  - `P`: passed with output

  - `a`: all except passed (p/P)

  - `A`: all

  - `w`: warnings (enabled by default)

  - `N`: resets the list

  Default: `'fE'`

  Examples:

      pytest -rA           # show all outcomes
      pytest -rfE          # show only failed and errors (default)
      pytest -rfs          # show failed and skipped

  See Producing a detailed summary report for more information.

--no-header

  Disable header.

--no-summary

  Disable summary.

--no-fold-skipped

  Do not fold skipped tests in short summary.

--force-short-summary

  Force condensed summary output regardless of verbosity level.

-l, --showlocals

  Show locals in tracebacks (disabled by default).

--no-showlocals

  Hide locals in tracebacks (negate `--showlocals` passed through addopts).

--tb=STYLE

  Traceback print mode:

  - `auto`: intelligent traceback formatting (default)

  - `long`: exhaustive, informative traceback formatting

  - `short`: shorter traceback format

  - `line`: only the failing line

  - `native`: Python's standard traceback

  - `no`: no traceback

  See Modifying Python traceback printing for examples.

--xfail-tb

  Show tracebacks for xfail (as long as `--tb` != `no`).

--show-capture

  Controls how captured stdout/stderr/log is shown on failed tests.

  - `no`: don't show captured output

  - `stdout`: show captured stdout

  - `stderr`: show captured stderr

  - `log`: show captured logging

  - `all` (default): show all captured output

--color=WHEN

  Color terminal output:

  - `yes`: always use color

  - `no`: never use color

  - `auto` (default): use color if terminal supports it

--code-highlight={yes,no}

  Whether code should be highlighted (only if `--color` is also enabled). Default: `yes`.

--pastebin=MODE

  Send failed|all info to bpaste.net pastebin service.

--durations=NUM

  Show N slowest setup/test durations (N=0 for all). See Profiling test execution duration.

--durations-min=NUM

  Minimal duration in seconds for inclusion in slowest list. Default: 0.005 (or 0.0 if `-vv` is given).

### Output Capture

--capture=METHOD

  Per-test capturing method:

  - `fd`: capture at file descriptor level (default)

  - `sys`: capture at sys level

  - `no`: don't capture output

  - `tee-sys`: capture but also show output on terminal

  See How to capture stdout/stderr output.

-s

  Shortcut for `--capture=no`.

### JUnit XML

--junit-xml=PATH, --junitxml=PATH

  Create junit-xml style report file at given path.

--junit-prefix=STR, --junitprefix=STR

  Prepend prefix to classnames in junit-xml output.

### Cache

--cache-show[=PATTERN]

  Show cache contents, don't perform collection or tests. Default glob pattern: `'*'`.

--cache-clear

  Remove all cache contents at start of test run. See How to re-run failed tests and maintain state between test runs.

### Warnings

--disable-pytest-warnings, --disable-warnings

  Disable warnings summary.

-W WARNING, --pythonwarnings=WARNING

  Set which warnings to report, see `-W` option of Python itself. Can be specified multiple times.

### Doctest

--doctest-modules

  Run doctests in all .py modules.

  See How to run doctests for more information on using doctests with pytest.

--doctest-report

  Choose another output format for diffs on doctest failure:

  - `none`

  - `cdiff`

  - `ndiff`

  - `udiff`

  - `only_first_failure`

--doctest-glob=PATTERN

  Doctests file matching pattern. Default: `test*.txt`.

--doctest-ignore-import-errors

  Ignore doctest collection errors.

--doctest-continue-on-failure

  For a given doctest, continue to run after the first failure.

### Configuration

-c FILE, --config-file=FILE

  Load configuration from `FILE` instead of trying to locate one of the implicit configuration files.

--rootdir=ROOTDIR

  Define root directory for tests. Can be relative path: `'root_dir'`, `'./root_dir'`, `'root_dir/another_dir/'`; absolute path: `'/home/user/root_dir'`; path with variables: `'$HOME/root_dir'`.

--basetemp=DIR

  Base temporary directory for this test run. Warning: this directory is removed if it exists.

  See Temporary directory location and retention for more information.

-o OPTION=VALUE, --override-ini=OPTION=VALUE

  Override configuration option with `option=value` style. Can be specified multiple times.

  Example:

      pytest -o strict_xfail=true -o cache_dir=cache

--strict-config

  Enables the `strict_config` option.

--strict-markers

  Enables the `strict_markers` option.

--strict

  Enables the `strict` option (which enables all strictness options).

--assert=MODE

  Control assertion debugging tools:

  - `plain`: performs no assertion debugging

  - `rewrite` (default): rewrites assert statements in test modules on import to provide assert expression information

### Logging

See How to manage logging for a guide on using these flags.

--log-level=LEVEL

  Level of messages to catch/display. Not set by default, so it depends on the root/parent log handler's effective level, where it is `WARNING` by default.

--log-format=FORMAT

  Log format used by the logging module.

--log-date-format=FORMAT

  Log date format used by the logging module.

--log-cli-level=LEVEL

  CLI logging level. See Live Logs.

--log-cli-format=FORMAT

  Log format used by the logging module for CLI output.

--log-cli-date-format=FORMAT

  Log date format used by the logging module for CLI output.

--log-file=PATH

  Path to a file when logging will be written to.

--log-file-mode

  Log file open mode:

  - `w` (default): recreate the file

  - `a`: append to the file

--log-file-level=LEVEL

  Log file logging level.

--log-file-format=FORMAT

  Log format used by the logging module for the log file.

--log-file-date-format=FORMAT

  Log date format used by the logging module for the log file.

--log-auto-indent=VALUE

  Auto-indent multiline messages passed to the logging module. Accepts `true|on`, `false|off` or an integer.

--log-disable=LOGGER

  Disable a logger by name. Can be passed multiple times.

### Plugin and Extension Management

-p NAME

  Early-load given plugin module name or entry point (multi-allowed). To avoid loading of plugins, use the `no:` prefix, e.g. `no:doctest`. See also `--disable-plugin-autoload`.

--disable-plugin-autoload

  Disable plugin auto-loading through entry point packaging metadata. Only plugins explicitly specified in `-p` or env var `PYTEST_PLUGINS` will be loaded.

### Version and Help

-V, --version

  Display pytest version and information about plugins. When given twice, also display information about plugins.

-h, --help

  Show help message and configuration info.

### Complete Help Output

All the command-line flags can also be obtained by running `pytest --help`:

    $ pytest --help
    usage: pytest [options] [file_or_dir] [file_or_dir] [...]

    positional arguments:
      file_or_dir

    general:
      -k EXPRESSION         Only run tests which match the given substring
                            expression. An expression is a Python evaluable
                            expression where all names are substring-matched
                            against test names and their parent classes.
                            Example: -k 'test_method or test_other' matches all
                            test functions and classes whose name contains
                            'test_method' or 'test_other', while -k 'not
                            test_method' matches those that don't contain
                            'test_method' in their names. -k 'not test_method
                            and not test_other' will eliminate the matches.
                            Additionally keywords are matched to classes and
                            functions containing extra names in their
                            'extra_keyword_matches' set, as well as functions
                            which have names assigned directly to them. The
                            matching is case-insensitive.
      -m MARKEXPR           Only run tests matching given mark expression. For
                            example: -m 'mark1 and not mark2'.
      --markers             show markers (builtin, plugin and per-project ones).
      -x, --exitfirst       Exit instantly on first error or failed test
      --maxfail=num         Exit after first num failures or errors
      --strict-config       Enables the strict_config option
      --strict-markers      Enables the strict_markers option
      --strict              Enables the strict option
      --fixtures, --funcargs
                            Show available fixtures, sorted by plugin appearance
                            (fixtures with leading '_' are only shown with '-v')
      --fixtures-per-test   Show fixtures per test
      --pdb                 Start the interactive Python debugger on errors or
                            KeyboardInterrupt
      --pdbcls=modulename:classname
                            Specify a custom interactive Python debugger for use
                            with --pdb.For example:
                            --pdbcls=IPython.terminal.debugger:TerminalPdb
      --trace               Immediately break when running each test
      --capture=method      Per-test capturing method: one of fd|sys|no|tee-sys
      -s                    Shortcut for --capture=no
      --runxfail            Report the results of xfail tests as if they were
                            not marked
      --lf, --last-failed   Rerun only the tests that failed at the last run (or
                            all if none failed)
      --ff, --failed-first  Run all tests, but run the last failures first. This
                            may re-order tests and thus lead to repeated fixture
                            setup/teardown.
      --nf, --new-first     Run tests from new files first, then the rest of the
                            tests sorted by file mtime
      --cache-show=[CACHESHOW]
                            Show cache contents, don't perform collection or
                            tests. Optional argument: glob (default: '*').
      --cache-clear         Remove all cache contents at start of test run
      --lfnf, --last-failed-no-failures={all,none}
                            With ``--lf``, determines whether to execute tests
                            when there are no previously (known) failures or
                            when no cached ``lastfailed`` data was found.
                            ``all`` (the default) runs the full test suite
                            again. ``none`` just emits a message about no known
                            failures and exits successfully.
      --sw, --stepwise      Exit on test failure and continue from last failing
                            test next time
      --sw-skip, --stepwise-skip
                            Ignore the first failing test but stop on the next
                            failing test. Implicitly enables --stepwise.
      --sw-reset, --stepwise-reset
                            Resets stepwise state, restarting the stepwise
                            workflow. Implicitly enables --stepwise.

    Reporting:
      --durations=N         Show N slowest setup/test durations (N=0 for all)
      --durations-min=N     Minimal duration in seconds for inclusion in slowest
                            list. Default: 0.005 (or 0.0 if -vv is given).
      -v, --verbose         Increase verbosity
      --no-header           Disable header
      --no-summary          Disable summary
      --no-fold-skipped     Do not fold skipped tests in short summary.
      --force-short-summary
                            Force condensed summary output regardless of
                            verbosity level.
      -q, --quiet           Decrease verbosity
      --verbosity=VERBOSE   Set verbosity. Default: 0.
      -r chars              Show extra test summary info as specified by chars:
                            (f)ailed, (E)rror, (s)kipped, (x)failed, (X)passed,
                            (p)assed, (P)assed with output, (a)ll except passed
                            (p/P), or (A)ll. (w)arnings are enabled by default
                            (see --disable-warnings), 'N' can be used to reset
                            the list. (default: 'fE').
      --disable-warnings, --disable-pytest-warnings
                            Disable warnings summary
      -l, --showlocals      Show locals in tracebacks (disabled by default)
      --no-showlocals       Hide locals in tracebacks (negate --showlocals
                            passed through addopts)
      --tb=style            Traceback print mode
                            (auto/long/short/line/native/no)
      --xfail-tb            Show tracebacks for xfail (as long as --tb != no)
      --show-capture={no,stdout,stderr,log,all}
                            Controls how captured stdout/stderr/log is shown on
                            failed tests. Default: all.
      --full-trace          Don't cut any tracebacks (default is to cut)
      --color=color         Color terminal output (yes/no/auto)
      --code-highlight={yes,no}
                            Whether code should be highlighted (only if --color
                            is also enabled). Default: yes.
      --pastebin=mode       Send failed|all info to bpaste.net pastebin service
      --junitxml, --junit-xml=path
                            Create junit-xml style report file at given path
      --junitprefix, --junit-prefix=str
                            Prepend prefix to classnames in junit-xml output

    pytest-warnings:
      -W, --pythonwarnings PYTHONWARNINGS
                            Set which warnings to report, see -W option of
                            Python itself

    collection:
      --collect-only, --co  Only collect tests, don't execute them
      --pyargs              Try to interpret all arguments as Python packages
      --ignore=path         Ignore path during collection (multi-allowed)
      --ignore-glob=path    Ignore path pattern during collection (multi-
                            allowed)
      --deselect=nodeid_prefix
                            Deselect item (via node id prefix) during collection
                            (multi-allowed)
      --confcutdir=dir      Only load conftest.py's relative to specified dir
      --noconftest          Don't load any conftest.py files
      --keep-duplicates     Keep duplicate tests
      --collect-in-virtualenv
                            Don't ignore tests in a local virtualenv directory
      --continue-on-collection-errors
                            Force test execution even if collection errors occur
      --import-mode={prepend,append,importlib}
                            Prepend/append to sys.path when importing test
                            modules and conftest files. Default: prepend.
      --doctest-modules     Run doctests in all .py modules
      --doctest-report={none,cdiff,ndiff,udiff,only_first_failure}
                            Choose another output format for diffs on doctest
                            failure
      --doctest-glob=pat    Doctests file matching pattern, default: test*.txt
      --doctest-ignore-import-errors
                            Ignore doctest collection errors
      --doctest-continue-on-failure
                            For a given doctest, continue to run after the first
                            failure

    test session debugging and configuration:
      -c, --config-file FILE
                            Load configuration from `FILE` instead of trying to
                            locate one of the implicit configuration files.
      --rootdir=ROOTDIR     Define root directory for tests. Can be relative
                            path: 'root_dir', './root_dir',
                            'root_dir/another_dir/'; absolute path:
                            '/home/user/root_dir'; path with variables:
                            '$HOME/root_dir'.
      --basetemp=dir        Base temporary directory for this test run.
                            (Warning: this directory is removed if it exists.)
      -V, --version         Display pytest version and information about
                            plugins. When given twice, also display information
                            about plugins.
      -h, --help            Show help message and configuration info
      -p name               Early-load given plugin module name or entry point
                            (multi-allowed). To avoid loading of plugins, use
                            the `no:` prefix, e.g. `no:doctest`. See also
                            --disable-plugin-autoload.
      --disable-plugin-autoload
                            Disable plugin auto-loading through entry point
                            packaging metadata. Only plugins explicitly
                            specified in -p or env var PYTEST_PLUGINS will be
                            loaded.
      --trace-config        Trace considerations of conftest.py files
      --debug=[DEBUG_FILE_NAME]
                            Store internal tracing debug information in this log
                            file. This file is opened with 'w' and truncated as
                            a result, care advised. Default: pytestdebug.log.
      -o, --override-ini OVERRIDE_INI
                            Override configuration option with "option=value"
                            style, e.g. `-o strict_xfail=True -o
                            cache_dir=cache`.
      --assert=MODE         Control assertion debugging tools.
                            'plain' performs no assertion debugging.
                            'rewrite' (the default) rewrites assert statements
                            in test modules on import to provide assert
                            expression information.
      --setup-only          Only setup fixtures, do not execute tests
      --setup-show          Show setup of fixtures while executing tests
      --setup-plan          Show what fixtures and tests would be executed but
                            don't execute anything

    logging:
      --log-level=LEVEL     Level of messages to catch/display. Not set by
                            default, so it depends on the root/parent log
                            handler's effective level, where it is "WARNING" by
                            default.
      --log-format=LOG_FORMAT
                            Log format used by the logging module
      --log-date-format=LOG_DATE_FORMAT
                            Log date format used by the logging module
      --log-cli-level=LOG_CLI_LEVEL
                            CLI logging level
      --log-cli-format=LOG_CLI_FORMAT
                            Log format used by the logging module
      --log-cli-date-format=LOG_CLI_DATE_FORMAT
                            Log date format used by the logging module
      --log-file=LOG_FILE   Path to a file when logging will be written to
      --log-file-mode={w,a}
                            Log file open mode
      --log-file-level=LOG_FILE_LEVEL
                            Log file logging level
      --log-file-format=LOG_FILE_FORMAT
                            Log format used by the logging module
      --log-file-date-format=LOG_FILE_DATE_FORMAT
                            Log date format used by the logging module
      --log-auto-indent=LOG_AUTO_INDENT
                            Auto-indent multiline messages passed to the logging
                            module. Accepts true|on, false|off or an integer.
      --log-disable=LOGGER_DISABLE
                            Disable a logger by name. Can be passed multiple
                            times.

    [pytest] configuration options in the first pytest.toml|pytest.ini|tox.ini|setup.cfg|pyproject.toml file found:

      markers (linelist):   Register new markers for test functions
      empty_parameter_set_mark (string):
                            Default marker for empty parametersets
      strict_config (bool): Any warnings encountered while parsing the `pytest`
                            section of the configuration file raise errors
      strict_markers (bool):
                            Markers not registered in the `markers` section of
                            the configuration file raise errors
      strict (bool):        Enables all strictness options, currently:
                            strict_config, strict_markers, strict_xfail,
                            strict_parametrization_ids
      filterwarnings (linelist):
                            Each line specifies a pattern for
                            warnings.filterwarnings. Processed after
                            -W/--pythonwarnings.
      norecursedirs (args): Directory patterns to avoid for recursion
      testpaths (args):     Directories to search for tests when no files or
                            directories are given on the command line
      collect_imported_tests (bool):
                            Whether to collect tests in imported modules outside
                            `testpaths`
      consider_namespace_packages (bool):
                            Consider namespace packages when resolving module
                            names during import
      usefixtures (args):   List of default fixtures to be used with this
                            project
      python_files (args):  Glob-style file patterns for Python test module
                            discovery
      python_classes (args):
                            Prefixes or glob names for Python test class
                            discovery
      python_functions (args):
                            Prefixes or glob names for Python test function and
                            method discovery
      disable_test_id_escaping_and_forfeit_all_rights_to_community_support (bool):
                            Disable string escape non-ASCII characters, might
                            cause unwanted side effects(use at your own risk)
      strict_parametrization_ids (bool):
                            Emit an error if non-unique parameter set IDs are
                            detected
      console_output_style (string):
                            Console output: "classic", or with additional
                            progress information ("progress" (percentage) |
                            "count" | "progress-even-when-capture-no" (forces
                            progress even when capture=no)
      verbosity_test_cases (string):
                            Specify a verbosity level for test case execution,
                            overriding the main level. Higher levels will
                            provide more detailed information about each test
                            case executed.
      strict_xfail (bool):  Default for the strict parameter of xfail markers
                            when not given explicitly (default: False) (alias:
                            xfail_strict)
      tmp_path_retention_count (string):
                            How many sessions should we keep the `tmp_path`
                            directories, according to
                            `tmp_path_retention_policy`.
      tmp_path_retention_policy (string):
                            Controls which directories created by the `tmp_path`
                            fixture are kept around, based on test outcome.
                            (all/failed/none)
      enable_assertion_pass_hook (bool):
                            Enables the pytest_assertion_pass hook. Make sure to
                            delete any previously generated pyc cache files.
      truncation_limit_lines (string):
                            Set threshold of LINES after which truncation will
                            take effect
      truncation_limit_chars (string):
                            Set threshold of CHARS after which truncation will
                            take effect
      verbosity_assertions (string):
                            Specify a verbosity level for assertions, overriding
                            the main level. Higher levels will provide more
                            detailed explanation when an assertion fails.
      junit_suite_name (string):
                            Test suite name for JUnit report
      junit_logging (string):
                            Write captured log messages to JUnit report: one of
                            no|log|system-out|system-err|out-err|all
      junit_log_passing_tests (bool):
                            Capture log information for passing tests to JUnit
                            report:
      junit_duration_report (string):
                            Duration time to report: one of total|call
      junit_family (string):
                            Emit XML for schema: one of legacy|xunit1|xunit2
      doctest_optionflags (args):
                            Option flags for doctests
      doctest_encoding (string):
                            Encoding used for doctest files
      cache_dir (string):   Cache directory path
      log_level (string):   Default value for --log-level
      log_format (string):  Default value for --log-format
      log_date_format (string):
                            Default value for --log-date-format
      log_cli (bool):       Enable log display during test run (also known as
                            "live logging")
      log_cli_level (string):
                            Default value for --log-cli-level
      log_cli_format (string):
                            Default value for --log-cli-format
      log_cli_date_format (string):
                            Default value for --log-cli-date-format
      log_file (string):    Default value for --log-file
      log_file_mode (string):
                            Default value for --log-file-mode
      log_file_level (string):
                            Default value for --log-file-level
      log_file_format (string):
                            Default value for --log-file-format
      log_file_date_format (string):
                            Default value for --log-file-date-format
      log_auto_indent (string):
                            Default value for --log-auto-indent
      faulthandler_timeout (string):
                            Dump the traceback of all threads if a test takes
                            more than TIMEOUT seconds to finish
      faulthandler_exit_on_timeout (bool):
                            Exit the test process if a test takes more than
                            faulthandler_timeout seconds to finish
      verbosity_subtests (string):
                            Specify verbosity level for subtests. Higher levels
                            will generate output for passed subtests. Failed
                            subtests are always reported.
      addopts (args):       Extra command line options
      minversion (string):  Minimally required pytest version
      pythonpath (paths):   Add paths to sys.path
      required_plugins (args):
                            Plugins that must be present for pytest to run

    Environment variables:
      CI                       When set to a non-empty value, pytest knows it is running in a CI process and does not truncate summary info
      BUILD_NUMBER             Equivalent to CI
      PYTEST_ADDOPTS           Extra command line options
      PYTEST_PLUGINS           Comma-separated plugins to load during startup
      PYTEST_DISABLE_PLUGIN_AUTOLOAD Set to disable plugin auto-loading
      PYTEST_DEBUG             Set to enable debug tracing of pytest's internals
      PYTEST_DEBUG_TEMPROOT    Override the system temporary directory
      PYTEST_THEME             The Pygments style to use for code output
      PYTEST_THEME_MODE        Set the PYTEST_THEME to be either 'dark' or 'light'

    to see available markers type: pytest --markers
    to see available fixtures type: pytest --fixtures
    (shown according to specified file_or_dir or current dir if not specified; fixtures with leading '_' are only shown with the '-v' option