NAME

       pytest - pytest usage

       SEE ALSO:
          Complete pytest command-line flag reference

       In  general, pytest is invoked with the command pytest (see below for other ways to invoke
       pytest). 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
       standard test discovery rules.

SPECIFYING WHICH TESTS TO RUN

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

       Run tests in a module

          pytest test_mod.py

       Run tests in a directory

          pytest testing/

       Run tests by keyword expressions

          pytest -k 'MyClass and not method'

       This  will  run  tests  which  contain  names  that  match  the  given  string  expression
       (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

       Run tests by collection arguments

       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]

       Run tests by marker expressions

       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.

       Run tests from packages

          pytest --pyargs pkg.testing

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

       Read arguments from file

       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.

GETTING HELP ON VERSION, OPTION NAMES, ENVIRONMENT VARIABLES

          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

PROFILING TEST EXECUTION DURATION

       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.

MANAGING LOADING OF PLUGINS

   Early loading plugins
       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
         :pypi:`pytest-cov`
          plugin you can use:

            pytest -p pytest_cov

   Disabling plugins
       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

OTHER WAYS OF CALLING PYTEST

   Calling pytest through python -m pytest
       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.

   Calling pytest from Python code
       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 exit code 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.

AUTHOR

       holger krekel at merlinux eu

COPYRIGHT

       2024, holger krekel and pytest-dev team