# API Reference¶

## Constants¶

### pytest.__version__¶

The current pytest version, as a string:

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

### pytest.version_tuple¶

New 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)[source]

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
```

You can also use `approx` to compare nonnumeric types, or dicts and sequences containing nonnumeric 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 (numpy.testing) if you need support for comparisons, NaNs, or ULP-based tolerances.

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 nonnumeric type.

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

Parameters

nan_ok (bool) –

Return type

_pytest.python_api.ApproxBase

### pytest.fail¶

`fail`(reason[, pytrace=True, msg=None])[source]

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.

• msg (Optional[str]) – Same as `reason`, but deprecated. Will be removed in a future version, use `reason` instead.

Return type

NoReturn

### pytest.skip¶

`skip`(reason[, allow_module_level=False, msg=None])[source]

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, skipping the rest of the module. Defaults to False.

• msg (Optional[str]) – Same as `reason`, but deprecated. Will be removed in a future version, use `reason` instead.

Return type

NoReturn

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.

### pytest.importorskip¶

`importorskip`(modname, minversion=None, reason=None)[source]

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) – If given, the imported module’s `__version__` attribute must be at least this minimal version, otherwise the test is still skipped.

• reason (str) – If given, this reason is shown as the message when the module cannot be imported.

Returns

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

Return type

Any

Example:

```docutils = pytest.importorskip("docutils")
```

### pytest.xfail¶

`xfail`(reason='')[source]

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

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

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.

Parameters

reason (str) –

Return type

NoReturn

### pytest.exit¶

`exit`(reason[, returncode=False, msg=None])[source]

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 (Optional[int]) – Return code to be used when exiting pytest.

• msg (Optional[str]) – Same as `reason`, but deprecated. Will be removed in a future version, use `reason` instead.

Return type

NoReturn

### pytest.main¶

`main`(args=None, plugins=None)[source]

Perform an in-process test run.

Parameters
• args (Optional[Union[List[str], os.PathLike[str]]]) – List of command line arguments.

• plugins (Optional[Sequence[Union[str, object]]]) – List of plugin objects to be auto-registered during initialization.

Returns

An exit code.

Return type

Union[int, _pytest.config.ExitCode]

### pytest.param¶

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

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 (Union[_pytest.mark.structures.MarkDecorator, Collection[Union[_pytest.mark.structures.MarkDecorator, _pytest.mark.structures.Mark]]]) – A single mark or a list of marks to be applied to this parameter set.

• id (Optional[str]) – The id to attribute to this parameter set.

• marks

• id

Return type

_pytest.mark.structures.ParameterSet

### pytest.raises¶

with `raises`(expected_exception: Exception[, *, match]) as excinfo[source]

Assert that a code block/function call raises `expected_exception` or raise a failure exception otherwise.

Parameters
• match

If specified, a string containing a regular expression, or a regular expression object, that is tested against the string representation of the exception using `re.search()`. To match a literal string that may contain special characters, the pattern can first be escaped with `re.escape()`.

(This is only used when `pytest.raises()` is used as a context manager, and passed through to the function otherwise. When using `pytest.raises()` as a function, you can use: `pytest.raises(Exc, func, match="passed on").match("my pattern")`.)

• expected_exception (Union[Type[E], Tuple[Type[E], ..]]) –

• args (Any) –

• kwargs (Any) –

Return type

Union[_pytest.python_api.RaisesContext[E], _pytest._code.code.ExceptionInfo[E]]

Use `pytest.raises` as a context manager, which will capture the exception of the given type:

```>>> import pytest
>>> with pytest.raises(ZeroDivisionError):
...    1/0
```

If the code block does not raise the expected exception (`ZeroDivisionError` in the example above), or no exception at all, the check will fail instead.

You can also use the keyword argument `match` to assert that the exception matches a text or regex:

```>>> with pytest.raises(ValueError, match='must be 0 or None'):
...     raise ValueError("value must be 0 or None")

>>> with pytest.raises(ValueError, match=r'must be \d+\$'):
...     raise ValueError("value must be 42")
```

The context manager produces an `ExceptionInfo` object which can be used to inspect the details of the captured exception:

```>>> with pytest.raises(ValueError) as exc_info:
...     raise ValueError("value must be 42")
>>> assert exc_info.type is ValueError
>>> assert exc_info.value.args[0] == "value must be 42"
```

Note

When using `pytest.raises` as a context manager, it’s worthwhile to note that normal context manager rules apply and that the exception raised must be the final line in the scope of the context manager. Lines of code after that, within the scope of the context manager will not be executed. For example:

```>>> value = 15
>>> with pytest.raises(ValueError) as exc_info:
...     if value > 10:
...         raise ValueError("value must be <= 10")
...     assert exc_info.type is ValueError  # this will not execute
```

Instead, the following approach must be taken (note the difference in scope):

```>>> with pytest.raises(ValueError) as exc_info:
...     if value > 10:
...         raise ValueError("value must be <= 10")
...
>>> assert exc_info.type is ValueError
```

Using with `pytest.mark.parametrize`

When using pytest.mark.parametrize it is possible to parametrize tests such that some runs raise an exception and others do not.

See Parametrizing conditional raising for an example.

Legacy form

It is possible to specify a callable by passing a to-be-called lambda:

```>>> raises(ZeroDivisionError, lambda: 1/0)
<ExceptionInfo ...>
```

or you can specify an arbitrary callable with arguments:

```>>> def f(x): return 1/x
...
>>> raises(ZeroDivisionError, f, 0)
<ExceptionInfo ...>
>>> raises(ZeroDivisionError, f, x=0)
<ExceptionInfo ...>
```

The form above is fully supported but discouraged for new code because the context manager form is regarded as more readable and less error-prone.

Note

Similar to caught exception objects in Python, explicitly clearing local references to returned `ExceptionInfo` objects can help the Python interpreter speed up its garbage collection.

Clearing those references breaks a reference cycle (`ExceptionInfo` –> caught exception –> frame stack raising the exception –> current frame stack –> local variables –> `ExceptionInfo`) which makes Python keep all objects referenced from that cycle (including all local variables in the current frame) alive until the next cyclic garbage collection run. More detailed information can be found in the official Python documentation for the try statement.

### pytest.deprecated_call¶

with `deprecated_call`()[source]

Assert that code produces a `DeprecationWarning` or `PendingDeprecationWarning`.

This function can be used as a context manager:

```>>> import warnings
>>> def api_call_v2():
...     warnings.warn('use v3 of this api', DeprecationWarning)
...     return 200

>>> import pytest
>>> with pytest.deprecated_call():
...    assert api_call_v2() == 200
```

It can also be used by passing a function and `*args` and `**kwargs`, in which case it will ensure calling `func(*args, **kwargs)` produces one of the warnings types above. The return value is the return value of the function.

In the context manager form you may use the keyword argument `match` to assert that the warning matches a text or regex.

The context manager produces a list of `warnings.WarningMessage` objects, one for each warning raised.

Parameters
• func (Optional[Callable[[..], Any]]) –

• args (Any) –

• kwargs (Any) –

Return type

Union[_pytest.recwarn.WarningsRecorder, Any]

### pytest.register_assert_rewrite¶

Tutorial: Assertion Rewriting

`register_assert_rewrite`(*names)[source]

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.

Raises

TypeError – If the given module names are not strings.

Parameters

names (str) –

Return type

None

### pytest.warns¶

with `warns`(expected_warning: Exception[, match])[source]

Assert that code raises a particular class of warning.

Specifically, the parameter `expected_warning` can be a warning class or sequence of warning classes, and the inside the `with` block must issue a warning of that class or classes.

This helper produces a list of `warnings.WarningMessage` objects, one for each warning raised.

This function can be used as a context manager, or any of the other ways `pytest.raises()` can be used:

```>>> import pytest
>>> with pytest.warns(RuntimeWarning):
...    warnings.warn("my warning", RuntimeWarning)
```

In the context manager form you may use the keyword argument `match` to assert that the warning matches a text or regex:

```>>> with pytest.warns(UserWarning, match='must be 0 or None'):
...     warnings.warn("value must be 0 or None", UserWarning)

>>> with pytest.warns(UserWarning, match=r'must be \d+\$'):
...     warnings.warn("value must be 42", UserWarning)

