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.

       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.

       Run tests by node ids

       Each  collected  test  is  assigned  a  unique nodeid which consist of the module filename
       followed  by  specifiers  like  class  names,   function   names   and   parameters   from
       parametrization, separated by :: characters.

       To run a specific test within a module:

          pytest test_mod.py::test_func

       Another example specifying a test method in the command line:

          pytest test_mod.py::TestClass::test_method

       Run tests by marker expressions

          pytest -m slow

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

       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.

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 setuptools when the  plugin
         is registered. For example to early-load the 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.  You can pass in options and arguments:

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

       You can specify additional plugins to pytest.main:

          # content of myinvoke.py
          import pytest
          import sys

          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

       2022, holger krekel and pytest-dev team