- Get Started
- How-to guides
- How to invoke pytest
- How to write and report assertions in tests
- How to use fixtures
- How to mark test functions with attributes
- How to parametrize fixtures and test functions
- How to use subtests
- How to use temporary directories and files in tests
- How to monkeypatch/mock modules and environments
- How to run doctests
- How to re-run failed tests and maintain state between test runs
- How to handle test failures
- Managing pytest’s output
- How to manage logging
- How to capture stdout/stderr output
- How to capture warnings
- How to use skip and xfail to deal with tests that cannot succeed
- How to install and use plugins
- Writing plugins
- Writing hook functions
- How to use pytest with an existing test suite
- How to use
unittest-based tests with pytest - How to implement xunit-style set-up
- How to set up bash completion
- Reference guides
- Explanation
- Examples and customization tricks
About the project
- Changelog
- Contributing
- Backwards Compatibility Policy
- History
- Python version support
- Sponsor
- pytest for enterprise
- License
- Contact channels
Useful links
How to invoke pytest¶
In general, pytest is invoked with the commandpytest (see below forother ways to invoke pytest). This will execute all tests in all files whose names follow the formtest_*.py or\*_test.pyin the current directory and its subdirectories. More generally, pytest followsstandard 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 forreading arguments from file).
Run tests in a module
pytesttest_mod.py
Run tests in a directory
pytesttesting/
Run tests by keyword expressions
pytest-k'MyClass and not method'This will run tests which contain names that match the givenstring expression (case-insensitive),which can include Python operators that use filenames, class names and function names as variables.The example above will runTestMyClass.test_something but notTestMyClass.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 nameseparated by:: characters, and parameters from parameterization enclosed in[].
To run a specific test within a module:
pytesttests/test_mod.py::test_func
To run all tests in a class:
pytesttests/test_mod.py::TestClass
Specifying a specific test method:
pytesttests/test_mod.py::TestClass::test_method
Specifying a specific parametrization of a test:
pytesttests/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-mslow
To run all tests which are decorated with the annotated@pytest.mark.slow(phase=1) decorator,with thephase keyword argument set to1:
pytest-m"slow(phase=1)"For more information seemarks.
Run tests from packages
pytest--pyargspkg.testing
This will importpkg.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
wheretests_to_run.txt contains an entry per line, e.g.:
tests/test_file.pytests/test_mod.py::test_func[x1,y2]tests/test_mod.py::TestClass-m slow
This file can also be generated usingpytest--collect-only-q and modified as needed.
Getting help on version, option names, environment variables¶
pytest--version# shows where pytest was imported frompytest--fixtures# show available builtin function argumentspytest-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-pmypluginmodule
The option receives aname 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
importlibwhen the plugin isregistered. For example to early-load thepytest-cov plugin you can use:pytest-ppytest_cov
Disabling plugins¶
To disable loading specific plugins at invocation time, use the-p optiontogether with the prefixno:.
Example: to disable loading the plugindoctest, which is responsible forexecuting doctest tests from text files, invoke pytest like this:
pytest-pno:doctest
Other ways of calling pytest¶
Calling pytest throughpython-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 scriptpytest[...]directly, except that calling viapython will also add the current directory tosys.path.
Calling pytest from Python code¶
You can invokepytest from Python code directly:
retcode=pytest.main()
this acts as if you would call “pytest” from the command line.It will not raiseSystemExit but return theexit 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 topytest.main:
# content of myinvoke.pyimportsysimportpytestclassMyPlugin:defpytest_sessionfinish(self):print("*** test run reporting finishing")if__name__=="__main__":sys.exit(pytest.main(["-qq"],plugins=[MyPlugin()]))
Running it will show thatMyPlugin was added and itshook was invoked:
$ python myinvoke.py*** test run reporting finishing
Note
Callingpytest.main() will result in importing your tests and any modulesthat they import. Due to the caching mechanism of python’s import system,making subsequent calls topytest.main() from the same process will notreflect changes to those files between the calls. For this reason, makingmultiple calls topytest.main() from the same process (in order to re-runtests, for example) is not recommended.