>>> with pytest.warns(UserWarning, match=r'must be \d+\$'):
...     warnings.warn("this is not here", UserWarning)
Traceback (most recent call last):
...
Failed: DID NOT WARN. No warnings of type ...UserWarning... were emitted...
```
Parameters
• expected_warning (Union[Type[Warning], Tuple[Type[Warning], ..]]) –

• args (Any) –

• match (Optional[Union[str, Pattern[str]]]) –

• kwargs (Any) –

Return type

Union[_pytest.recwarn.WarningsChecker, Any]

### pytest.freeze_includes¶

Tutorial: Freezing pytest

`freeze_includes`()[source]

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

Return type

List[str]

## Marks¶

Marks can be used apply meta data 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¶

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¶

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¶

Marks a test function as expected to fail.

`pytest.mark.``xfail`(condition=None, *, reason=None, raises=None, run=True, strict=False)
Parameters
• condition (bool or 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 subclass (or tuple of subclasses) expected to be raised by the test function; other exceptions will fail the test.

• run (bool) – If 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 default) 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).

### 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")
```

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` 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")
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¶

`@``fixture`(fixture_function=None, *, scope='function', params=None, autouse=False, ids=None, name=None)[source]

Decorator to mark a fixture factory function.

This decorator can be used, with or without parameters, to define a fixture function.

The name of the fixture function can later be referenced to cause its invocation ahead of running tests: test modules or classes can use the `pytest.mark.usefixtures(fixturename)` marker.

Test functions can directly use fixture names as input arguments in which case the fixture instance returned from the fixture function will be injected.

Fixtures can provide their values to test functions using `return` or `yield` statements. When using `yield` the code block after the `yield` statement is executed as teardown code regardless of the test outcome, and must yield exactly once.

Parameters
• scope (Union[_ScopeName, Callable[[str, Config], _ScopeName]]) –

The scope for which this fixture is shared; one of `"function"` (default), `"class"`, `"module"`, `"package"` or `"session"`.

This parameter may also be a callable which receives `(fixture_name, config)` as parameters, and must return a `str` with one of the values mentioned above.

• params (Optional[Iterable[object]]) – An optional list of parameters which will cause multiple invocations of the fixture function and all of the tests using it. The current parameter is available in `request.param`.

• autouse (bool) – If True, the fixture func is activated for all tests that can see it. If False (the default), an explicit reference is needed to activate the fixture.

• ids (Optional[Union[Sequence[Optional[object]], Callable[[Any], Optional[object]]]]) – Sequence of ids each corresponding to the params so that they are part of the test id. If no ids are provided they will be generated automatically from the params.

• name (Optional[str]) – The name of the fixture. This defaults to the name of the decorated function. If a fixture is used in the same module in which it is defined, the function name of the fixture will be shadowed by the function arg that requests the fixture; one way to resolve this is to name the decorated function `fixture_<fixturename>` and then use `@pytest.fixture(name='<fixturename>')`.

• fixture_function (Optional[FixtureFunction]) –

Return type

Union[_pytest.fixtures.FixtureFunctionMarker, FixtureFunction]

### config.cache¶

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`[source]
`mkdir`(name)[source]

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.

New 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.

Return type

pathlib.Path

`get`(key, default)[source]

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)[source]

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.

Return type

None

### capsys¶

Tutorial: How to capture stdout/stderr output

`capsys`()[source]

Enable text capturing of writes to `sys.stdout` and `sys.stderr`.

The captured output is made available via `capsys.readouterr()` method calls, which return a `(out, err)` namedtuple. `out` and `err` will be `text` objects.

Returns an instance of `CaptureFixture[str]`.

Example:

```def test_output(capsys):
print("hello")
assert captured.out == "hello\n"
```
Parameters

request (_pytest.fixtures.SubRequest) –

Return type

Generator[_pytest.capture.CaptureFixture[str], None, None]

class `CaptureFixture`[source]

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

`readouterr`()[source]

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

_pytest.capture.CaptureResult

with `disabled`()[source]

Temporarily disable capturing while inside the `with` block.

Return type

Generator[None, None, None]

### capsysbinary¶

Tutorial: How to capture stdout/stderr output

`capsysbinary`()[source]

Enable bytes capturing of writes to `sys.stdout` and `sys.stderr`.

The captured output is made available via `capsysbinary.readouterr()` method calls, which return a `(out, err)` namedtuple. `out` and `err` will be `bytes` objects.

Returns an instance of `CaptureFixture[bytes]`.

Example:

```def test_output(capsysbinary):
print("hello")
assert captured.out == b"hello\n"
```
Parameters

request (_pytest.fixtures.SubRequest) –

Return type

Generator[_pytest.capture.CaptureFixture[bytes], None, None]

### capfd¶

Tutorial: How to capture stdout/stderr output

`capfd`()[source]

Enable text capturing of writes to file descriptors `1` and `2`.

The captured output is made available via `capfd.readouterr()` method calls, which return a `(out, err)` namedtuple. `out` and `err` will be `text` objects.

Returns an instance of `CaptureFixture[str]`.

Example:

```def test_system_echo(capfd):
os.system('echo "hello"')
assert captured.out == "hello\n"
```
Parameters

request (_pytest.fixtures.SubRequest) –

Return type

Generator[_pytest.capture.CaptureFixture[str], None, None]

### capfdbinary¶

Tutorial: How to capture stdout/stderr output

`capfdbinary`()[source]

Enable bytes capturing of writes to file descriptors `1` and `2`.

The captured output is made available via `capfd.readouterr()` method calls, which return a `(out, err)` namedtuple. `out` and `err` will be `byte` objects.

Returns an instance of `CaptureFixture[bytes]`.

Example:

```def test_system_echo(capfdbinary):
os.system('echo "hello"')
assert captured.out == b"hello\n"
```
Parameters

request (_pytest.fixtures.SubRequest) –

Return type

Generator[_pytest.capture.CaptureFixture[bytes], None, None]

### doctest_namespace¶

Tutorial: How to run doctests

`doctest_namespace`()[source]

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)
doctest_namespace["np"] = numpy
```

For more details: ‘doctest_namespace’ fixture.

Return type

Dict[str, Any]

### request¶

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

class `FixtureRequest`[source]

A request for a fixture from a test or fixture function.

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

`fixturename`: Optional[str]

Fixture for which this request is being performed.

`scope`

Scope string, one of “function”, “class”, “module”, “package”, “session”.

`fixturenames`

Names of all active fixtures in this request.

`node`

Underlying collection node (depends on current request scope).

`config`

The pytest config object associated with this request.

`function`

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

`cls`

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

`instance`

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

`module`

Python module object where the test function was collected.

`path`

Path where the test function was collected.

`keywords`

Keywords/markers dictionary for the underlying node.

`session`

Pytest session object.

`addfinalizer`(finalizer)[source]

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

Parameters

finalizer (Callable[[], object]) –

Return type

None

`applymarker`(marker)[source]

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 (Union[str, _pytest.mark.structures.MarkDecorator]) – A `pytest.MarkDecorator` object created by a call to `pytest.mark.NAME(...)`.

Return type

None

`raiseerror`(msg)[source]

Raise a FixtureLookupError with the given message.

Parameters

msg (Optional[str]) –

Return type

NoReturn

`getfixturevalue`(argname)[source]

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.

Raises

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

Parameters

argname (str) –

Return type

Any

### pytestconfig¶

`pytestconfig`()[source]

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

Example:

```def test_foo(pytestconfig):
if pytestconfig.getoption("verbose") > 0:
...
```
Parameters

request (_pytest.fixtures.FixtureRequest) –

Return type

_pytest.config.Config

### record_property¶

Tutorial: record_property

`record_property`()[source]

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)
```
Parameters

request (_pytest.fixtures.FixtureRequest) –

Return type

Callable[[str, object], None]

### record_testsuite_property¶

Tutorial: record_testsuite_property

`record_testsuite_property`()[source]

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

`name` must be a string, `value` will be converted to a string and properly xml-escaped.

Warning

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

Parameters

request (_pytest.fixtures.FixtureRequest) –

Return type

Callable[[str, object], None]

### caplog¶

Tutorial: How to manage logging

`caplog`()[source]

Access and control log capturing.

Captured logs are available through the following properties/methods:

```* caplog.messages        -> list of format-interpolated log messages
* caplog.text            -> string containing formatted log output
* caplog.records         -> list of logging.LogRecord instances
* caplog.record_tuples   -> list of (logger_name, level, message) tuples
* caplog.clear()         -> clear captured records and formatted log output string
```

Returns a `pytest.LogCaptureFixture` instance.

Parameters

request (_pytest.fixtures.FixtureRequest) –

Return type

Generator[_pytest.logging.LogCaptureFixture, None, None]

final class `LogCaptureFixture`[source]

Provides access and control of log capturing.

`handler`

Get the logging handler used by the fixture.

Return type

LogCaptureHandler

`get_records`(when)[source]

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

Parameters

when (str) – 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[logging.LogRecord]

New in version 3.4.

`text`

The formatted log text.

`records`

The list of log records.

`record_tuples`

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)

`messages`

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.

New in version 3.7.

`clear`()[source]

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

Return type

None

`set_level`(level, logger=None)[source]

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

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.

Parameters
• level (int) – The level.

• logger (str) – The logger to update. If not given, the root logger.

Return type

None

with `at_level`(level, logger=None)[source]

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.

Parameters
• level (int) – The level.

