How to invoke pytest¶
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
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
Run tests in a directory
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
"" 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
:: characters, and parameters from parameterization enclosed in
To run a specific test within a module:
To run all tests in a class:
Specifying a specific test method:
Specifying a specific parametrization of a test:
Run tests by marker expressions
pytest -m slow
Will run all tests which are decorated with the
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
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
setuptoolswhen the plugin is registered. For example to early-load the pytest-cov plugin you can use:
pytest -p pytest_cov
To disable loading specific plugins at invocation time, use the
together with the prefix
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
directly, except that calling via
python will also add the current directory to
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
# content of myinvoke.py
print("*** test run reporting finishing")
if __name__ == "__main__":
Running it will show that
MyPlugin was added and its
hook was invoked:
$ python myinvoke.py
*** test run reporting finishing
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.