pytest - pytest usage

       holger krekel at merlinux eu

       2015, holger krekel and pytest-dev team

8.3.5                                             Mar 09, 2025                                         PYTEST(1)

          pytest --version   # shows where pytest was imported from
          pytest --fixtures  # show available builtin function arguments
          pytest -h | --help # show help on command line and config file options

Earlyloadingplugins
       You can early-load plugins (internal and external) explicitly in the command-line with the -p option:

          pytest -p mypluginmodule

       The option receives a name parameter, which can be:

       • A full module dotted name, for example myproject.plugins. This dotted name must be importable.

       • The entry-point name of a plugin. This is the name passed to importlib when the plugin  is  registered.
         For example to early-load the pytest-cov plugin you can use:

            pytest -p pytest_cov

   Disablingplugins
       To disable loading specific plugins at invocation time, use the -p option together with the prefix no:.

       Example:  to  disable  loading  the plugin doctest, which is responsible for executing doctest tests from
       text files, invoke pytest like this:

          pytest -p no:doctest

       pytest - pytest usage

       SEEALSO:Completepytestcommand-lineflagreference

       In  general,  pytest is invoked with the command pytest (see below for otherwaystoinvokepytest). This
       will execute all tests in all files whose names follow the form test_*.py or \*_test.py  in  the  current
       directory and its subdirectories. More generally, pytest follows standardtestdiscoveryrules.

Callingpytestthroughpython-mpytest
       You can invoke testing through the Python interpreter from the command line:

          python -m pytest [...]

       This is almost equivalent to invoking the command line script pytest[...]  directly, except that calling
       via python will also add the current directory to sys.path.

   CallingpytestfromPythoncode
       You can invoke pytest from Python code directly:

          retcode = pytest.main()

       this acts as if you would call "pytest" from the command line.  It will not raise SystemExit  but  return
       the  exitcode  instead.   If you don't pass it any arguments, main reads the arguments from the command
       line arguments of the process (sys.argv), which  may  be  undesirable.   You  can  pass  in  options  and
       arguments explicitly:

          retcode = pytest.main(["-x", "mytestdir"])

       You can specify additional plugins to pytest.main:

          # content of myinvoke.py
          import sys

          import pytest

          class MyPlugin:
              def pytest_sessionfinish(self):
                  print("*** test run reporting finishing")

          if __name__ == "__main__":
              sys.exit(pytest.main(["-qq"], plugins=[MyPlugin()]))

       Running it will show that MyPlugin was added and its hook was invoked:

          $ python myinvoke.py
          *** test run reporting finishing

       NOTE:
          Calling pytest.main() will result in importing your tests and any modules that they import. Due to the
          caching  mechanism  of  python's import system, making subsequent calls to pytest.main() from the same
          process will not reflect changes to those files between the calls. For this  reason,  making  multiple
          calls  to  pytest.main()  from  the  same  process  (in  order  to  re-run  tests, for example) is not
          recommended.

       Changed in version 6.0.

       To get a list of the slowest 10 test durations over 1.0s long:

          pytest --durations=10 --durations-min=1.0

       By  default, pytest will not show test durations that are too small (<0.005s) unless -vv is passed on the
       command-line.

       Pytest  supports several ways to run and select tests from the command-line or from a file (see below for
       readingargumentsfromfile).

       Runtestsinamodule

          pytest test_mod.py

       Runtestsinadirectory

          pytest testing/

       Runtestsbykeywordexpressions

          pytest -k 'MyClass and not method'

       This will run tests which contain names that match the given stringexpression (case-insensitive),  which
       can  include  Python  operators  that  use  filenames,  class names and function names as variables.  The
       example above will  run  TestMyClass.test_something   but  not  TestMyClass.test_method_simple.   Use  ""
       instead of '' in expression when running this on Windows

       Runtestsbycollectionarguments

       Pass  the  module  filename relative to the working directory, followed by specifiers like the class name
       and function name separated by :: characters, and parameters from parameterization enclosed in [].

       To run a specific test within a module:

          pytest tests/test_mod.py::test_func

       To run all tests in a class:

          pytest tests/test_mod.py::TestClass

       Specifying a specific test method:

          pytest tests/test_mod.py::TestClass::test_method

       Specifying a specific parametrization of a test:

          pytest tests/test_mod.py::test_func[x1,y2]

       Runtestsbymarkerexpressions

       To run all tests which are decorated with the @pytest.mark.slow decorator:

          pytest -m slow

       To run all tests which are decorated with the annotated @pytest.mark.slow(phase=1)  decorator,  with  the
       phase keyword argument set to 1:

          pytest -m "slow(phase=1)"

       For more information see marks.

       Runtestsfrompackages

          pytest --pyargs pkg.testing

       This will import pkg.testing and use its filesystem location to find and run tests from.

       Readargumentsfromfile

       Added in version 8.2.

       All of the above can be read from a file using the @ prefix:

          pytest @tests_to_run.txt

       where tests_to_run.txt contains an entry per line, e.g.:

          tests/test_file.py
          tests/test_mod.py::test_func[x1,y2]
          tests/test_mod.py::TestClass
          -m slow

       This file can also be generated using pytest--collect-only-q and modified as needed.