• logger (str) – The logger to update. If not given, the root logger.

Return type

Generator[None, None, None]

### monkeypatch¶

`monkeypatch`()[source]

A convenient fixture for monkey-patching.

The fixture provides these methods to modify objects, dictionaries, or `os.environ`:

All modifications will be undone after the requesting test function or fixture has finished. The `raising` parameter determines if a `KeyError` or `AttributeError` will be raised if the set/deletion operation does not have the specified target.

To undo modifications done by the fixture in a contained scope, use `context()`.

Returns a `MonkeyPatch` instance.

Return type

Generator[_pytest.monkeypatch.MonkeyPatch, None, None]

final class `MonkeyPatch`[source]

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

Returned by the `monkeypatch` fixture.

Versionchanged:

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 with `context`()[source]

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 issue #3290).

Return type

Generator[_pytest.monkeypatch.MonkeyPatch, None, None]

`setattr`(target, name, value=<notset>, raising=True)[source]

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.

Parameters
Return type

None

`delattr`(target, name=<notset>, raising=True)[source]

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.

Parameters
• target (Union[object, str]) –

• name (Union[str, _pytest.monkeypatch.Notset]) –

• raising (bool) –

Return type

None

`setitem`(dic, name, value)[source]

Set dictionary entry `name` to value.

Parameters
• dic (MutableMapping[K, V]) –

• name (K) –

• value (V) –

Return type

None

`delitem`(dic, name, raising=True)[source]

Delete `name` from dict.

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

Parameters
• dic (MutableMapping[K, V]) –

• name (K) –

• raising (bool) –

Return type

None

`setenv`(name, value, prepend=None)[source]

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.

Parameters
• name (str) –

• value (str) –

• prepend (Optional[str]) –

Return type

None

`delenv`(name, raising=True)[source]

Delete `name` from the environment.

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

Parameters
• name (str) –

• raising (bool) –

Return type

None

`syspath_prepend`(path)[source]

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

Return type

None

`chdir`(path)[source]

Change the current working directory to the specified path.

Path can be a string or a path object.

Parameters

path (Union[str, os.PathLike[str]]) –

Return type

None

`undo`()[source]

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.

Return type

None

### pytester¶

New 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`[source]

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.

Attributes:

Variables
• path (Path) – temporary directory path used to create files/run tests from, etc.

• plugins – A list of plugins to use with `parseconfig()` and `runpytest()`. Initially this is an empty list but plugins can be added to the list. The type of items to add to the list depends on the method using them so refer to them for details.

exception `TimeoutExpired`[source]
`path`

Temporary directory where files are created and pytest is executed.

`make_hook_recorder`(pluginmanager)[source]

Create a new `HookRecorder` for a PluginManager.

Parameters

pluginmanager (_pytest.config.PytestPluginManager) –

Return type

_pytest.pytester.HookRecorder

`chdir`()[source]

Cd into the temporary directory.

This is done automatically upon instantiation.

Return type

None

`makefile`(ext, *args, **kwargs)[source]

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.

Return type

pathlib.Path

Examples:

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

```

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

```filename = pytester.path.joinpath("foo.bin")
filename.write_bytes(b"...")
```
`makeconftest`(source)[source]

Write a contest.py file with ‘source’ as contents.

Parameters

source (str) –

Return type

pathlib.Path

`makeini`(source)[source]

Write a tox.ini file with ‘source’ as contents.

Parameters

source (str) –

Return type

pathlib.Path

`getinicfg`(source)[source]

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

Parameters

source (str) –

Return type

iniconfig.SectionWrapper

`makepyprojecttoml`(source)[source]

Write a pyproject.toml file with ‘source’ as contents.

New in version 6.0.

Parameters

source (str) –

Return type

pathlib.Path

`makepyfile`(*args, **kwargs)[source]

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.
```
Return type

pathlib.Path

`maketxtfile`(*args, **kwargs)[source]

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.
```
Return type

pathlib.Path

`syspathinsert`(path=None)[source]

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 (Optional[Union[str, os.PathLike[str]]]) –

Return type

None

`mkdir`(name)[source]

Create a new (sub)directory.

Parameters

name (str) –

Return type

pathlib.Path

`mkpydir`(name)[source]

Create a new python package.

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

Parameters

name (str) –

Return type

pathlib.Path

`copy_example`(name=None)[source]

Copy file from project’s directory into the testdir.

Parameters

name (str) – The name of the file to copy.

Returns

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

Return type

pathlib.Path

`getnode`(config, arg)[source]

Return the collection node of a file.

Parameters
Return type

Optional[Union[_pytest.nodes.Item, _pytest.nodes.Collector]]

`getpathnode`(path)[source]

Return the collection node of a file.

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

Parameters

path (os.PathLike[str]) – Path to the file.

`genitems`(colitems)[source]

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[Union[_pytest.nodes.Item, _pytest.nodes.Collector]]) –

Return type

List[_pytest.nodes.Item]

`runitem`(source)[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()`.

Parameters

source (str) –

Return type

Any

`inline_runsource`(source, *cmdlineargs)[source]

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.

Return type

_pytest.pytester.HookRecorder

`inline_genitems`(*args)[source]

Run `pytest.main(['--collectonly'])` 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.

Return type

Tuple[List[_pytest.nodes.Item], _pytest.pytester.HookRecorder]

`inline_run`(*args, plugins=(), no_reraise_ctrlc=False)[source]

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 (Union[str, os.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.

Return type

_pytest.pytester.HookRecorder

`runpytest_inprocess`(*args, **kwargs)[source]

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

Parameters
Return type

_pytest.pytester.RunResult

`runpytest`(*args, **kwargs)[source]

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

Parameters
Return type

_pytest.pytester.RunResult

`parseconfig`(*args)[source]

Return a new pytest Config instance from given commandline args.

This invokes the pytest bootstrapping code in _pytest.config to create a new `_pytest.core.PluginManager` 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 PluginManager.

Parameters

args (Union[str, os.PathLike[str]]) –

Return type

_pytest.config.Config

`parseconfigure`(*args)[source]

Return a new pytest configured Config instance.

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

Parameters

args (Union[str, os.PathLike[str]]) –

Return type

_pytest.config.Config

`getitem`(source, funcname='test_func')[source]

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 (Union[str, os.PathLike[str]]) – The module source.

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

Return type

_pytest.nodes.Item

`getitems`(source)[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.

Parameters

source (Union[str, os.PathLike[str]]) –

Return type

List[_pytest.nodes.Item]

`getmodulecol`(source, configargs=(), *, withinit=False)[source]

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 (Union[str, os.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)[source]

Return the collection node for name from the module collection.

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

Parameters
Return type

Optional[Union[_pytest.nodes.Item, _pytest.nodes.Collector]]

`popen`(cmdargs, stdout=-1, stderr=-1, stdin=<NotSetType.token: 0>, **kw)[source]

Invoke `subprocess.Popen`.

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

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

Parameters
• cmdargs (Sequence[Union[str, os.PathLike[str]]]) –

• stdout (Union[int, TextIO]) –

• stderr (Union[int, TextIO]) –

• stdin (Union[_pytest.compat.NotSetType, bytes, IO[Any], int]) –

`run`(*cmdargs, timeout=None, stdin=<NotSetType.token: 0>)[source]

Run a command with arguments.

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

Parameters
Return type

_pytest.pytester.RunResult

`runpython`(script)[source]

Run a python script using sys.executable as interpreter.

Parameters

script (os.PathLike[str]) –

Return type

_pytest.pytester.RunResult

`runpython_c`(command)[source]

Run `python -c "command"`.

Parameters

command (str) –

Return type

_pytest.pytester.RunResult

`runpytest_subprocess`(*args, timeout=None)[source]

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
Return type

_pytest.pytester.RunResult

`spawn_pytest`(string, expect_timeout=10.0)[source]

Run pytest using pexpect.

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

The pexpect child is returned.

Parameters
• string (str) –

• expect_timeout (float) –

Return type

pexpect.spawn

`spawn`(cmd, expect_timeout=10.0)[source]

Run a command using pexpect.

The pexpect child is returned.

Parameters
• cmd (str) –

• expect_timeout (float) –

Return type

pexpect.spawn

final class `RunResult`[source]

The result of running a command from `Pytester`.

`ret`: Union[int, _pytest.config.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`()[source]

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}`.

Return type

Dict[str, int]

classmethod `parse_summary_nouns`(lines)[source]

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}`.

Return type

Dict[str, int]

`assert_outcomes`(passed=0, skipped=0, failed=0, errors=0, xpassed=0, xfailed=0, warnings=None, deselected=None)[source]

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.

Parameters
• passed (int) –

• skipped (int) –

• failed (int) –

• errors (int) –

• xpassed (int) –

• xfailed (int) –

• warnings (Optional[int]) –

• deselected (Optional[int]) –

Return type

None

