### `pytest.mark.parametrize(*args: 'object', **kwargs: 'object')`

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

---

###
`pytest.fixture(fixture_function: 'FixtureFunction | None' = None, *, scope: '_ScopeName | Callable[[str, Config], _ScopeName]' = 'function', params: 'Iterable[object] | None' = None, autouse: 'bool' = False, ids: 'Sequence[object | None] | Callable[[Any], object | None] | None' = None, name: 'str | None' = None) -> 'FixtureFunctionMarker | FixtureFunctionDefinition'`

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.

:param scope:
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.

    See :ref:`dynamic scope` in the docs for more information.

:param params:
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``.

:param autouse:
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.

:param ids:
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.

:param name:
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>')``.

---

###
`pytest.raises(expected_exception: 'type[E] | tuple[type[E], ...] | None' = None, *args: 'Any', **kwargs: 'Any') -> 'RaisesExc[BaseException] | ExceptionInfo[E]'`

Assert that a code block/function call raises an exception type, or one of its subclasses.

:param expected_exception:
The expected exception type, or a tuple if one of multiple possible
exception types are expected. Note that subclasses of the passed exceptions
will also match.

    This is not a required parameter, you may opt to only use ``match`` and/or
    ``check`` for verifying the raised exception.

:kwparam str | re.Pattern[str] | None match:
If specified, a string containing a regular expression,
or a regular expression object, that is tested against the string
representation of the exception and its :pep:`678` `__notes__`
using :func:`re.search`.

    To match a literal string that may contain :ref:`special characters
    <re-syntax>`, the pattern can first be escaped with :func:`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")``.)

:kwparam Callable[[BaseException], bool] check:

    .. versionadded:: 8.4

    If specified, a callable that will be called with the exception as a parameter
    after checking the type and the match regex if specified.
    If it returns ``True`` it will be considered a match, if not it will
    be considered a failed match.

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

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

If the code block does not raise the expected exception (:class:`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 ``match`` argument searches the formatted exception string, which includes any
`PEP-678 <https://peps.python.org/pep-0678/>`__ ``__notes__``:

    >>> with pytest.raises(ValueError, match=r"had a note added"):  # doctest: +SKIP
    ...     e = ValueError("value must be 42")
    ...     e.add_note("had a note added")
    ...     raise e

The ``check`` argument, if provided, must return True when passed the raised exception
for the match to be successful, otherwise an :exc:`AssertionError` is raised.

    >>> import errno
    >>> with pytest.raises(OSError, check=lambda e: e.errno == errno.EACCES):
    ...     raise OSError(errno.EACCES, "no permission to view")

The context manager produces an :class:`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"

.. warning::

Given that ``pytest.raises`` matches subclasses, be wary of using it to match :class:`Exception` like this::

       # Careful, this will catch ANY exception raised.
       with pytest.raises(Exception):
           some_function()

Because :class:`Exception` is the base class of almost all exceptions, it is easy for this to hide
real bugs, where the user wrote this expecting a specific exception, but some other exception is being
raised due to a bug introduced during a refactoring.

Avoid using ``pytest.raises`` to catch :class:`Exception` unless certain that you really want to catch
**any** exception raised.

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

**Expecting exception groups**

When expecting exceptions wrapped in :exc:`BaseExceptionGroup` or
:exc:`ExceptionGroup`, you should instead use :class:`pytest.RaisesGroup`.

**Using with** ``pytest.mark.parametrize``

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

See :ref:`parametrizing_conditional_raising` for an example.

.. seealso::

    :ref:`assertraises` for more examples and detailed discussion.

**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 :ref:`the try statement <python:try>`.

---

### `pytest.skip(reason: 'str' = '', allow_module_level: 'bool' = False) -> 'NoReturn'`

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.

:param reason:
The message to show the user as reason for the skip.

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

    Defaults to False.

:raises pytest.skip.Exception:
The exception that is raised.

.. note::
It is better to use the :ref:`pytest.mark.skipif ref` 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 :py:data:`doctest.SKIP`)
to skip a doctest statically.

---