class `LineMatcher`[source]

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__`()[source]

Return the entire original text.

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

Return type

str

`fnmatch_lines_random`(lines2)[source]

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

Parameters

lines2 (Sequence[str]) –

Return type

None

`re_match_lines_random`(lines2)[source]

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

Parameters

lines2 (Sequence[str]) –

Return type

None

`get_lines_after`(fnline)[source]

Return all lines following the given line in the text.

The given line can contain glob wildcards.

Parameters

fnline (str) –

Return type

Sequence[str]

`fnmatch_lines`(lines2, *, consecutive=False)[source]

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?

Return type

None

`re_match_lines`(lines2, *, consecutive=False)[source]

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?

Return type

None

`no_fnmatch_line`(pat)[source]

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

Parameters

pat (str) – The pattern to match lines.

Return type

None

`no_re_match_line`(pat)[source]

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

Parameters

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

Return type

None

`str`()[source]

Return the entire original text.

Return type

str

final class `HookRecorder`[source]

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)[source]

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

Parameters

names (Union[str, Iterable[str]]) –

Return type

List[_pytest.pytester.RecordedHookCall]

`matchreport`(inamepart='', names=('pytest_runtest_logreport', 'pytest_collectreport'), when=None)[source]

Return a testreport whose dotted import path matches.

Parameters
• inamepart (str) –

• names (Union[str, Iterable[str]]) –

• when (Optional[str]) –

Return type

Union[_pytest.reports.CollectReport, _pytest.reports.TestReport]

final class `RecordedHookCall`[source]

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
```

### 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`[source]

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`
`tmpdir`

Temporary directory where tests are executed.

`make_hook_recorder`(pluginmanager)[source]
Return type

_pytest.pytester.HookRecorder

`chdir`()[source]
Return type

None

`finalize`()[source]

See `Pytester._finalize()`.

Return type

None

`makefile`(ext, *args, **kwargs)[source]
Return type

py._path.local.LocalPath

`makeconftest`(source)[source]
Return type

py._path.local.LocalPath

`makeini`(source)[source]
Return type

py._path.local.LocalPath

`getinicfg`(source)[source]
Parameters

source (str) –

Return type

iniconfig.SectionWrapper

`makepyprojecttoml`(source)[source]
Return type

py._path.local.LocalPath

`makepyfile`(*args, **kwargs)[source]
Return type

py._path.local.LocalPath

`maketxtfile`(*args, **kwargs)[source]
Return type

py._path.local.LocalPath

`syspathinsert`(path=None)[source]
Return type

None

`mkdir`(name)[source]
Return type

py._path.local.LocalPath

`mkpydir`(name)[source]
Return type

py._path.local.LocalPath

`copy_example`(name=None)[source]
Return type

py._path.local.LocalPath

`getnode`(config, arg)[source]
Parameters

config (_pytest.config.Config) –

Return type

Optional[Union[_pytest.nodes.Item, _pytest.nodes.Collector]]

`getpathnode`(path)[source]
`genitems`(colitems)[source]
Parameters

colitems (List[Union[_pytest.nodes.Item, _pytest.nodes.Collector]]) –

Return type

List[_pytest.nodes.Item]

`runitem`(source)[source]
`inline_runsource`(source, *cmdlineargs)[source]
`inline_genitems`(*args)[source]
`inline_run`(*args, plugins=(), no_reraise_ctrlc=False)[source]
Parameters

no_reraise_ctrlc (bool) –

`runpytest_inprocess`(*args, **kwargs)[source]
Return type

_pytest.pytester.RunResult

`runpytest`(*args, **kwargs)[source]
Return type

_pytest.pytester.RunResult

`parseconfig`(*args)[source]
Return type

_pytest.config.Config

`parseconfigure`(*args)[source]
Return type

_pytest.config.Config

`getitem`(source, funcname='test_func')[source]
`getitems`(source)[source]
`getmodulecol`(source, configargs=(), withinit=False)[source]
`collect_by_name`(modcol, name)[source]
Parameters
• modcol (_pytest.nodes.Collector) –

• name (str) –

Return type

Optional[Union[_pytest.nodes.Item, _pytest.nodes.Collector]]

`popen`(cmdargs, stdout=-1, stderr=-1, stdin=<NotSetType.token: 0>, **kw)[source]
`run`(*cmdargs, timeout=None, stdin=<NotSetType.token: 0>)[source]
Return type

_pytest.pytester.RunResult

`runpython`(script)[source]
Return type

_pytest.pytester.RunResult

`runpython_c`(command)[source]
`runpytest_subprocess`(*args, timeout=None)[source]
Return type

_pytest.pytester.RunResult

`spawn_pytest`(string, expect_timeout=10.0)[source]
Parameters
• string (str) –

• expect_timeout (float) –

Return type

pexpect.spawn

`spawn`(cmd, expect_timeout=10.0)[source]
Parameters
• cmd (str) –

• expect_timeout (float) –

Return type

pexpect.spawn

### recwarn¶

`recwarn`()[source]

Return a `WarningsRecorder` instance that records all warnings emitted by test functions.

See https://docs.pytest.org/en/latest/how-to/capture-warnings.html for information on warning categories.

Return type

Generator[_pytest.recwarn.WarningsRecorder, None, None]

class `WarningsRecorder`[source]

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.

`list`

The list of recorded warnings.

`pop`(cls=<class 'Warning'>)[source]

Pop the first recorded warning, raise exception if not exists.

Parameters

cls (Type[Warning]) –

Return type

warnings.WarningMessage

`clear`()[source]

Clear the list of recorded warnings.

Return type

None

### tmp_path¶

`tmp_path`()[source]

Return a temporary directory path object which is unique to each test function invocation, created as a sub directory of the base temporary directory.

By default, a new base temporary directory is created each test session, and old bases are removed after 3 sessions, to aid in debugging. If `--basetemp` is used then it is cleared each session. See The default base temporary directory.

The returned object is a `pathlib.Path` object.

Parameters
• request (_pytest.fixtures.FixtureRequest) –

• tmp_path_factory (_pytest.tmpdir.TempPathFactory) –

Return type

pathlib.Path

### tmp_path_factory¶

Tutorial: The tmp_path_factory fixture

`tmp_path_factory` is an instance of `TempPathFactory`:

final class `TempPathFactory`[source]

Factory for temporary directories under the common base temp directory.

The base directory can be configured using the `--basetemp` option.

`mktemp`(basename, numbered=True)[source]

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

pathlib.Path

`getbasetemp`()[source]

Return the base temporary directory, creating it if needed.

Return type

pathlib.Path

### tmpdir¶

`tmpdir`()

Return a temporary directory path object which is unique to each test function invocation, created as a sub directory of the base temporary directory.

By default, a new base temporary directory is created each test session, and old bases are removed after 3 sessions, to aid in debugging. If `--basetemp` is used then it is cleared each session. See The default base temporary directory.

The returned object is a legacy_path object.

Note

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

Parameters

tmp_path (pathlib.Path) –

Return type

py._path.local.LocalPath

### tmpdir_factory¶

`tmpdir_factory` is an instance of `TempdirFactory`:

final class `TempdirFactory`[source]

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

Note

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

`mktemp`(basename, numbered=True)[source]

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

Parameters
• basename (str) –

• numbered (bool) –

Return type

py._path.local.LocalPath

`getbasetemp`()[source]

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

Return type

py._path.local.LocalPath

## Hooks¶

Tutorial: Writing plugins

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

### Bootstrapping hooks¶

Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins).

`pytest_load_initial_conftests`(early_config, parser, args)[source]

Note

This hook will not be called for `conftest.py` files, only for setuptools plugins.

Parameters
• early_config (pytest.Config) – The pytest config object.

• args (List[str]) – Arguments passed on the command line.

• parser (pytest.Parser) – To add command line options.

Return type

None

`pytest_cmdline_preparse`(config, args)[source]

(Deprecated) modify command line arguments before option parsing.

This hook is considered deprecated and will be removed in a future pytest version. Consider using `pytest_load_initial_conftests` instead.

Note

This hook will not be called for `conftest.py` files, only for setuptools plugins.

Parameters
• config (pytest.Config) – The pytest config object.

• args (List[str]) – Arguments passed on the command line.

Return type

None

`pytest_cmdline_parse`(pluginmanager, args)[source]

Return an initialized config object, parsing the specified args.

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

Note

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

Parameters
Return type

Optional[Config]

`pytest_cmdline_main`(config)[source]

Called for performing the main command line action. The default implementation will invoke the configure hooks and runtest_mainloop.

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

Parameters

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

Return type

Optional[Union[ExitCode, int]]

### Initialization hooks¶

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

`pytest_addoption`(parser, pluginmanager)[source]

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

Note

This function should be implemented only in plugins or `conftest.py` files situated at the tests root directory due to how pytest discovers plugins during startup.

Parameters
Return type

None

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

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 `hookwrapper=True`.

`pytest_addhooks`(pluginmanager)[source]

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

Parameters

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

Return type

None

Note

This hook is incompatible with `hookwrapper=True`.

`pytest_configure`(config)[source]

Allow plugins and conftest files to perform initial configuration.

This hook is called for every plugin and initial conftest file after command line options have been parsed.

After that, the hook is called for other conftest files as they are imported.

Note

This hook is incompatible with `hookwrapper=True`.

Parameters

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

Return type

None

`pytest_unconfigure`(config)[source]

Called before test process is exited.

Parameters

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

Return type

None

`pytest_sessionstart`(session)[source]

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

Parameters

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

Return type

None

`pytest_sessionfinish`(session, exitstatus)[source]

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

Parameters
• session (pytest.Session) – The pytest session object.

• exitstatus (int) – The status which pytest will return to the system.

Return type

None

`pytest_plugin_registered`(plugin, manager)[source]

A new pytest plugin got registered.

Parameters
Return type

None

Note

This hook is incompatible with `hookwrapper=True`.

### Collection hooks¶

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

`pytest_collection`(session)[source]

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.

1. `pytest_collectreport(report)`

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

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

1. `pytest_collection_finish(session)`

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

3. 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 (pytest.Session) – The pytest session object.

Return type

Optional[object]

`pytest_ignore_collect`(collection_path, path, config)[source]

Return True to prevent considering this path for collection.

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.

:param pathlib.Path collection_path : The path to analyze. :param LEGACY_PATH path: The path to analyze (deprecated). :param pytest.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.

Parameters
Return type

Optional[bool]

`pytest_collect_file`(file_path, path, parent)[source]

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

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

• parent (Collector) –

Return type

Optional[Collector]

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.

`pytest_pycollect_makemodule`(module_path, path, parent)[source]

Return a 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).

Return type

Optional[Module]

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`.

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

`pytest_pycollect_makeitem`(collector, name, obj)[source]

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
Return type

Union[None, Item, Collector, List[Union[Item, Collector]]]

`pytest_generate_tests`(metafunc)[source]

Generate (multiple) parametrized calls to a test function.

Parameters

metafunc (Metafunc) –

Return type

None

`pytest_make_parametrize_id`(config, val, argname)[source]

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 (pytest.Config) – The pytest config object.

• val (object) – The parametrized value.

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

Return type

Optional[str]

Hooks for influencing test skipping:

`pytest_markeval_namespace`(config)[source]

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.

New in version 6.2.

Parameters

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

Returns

Return type

Dict[str, Any]

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

`pytest_collection_modifyitems`(session, config, items)[source]

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

Parameters
Return type

None

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)[source]

Called after collection has been performed and modified.

Parameters

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

Return type

None

### Test running (runtest) hooks¶

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

`pytest_runtestloop`(session)[source]

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 (pytest.Session) – The pytest session object.

Return type

Optional[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.

`pytest_runtest_protocol`(item, nextitem)[source]

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 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 (Optional[Item]) – The scheduled-to-be-next test item (or None if this is the end my friend).

Return type

Optional[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.

`pytest_runtest_logstart`(nodeid, location)[source]

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, Optional[int], str]) – A tuple of `(filename, lineno, testname)`.

Return type

None

`pytest_runtest_logfinish`(nodeid, location)[source]

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, Optional[int], str]) – A tuple of `(filename, lineno, testname)`.

Return type

None

`pytest_runtest_setup`(item)[source]

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) –

Return type

None

`pytest_runtest_call`(item)[source]

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

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

Parameters

item (Item) –

Return type

None

`pytest_runtest_teardown`(item, nextitem)[source]

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
• nextitem (Optional[Item]) – 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.

• item (Item) –

Return type

None

`pytest_runtest_makereport`(item, call)[source]

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
Return type

Optional[TestReport]

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

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)[source]

Call underlying test function.

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

Parameters

pyfuncitem (Function) –

Return type

Optional[object]

### Reporting hooks¶

Session related reporting hooks:

`pytest_collectstart`(collector)[source]

Collector starts collecting.

Parameters

collector (Collector) –

Return type

None

`pytest_make_collect_report`(collector)[source]

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

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

Parameters

collector (Collector) –

Return type

Optional[CollectReport]

`pytest_itemcollected`(item)[source]

We just collected a test item.

Parameters

item (Item) –

Return type

None

`pytest_collectreport`(report)[source]

Collector finished collecting.

Parameters

report (CollectReport) –

Return type

None

`pytest_deselected`(items)[source]

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

May be called multiple times.

Parameters

items (Sequence[Item]) –

Return type

None

`pytest_report_header`(config, start_path, startdir)[source]

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

Parameters
• config (pytest.Config) – The pytest config object.

• start_path (Path) – The starting dir.

• startdir (LEGACY_PATH) – The starting dir (deprecated).

Return type

Union[str, List[str]]

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.

Note

This function should be implemented only in plugins or `conftest.py` files situated at the tests root directory due to how pytest discovers plugins during startup.

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.

`pytest_report_collectionfinish`(config, start_path, startdir, items)[source]

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.

New in version 3.2.

Parameters
• config (pytest.Config) – The pytest config object.

• start_path (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.

Return type

Union[str, List[str]]

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.

`pytest_report_teststatus`(report, config)[source]

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
Return type

Tuple[str, str, Union[str, Mapping[str, bool]]]

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

`pytest_report_to_serializable`(config, report)[source]

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

Parameters
Return type

Optional[Dict[str, Any]]

`pytest_report_from_serializable`(config, data)[source]

Restore a report object previously serialized with `pytest_report_to_serializable`.

Parameters
• config (Config) –

• data (Dict[str, Any]) –

Return type

Optional[Union[CollectReport, TestReport]]

`pytest_terminal_summary`(terminalreporter, exitstatus, config)[source]

Add a section to terminal summary reporting.

Parameters
• terminalreporter (_pytest.terminal.TerminalReporter) – The internal terminal reporter object.

• exitstatus (int) – The exit status that will be reported back to the OS.

• config (pytest.Config) – The pytest config object.

Return type

None

New in version 4.2: The `config` parameter.

`pytest_fixture_setup`(fixturedef, request)[source]

Perform fixture setup execution.

Returns

The return value of the call to the fixture function.

Parameters
• fixturedef (FixtureDef[Any]) –

• request (SubRequest) –

Return type

Optional[object]

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.

`pytest_fixture_post_finalizer`(fixturedef, request)[source]

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]) –

• request (SubRequest) –

Return type

None

`pytest_warning_recorded`(warning_message, when, nodeid, location)[source]

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 (str) –

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.

• location (tuple|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.

Return type

None

New in version 6.0.

Central hook for reporting about test execution:

`pytest_runtest_logreport`(report)[source]

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.

Parameters

report (TestReport) –

Return type

None

Assertion related hooks:

`pytest_assertrepr_compare`(config, op, left, right)[source]

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
Return type

Optional[List[str]]

`pytest_assertion_pass`(item, lineno, orig, expl)[source]

Called whenever an assertion passes.

New 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` ini-file option:

```[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 (pytest.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.

Return type

None

### Debugging/Interaction hooks¶

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

`pytest_internalerror`(excrepr, excinfo)[source]

Called for internal errors.

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

Parameters
Return type

Optional[bool]

`pytest_keyboard_interrupt`(excinfo)[source]

Called for keyboard interrupt.

Parameters

excinfo (ExceptionInfo[Union[KeyboardInterrupt, Exit]]) –

Return type

None

`pytest_exception_interact`(node, call, report)[source]

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
Return type

None

`pytest_enter_pdb`(config, pdb)[source]

Called upon pdb.set_trace().

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

Parameters
Return type

None

`pytest_leave_pdb`(config, pdb)[source]

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
Return type

None

## Objects¶

Full reference to objects accessible from fixtures or hooks.

### CallInfo¶

final class `CallInfo`[source]

Result/Exception info of a function invocation.

`excinfo`: Optional[_pytest._code.code.ExceptionInfo[BaseException]]

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”.

`result`

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)[source]

Call func, wrapping the result in a CallInfo.

Parameters
• func (Callable[[], TResult]) – The function to call. Called without arguments.

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

• reraise (Optional[Union[Type[BaseException], Tuple[Type[BaseException], ..]]]) – Exception or exceptions that shall propagate if raised by the function, instead of being wrapped in the CallInfo.

Return type

CallInfo[TResult]

### Class¶

class `Class`[source]

Bases: `_pytest.python.PyCollector`

Collector for test methods.

classmethod `from_parent`(parent, *, name, obj=None, **kw)[source]

The public constructor.

`collect`()[source]

Return a list of children (items and collectors) for this collection node.

Return type

Iterable[Union[_pytest.nodes.Item, _pytest.nodes.Collector]]

### Collector¶

class `Collector`[source]

Collector instances create children through collect() and thus iteratively build a tree.

exception `CollectError`[source]

Bases: `Exception`

An error during collection, contains a custom message.

`collect`()[source]

Return a list of children (items and collectors) for this collection node.

Return type

Iterable[Union[_pytest.nodes.Item, _pytest.nodes.Collector]]

`repr_failure`(excinfo)[source]

Return a representation of a collection failure.

Parameters

excinfo (_pytest._code.code.ExceptionInfo[BaseException]) – Exception information for the failure.

Return type

Union[str, _pytest._code.code.TerminalRepr]

### CollectReport¶

final class `CollectReport`[source]

Bases: `_pytest.reports.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`: Union[None, _pytest._code.code.ExceptionInfo[BaseException], Tuple[str, int, str], str, _pytest._code.code.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.

`caplog`

Return captured log lines, if log capturing is enabled.

New in version 3.5.

`capstderr`

Return captured text from stderr, if capturing is enabled.

New in version 3.0.

`capstdout`

Return captured text from stdout, if capturing is enabled.

New in version 3.0.

`count_towards_summary`

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.

`failed`

Whether the outcome is failed.

`fspath`

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

`head_line`

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.

`longreprtext`

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

New in version 3.0.

`passed`

Whether the outcome is passed.

`skipped`

Whether the outcome is skipped.

### Config¶

final class `Config`[source]

Parameters
final class `InvocationParams`(args, plugins, dir)[source]

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

New in version 5.1.

Note

Note that the environment variable `PYTEST_ADDOPTS` and the `addopts` ini 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`: Optional[Sequence[Union[str, object]]]

Extra plugins, might be `None`.

`dir`: pathlib.Path

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

`option`

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

`rootpath`

The path to the rootdir.

Type

pathlib.Path

New in version 6.1.

`inipath`

The path to the configfile.

Type

Optional[pathlib.Path]

New in version 6.1.

`add_cleanup`(func)[source]

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

Parameters

func (Callable[[], None]) –

Return type

None

classmethod `fromdictargs`(option_dict, args)[source]

Constructor usable for subprocesses.

Return type

_pytest.config.Config

`issue_config_time_warning`(warning, stacklevel)[source]

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 hookwrappers 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.

Return type

None

`addinivalue_line`(name, line)[source]

Add a line to an ini-file 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.

Parameters
• name (str) –

• line (str) –

Return type

None

`getini`(name)[source]

Return configuration value from an ini file.

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

Parameters

name (str) –

`getoption`(name, default=<NOTSET>, skip=False)[source]

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 – Default value if no option of that name exists.

• skip (bool) – If True, raise pytest.skip if option does not exists or has a None value.

`getvalue`(name, path=None)[source]

Parameters

name (str) –

`getvalueorskip`(name, path=None)[source]

Parameters

name (str) –

### ExceptionInfo¶

final class `ExceptionInfo`[source]

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

classmethod `from_exc_info`(exc_info, exprinfo=None)[source]

Return an ExceptionInfo for an existing exc_info tuple.

Warning

Experimental API

Parameters
• exprinfo (Optional[str]) – A text string helping to determine if we should strip `AssertionError` from the output. Defaults to the exception message/`__str__()`.

• exc_info (Tuple[Type[E], E, traceback]) –

Return type

_pytest._code.code.ExceptionInfo[E]

classmethod `from_current`(exprinfo=None)[source]

Return an ExceptionInfo matching the current traceback.

Warning

Experimental API

Parameters

exprinfo (Optional[str]) – A text string helping to determine if we should strip `AssertionError` from the output. Defaults to the exception message/`__str__()`.

Return type

_pytest._code.code.ExceptionInfo[BaseException]

classmethod `for_later`()[source]

Return an unfilled ExceptionInfo.

Return type

_pytest._code.code.ExceptionInfo[E]

`fill_unfilled`(exc_info)[source]

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

Parameters

exc_info (Tuple[Type[E], E, traceback]) –

Return type

None

`type`

The exception class.

`value`

The exception value.

`tb`

The exception raw traceback.

`typename`

The type name of the exception.

`traceback`

The traceback.

`exconly`(tryshort=False)[source]

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

Parameters

tryshort (bool) –

Return type

str

`errisinstance`(exc)[source]

Return True if the exception is an instance of exc.

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

Parameters

exc (Union[Type[BaseException], Tuple[Type[BaseException], ..]]) –

Return type

bool

`getrepr`(showlocals=False, style='long', abspath=False, tbfilter=True, funcargs=False, truncate_locals=True, chain=True)[source]

Return str()able representation of this exception info.

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

• style (str) – long|short|no|native|value traceback style.

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

• tbfilter (bool) – Hide entries that contain a local variable `__tracebackhide__==True`. Ignored if `style=="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.

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

Return type

Union[ReprExceptionInfo, ExceptionChainRepr]

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

`match`(regexp)[source]

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.

Parameters

regexp (Union[str, Pattern[str]]) –

Return type

Literal[True]

### ExitCode¶

final class `ExitCode`(value)[source]

Encodes the valid exit codes by pytest.

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

New in version 5.0.

`OK` = 0

Tests passed.

`TESTS_FAILED` = 1

Tests failed.

`INTERRUPTED` = 2

pytest was interrupted.

`INTERNAL_ERROR` = 3

An internal error got in the way.

`USAGE_ERROR` = 4

pytest was misused.

`NO_TESTS_COLLECTED` = 5

pytest couldn’t find tests.

### File¶

class `File`[source]

Base class for collecting tests from a file.

### FixtureDef¶

final class `FixtureDef`[source]

Bases: `Generic`[`_pytest.fixtures.FixtureValue`]

A container for a fixture definition.

`scope`

Scope string, one of “function”, “class”, “module”, “package”, “session”.

### FSCollector¶

class `FSCollector`[source]

Bases: `_pytest.nodes.Collector`

classmethod `from_parent`(parent, *, fspath=None, path=None, **kw)[source]

The public constructor.

Parameters
• fspath (Optional[py._path.local.LocalPath]) –

• path (Optional[pathlib.Path]) –

### Function¶

class `Function`[source]

Bases: `_pytest.python.PyobjMixin`, `_pytest.nodes.Item`

An 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 is 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).

New in version 3.0.

classmethod `from_parent`(parent, **kw)[source]

The public constructor.

`function`

Underlying python ‘function’ object.

`runtest`()[source]

Execute the underlying test function.

Return type

None

`repr_failure`(excinfo)[source]

Return a representation of a collection or test failure.

Parameters

excinfo (_pytest._code.code.ExceptionInfo[BaseException]) – Exception information for the failure.

Return type

Union[str, _pytest._code.code.TerminalRepr]

### FunctionDefinition¶

class `FunctionDefinition`[source]

Bases: `_pytest.python.Function`

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

`runtest`()[source]

Execute the underlying test function.

Return type

None

`setup`()

Execute the underlying test function.

Return type

None

### Item¶

class `Item`[source]

A basic test invocation item.

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.

`runtest`()[source]

Run the test case for this item.

Must be implemented by subclasses.

Return type

None

`add_report_section`(when, key, content)[source]

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.

Return type

None

`reportinfo`()[source]

Get location information for this item for test reports.

Returns a tuple with three elements:

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

• The line number of the test (default `None`)

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

Return type

Tuple[Union[os.PathLike[str], str], Optional[int], str]

### MarkDecorator¶

class `MarkDecorator`[source]

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

`name`

Alias for mark.name.

`args`

Alias for mark.args.

`kwargs`

Alias for mark.kwargs.

`with_args`(*args, **kwargs)[source]

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.

Parameters
Return type

_pytest.mark.structures.MarkDecorator

### MarkGenerator¶

final class `MarkGenerator`[source]

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`[source]
`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)[source]

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`[source]

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)[source]

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 rather than at test setup time.

Can be called multiple times, 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 (Union[str, List[str], Tuple[str, ..]]) – A comma-separated string denoting one or more argument names, or a list/tuple of argument strings.

• argvalues (Iterable[Union[_pytest.mark.structures.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 (Union[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 (Optional[Union[Iterable[Optional[object]], Callable[[Any], Optional[object]]]]) –

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.

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 (Optional[_ScopeName]) – 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.

• _param_mark (Optional[_pytest.mark.structures.Mark]) –

Return type

None

### Module¶

class `Module`[source]

Bases: `_pytest.nodes.File`, `_pytest.python.PyCollector`

Collector for test classes and functions.

`collect`()[source]

Return a list of children (items and collectors) for this collection node.

Return type

Iterable[Union[_pytest.nodes.Item, _pytest.nodes.Collector]]

### Node¶

class `Node`[source]

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

Collector subclasses have children; Items are leaf nodes.

`fspath`: py._path.local.LocalPath

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`

A unique name within the scope of the parent node.

`parent`

The parent collector node.

`config`

The pytest config object.

`session`

The pytest session this node is part of.

`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[_pytest.mark.structures.Mark]

The marker objects belonging to this node.

`extra_keyword_matches`: Set[str]

Allow adding of extra keywords to use for matching.

`stash`

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

Type

Stash

classmethod `from_parent`(parent, **kw)[source]

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 (_pytest.nodes.Node) – The parent node of this Node.

`ihook`

fspath-sensitive hook proxy used to call pytest hooks.

`warn`(warning)[source]

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.

Return type

None

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.

`nodeid`

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

`listchain`()[source]

Return list of all parent collectors up to self, starting from the root of collection tree.

Return type

List[_pytest.nodes.Node]

`add_marker`(marker, append=True)[source]

Dynamically add a marker object to the node.

Parameters
• append (bool) – Whether to append the marker, or prepend it.

• marker (Union[str, _pytest.mark.structures.MarkDecorator]) –

Return type

None

`iter_markers`(name=None)[source]

Iterate over all markers of the node.

Parameters

name (Optional[str]) – If given, filter the results by the name attribute.

Return type

Iterator[_pytest.mark.structures.Mark]

for ... in `iter_markers_with_node`(name=None)[source]

Iterate over all markers of the node.

Parameters

name (Optional[str]) – If given, filter the results by the name attribute.

Returns

An iterator of (node, mark) tuples.

Return type

Iterator[Tuple[_pytest.nodes.Node, _pytest.mark.structures.Mark]]

`get_closest_marker`(name, default=None)[source]

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

Parameters
• default (Optional[_pytest.mark.structures.Mark]) – Fallback return value if no marker was found.

• name (str) – Name to filter by.

Return type

Optional[_pytest.mark.structures.Mark]

`listextrakeywords`()[source]

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

Return type

Set[str]

`addfinalizer`(fin)[source]

Register a function to be called 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().

Parameters

fin (Callable[[], object]) –

Return type

None

`getparent`(cls)[source]

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

Parameters

cls (Type[_NodeType]) –

Return type

Optional[_NodeType]

`repr_failure`(excinfo, style=None)[source]

Return a representation of a collection or test failure.

Parameters
• excinfo (_pytest._code.code.ExceptionInfo[BaseException]) – Exception information for the failure.

• style (Optional[_TracebackStyle]) –

Return type

Union[str, _pytest._code.code.TerminalRepr]

### Parser¶

final class `Parser`[source]

Parser for command line arguments and ini-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)[source]

Get (or create) a named option Group.

Name

Name of the option group.

Description

Long description for –help output.

After

Name of another group, used for ordering –help output.

Parameters
• name (str) –

• description (str) –

• after (Optional[str]) –

Return type

_pytest.config.argparsing.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)[source]

Register a command line option.

Opts

Option names, can be short or long options.

Attrs

Same attributes which the `add_argument()` function of the argparse library accepts.

Parameters
• opts (str) –

• attrs (Any) –

Return type

None

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)[source]

Parse and return a namespace object with known arguments at this point.

Parameters
Return type

argparse.Namespace

`parse_known_and_unknown_args`(args, namespace=None)[source]

Parse and return a namespace object with known arguments, and the remaining arguments unknown at this point.

Parameters
Return type

Tuple[argparse.Namespace, List[str]]

`addini`(name, help, type=None, default=None)[source]

Register an ini-file option.

Name

Name of the ini-variable.

Type

Type of the variable. 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

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

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

Default

Default value if no ini-file option exists but is queried.

Parameters
• name (str) –

• help (str) –

• type (Optional[Literal['string', 'paths', 'pathlist', 'args', 'linelist', 'bool']]) –

Return type

None

The value of ini-variables can be retrieved via a call to `config.getini(name)`.

### OptionGroup¶

class `OptionGroup`[source]

A group of options shown in its own section.

`addoption`(*optnames, **attrs)[source]

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
• optnames (str) –

• attrs (Any) –

Return type

None

### PytestPluginManager¶

final class `PytestPluginManager`[source]

Bases: `pluggy._manager.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.

`parse_hookimpl_opts`(plugin, name)[source]
Parameters
`parse_hookspec_opts`(module_or_class, name)[source]
Parameters

name (str) –

`register`(plugin, name=None)[source]

Register a plugin and return its canonical name or `None` if the name is blocked from registering. Raise a `ValueError` if the plugin is already registered.

Parameters
• plugin (object) –

• name (Optional[str]) –

Return type

Optional[str]

`getplugin`(name)[source]
Parameters

name (str) –

`hasplugin`(name)[source]

Return whether a plugin with the given name is registered.

Parameters

name (str) –

Return type

bool

`import_plugin`(modname, consider_entry_points=False)[source]

Import a plugin with `modname`.

If `consider_entry_points` is True, entry point names are also considered to find a plugin.

Parameters
• modname (str) –

• consider_entry_points (bool) –

Return type

None

`add_hookcall_monitoring`(before, after)

add before/after tracing functions for all hooks and return an undo function which, when called, will remove 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 `pluggy._callers._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 if they have been decorated accordingly.

`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 and return an undo function.

`get_canonical_name`(plugin)

Return canonical name for a plugin object. Note that a plugin may be registered under a different name which was specified by the caller of `register(plugin, name)`. To obtain the name of an registered plugin use `get_name(plugin)` instead.

`get_hookcallers`(plugin)

get all hook callers for the specified plugin.

`get_name`(plugin)

Return name for registered plugin or `None` if not registered.

`get_plugin`(name)

Return a plugin or `None` for the given name.

`get_plugins`()

return the set of registered plugins.

`has_plugin`(name)

Return `True` if a plugin with the given name is registered.

`is_blocked`(name)

return `True` if the given plugin name is blocked.

`is_registered`(plugin)

Return `True` if the plugin is already registered.

`list_name_plugin`()

return list of name/plugin pairs.

`list_plugin_distinfo`()

return list of distinfo/plugin tuples 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) – if given, loads only plugins with the given `name`.

Return type

int

Returns

return the number of loaded plugins by this call.

`set_blocked`(name)

block registrations of the given name, unregister if already registered.

`subset_hook_caller`(name, remove_plugins)

Return a new `_hooks._HookCaller` instance for the named method which manages calls to all registered plugins except the ones from remove_plugins.

`unregister`(plugin=None, name=None)

unregister a plugin object and all its contained hook implementations from internal data structures.

### Session¶

final class `Session`[source]
exception `Interrupted`

Signals that the test run was interrupted.

exception `Failed`

Bases: `Exception`

Signals a stop as failed test run.

`startpath`

The path from which pytest was invoked.

New in version 7.0.0.

`perform_collect`(args=None, genitems=True)[source]

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.

Parameters
• args (Optional[Sequence[str]]) –

• genitems (bool) –

Return type

Sequence[Union[_pytest.nodes.Item, _pytest.nodes.Collector]]

for ... in `collect`()[source]

Return a list of children (items and collectors) for this collection node.

Return type

Iterator[Union[_pytest.nodes.Item, _pytest.nodes.Collector]]

### TestReport¶

final class `TestReport`[source]

Bases: `_pytest.reports.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`: Optional[Tuple[str, Optional[int], 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.

`keywords`

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`: Union[None, _pytest._code.code.ExceptionInfo[BaseException], Tuple[str, int, str], str, _pytest._code.code.TerminalRepr]

None or a failure representation.

`when`: Optional[str]

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`

Time it took to run just the test.

classmethod `from_item_and_call`(item, call)[source]

Create and fill a TestReport with standard item and call info.

Parameters
Return type

TestReport

`caplog`

Return captured log lines, if log capturing is enabled.

New in version 3.5.

`capstderr`

Return captured text from stderr, if capturing is enabled.

New in version 3.0.

`capstdout`

Return captured text from stdout, if capturing is enabled.

New in version 3.0.

`count_towards_summary`

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.

`failed`

Whether the outcome is failed.

`fspath`

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

`head_line`

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.

`longreprtext`

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

New in version 3.0.

`passed`

Whether the outcome is passed.

`skipped`

Whether the outcome is skipped.

### _Result¶

Result object used within hook wrappers, see `_Result in the pluggy documentation` for more information.

### Stash¶

class `Stash`[source]

`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]
```
`__setitem__`(key, value)[source]

Set a value for key.

Parameters
• key (_pytest.stash.StashKey[T]) –

• value (T) –

Return type

None

`__getitem__`(key)[source]

Get the value for key.

Raises `KeyError` if the key wasn’t set before.

Parameters

key (_pytest.stash.StashKey[T]) –

Return type

T

`get`(key, default)[source]

Get the value for key, or return default if the key wasn’t set before.

Parameters
• key (_pytest.stash.StashKey[T]) –

• default (D) –

Return type

Union[T, D]

`setdefault`(key, default)[source]

Return the value of key if already set, otherwise set the value of key to default and return default.

Parameters
• key (_pytest.stash.StashKey[T]) –

• default (T) –

Return type

T

`__delitem__`(key)[source]

Delete the value for key.

Raises `KeyError` if the key wasn’t set before.

Parameters

key (_pytest.stash.StashKey[T]) –

Return type

None

`__contains__`(key)[source]

Return whether key was set.

Parameters

key (_pytest.stash.StashKey[T]) –

Return type

bool

`__len__`()[source]

Return how many items exist in the stash.

Return type

int

class `StashKey`[source]

Bases: `Generic`[`_pytest.stash.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.

## 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`

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.

`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_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_DISABLE_PLUGIN_AUTOLOAD`

`PYTEST_PLUGINS`

Contains comma-separated list of modules that should be loaded as plugins:

```export PYTEST_PLUGINS=mymodule.plugin,xdist
```
`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 (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 (regardless of value), pytest will use color in terminal output. `PY_COLORS` and `NO_COLOR` take precedence over `FORCE_COLOR`.

## Exceptions¶

final class `UsageError`[source]

Bases: `Exception`

Error in pytest usage or invocation.

## 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`

Warning emitted by the pytest assert rewrite module.

class `PytestCacheWarning`

Warning emitted by the cache plugin in various situations.

class `PytestCollectionWarning`

Warning emitted when pytest is not able to collect a file or symbol in a module.

class `PytestConfigWarning`

Warning emitted for configuration issues.

class `PytestDeprecationWarning`

Warning class for features that will be removed in a future version.

class `PytestExperimentalApiWarning`

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 `PytestUnhandledCoroutineWarning`

Warning emitted for an unhandled coroutine.

A coroutine was encountered when collecting test functions, but was not handled by any async-aware plugin. Coroutine test functions are not natively supported.

class `PytestUnknownMarkWarning`

Warning emitted on use of unknown markers.

See How to mark test functions with attributes for details.

class `PytestUnraisableExceptionWarning`

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`

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`, `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 `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 ini file content:

```# content of pytest.ini
[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 a directory where stores content of cache plugin. 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 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.

`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.

• `count`: like progress, but shows progress as the number of tests completed instead of a percent.

The default is `progress`, but you can fallback to `classic` if you prefer or the new mode is causing unexpected problems:

```# content of pytest.ini
[pytest]
console_output_style = classic
```
`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

```# content of pytest.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 issue #3155 for more details.

`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.

```# content of pytest.ini
[pytest]
faulthandler_timeout=5
```

`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.

```# content of pytest.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`

New 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.

```[pytest]
junit_duration_report = call
```
`junit_family`

New 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.

```[pytest]
junit_family = xunit2
```
`junit_logging`

New 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.

```[pytest]
junit_logging = system-out
```
`junit_log_passing_tests`

New 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`.

```[pytest]
junit_log_passing_tests = False
```
`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:

```[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

```[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`.

```[pytest]
log_cli = True
```
`log_cli_date_format`

Sets a `time.strftime()`-compatible string that will be used when formatting dates for live logging.

```[pytest]
log_cli_date_format = %Y-%m-%d %H:%M:%S
```

`log_cli_format`

Sets a `logging`-compatible string used to format live logging messages.

```[pytest]
log_cli_format = %(asctime)s %(levelname)s %(message)s
```

`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.

```[pytest]
log_cli_level = INFO
```

`log_date_format`

Sets a `time.strftime()`-compatible string that will be used when formatting dates for logging capture.

```[pytest]
log_date_format = %Y-%m-%d %H:%M:%S
```

`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.

```[pytest]
log_file = logs/pytest-logs.txt
```

`log_file_date_format`

Sets a `time.strftime()`-compatible string that will be used when formatting dates for the logging file.

```[pytest]
log_file_date_format = %Y-%m-%d %H:%M:%S
```

`log_file_format`

Sets a `logging`-compatible string used to format logging messages redirected to the logging file.

```[pytest]
log_file_format = %(asctime)s %(levelname)s %(message)s
```

`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.

```[pytest]
log_file_level = INFO
```

`log_format`

Sets a `logging`-compatible string used to format captured logging messages.

```[pytest]
log_format = %(asctime)s %(levelname)s %(message)s
```

`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.

```[pytest]
log_level = INFO
```

`markers`

When the `--strict-markers` or `--strict` command-line arguments are used, 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 add `--strict-markers` to `addopts` to avoid future regressions:

```[pytest]
markers =
slow
serial
```

Note

The use of `--strict-markers` is highly preferred. `--strict` was kept for backward compatibility only and may be confusing for others as it only applies to markers and not to other options.

`minversion`

Specifies a minimal pytest version required for running tests.

```# content of pytest.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:

```[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 by the presence of an activation script. 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`:

```[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:

```[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`:

```[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.

```[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.

```[pytest]
required_plugins = pytest-django>=3.0.0,<4.0.0 pytest-html pytest-xdist>=1.0.0
```
`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. Useful when all project tests are in a known location to speed up test collection and to avoid picking up undesired tests by accident.

```[pytest]
testpaths = testing doc
```

This tells pytest to only look for tests in `testing` and `doc` directories when executing from the root directory.

`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.

```[pytest]
usefixtures =
clean_db
```
`xfail_strict`

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.

```[pytest]
xfail_strict = True
```

## Command-line Flags¶

All the command-line flags can 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 evaluatable
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.
--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={all,none}, --last-failed-no-failures={all,none}
which tests to run with no previously (known)
failures.
--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.

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
-v, --verbose         increase verbosity.
--no-summary          disable summary
-q, --quiet           decrease verbosity.
--verbosity=VERBOSE   set verbosity. Default is 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).
--tb=style            traceback print mode
(auto/long/short/line/native/no).
--show-capture={no,stdout,stderr,log,all}
Controls how captured stdout/stderr/log is shown on
failed tests. Default is '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)
--pastebin=mode       send failed|all info to bpaste.net pastebin service.
--junit-xml=path      create junit-xml style report file at given path.
--junit-prefix=str    prepend prefix to classnames in junit-xml output

pytest-warnings:
-W PYTHONWARNINGS, --pythonwarnings=PYTHONWARNINGS
set which warnings to report, see -W option of
python itself.
--maxfail=num         exit after first num failures or errors.
--strict-config       any warnings encountered while parsing the `pytest`
section of the configuration file raise errors.
--strict-markers      markers not registered in the `markers` section of
the configuration file raise errors.
--strict              (deprecated) alias to --strict-markers.
locate one of the implicit configuration files.
--continue-on-collection-errors
Force test execution even if collection errors
occur.
--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'.

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
--import-mode={prepend,append,importlib}
prepend/append to sys.path when importing test
modules and conftest files, default is to 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 ImportErrors
--doctest-continue-on-failure
for a given doctest, continue to run after the first
failure

test session debugging and configuration:
--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
-h, --help            show help message and configuration info
-p name               early-load given plugin module name or entry point
(multi-allowed).
e.g. `no:doctest`.
--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
Defaults to 'pytestdebug.log'.
-o OVERRIDE_INI, --override-ini=OVERRIDE_INI
override ini option with "option=value" style, e.g.
`-o xfail_strict=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 as used by the logging module.
--log-date-format=LOG_DATE_FORMAT
log date format as used by the logging module.
--log-cli-level=LOG_CLI_LEVEL
cli logging level.
--log-cli-format=LOG_CLI_FORMAT
log format as used by the logging module.
--log-cli-date-format=LOG_CLI_DATE_FORMAT
log date format as used by the logging module.
--log-file=LOG_FILE   path to a file when logging will be written to.
--log-file-level=LOG_FILE_LEVEL
log file logging level.
--log-file-format=LOG_FILE_FORMAT
log format as used by the logging module.
--log-file-date-format=LOG_FILE_DATE_FORMAT
log date format as 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.

[pytest] ini-options in the first pytest.ini|tox.ini|setup.cfg file found:

markers (linelist):   markers for test functions
empty_parameter_set_mark (string):
default marker for empty parametersets
norecursedirs (args): directory patterns to avoid for recursion
testpaths (args):     directories to search for tests when no files or
directories are given in the command line.
filterwarnings (linelist):
Each line specifies a pattern for
warnings.filterwarnings. Processed after
-W/--pythonwarnings.
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)
console_output_style (string):
console output: "classic", or with additional
progress information ("progress" (percentage) |
"count").
xfail_strict (bool):  default for the strict parameter of xfail markers
when not given explicitly (default: False)
enable_assertion_pass_hook (bool):
Enables the pytest_assertion_pass hook.Make sure to
delete any previously generated pyc cache files.
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):
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_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
pythonpath (paths):   Add paths to sys.path
faulthandler_timeout (string):
Dump the traceback of all threads if a test takes
more than TIMEOUT seconds to finish.
addopts (args):       extra command line options
minversion (string):  minimally required pytest version
required_plugins (args):
plugins that must be present for pytest to run

environment variables: