Understanding pytest Configuration Files
Before I discuss how you can alter pytest’s default behavior, let’s run down all of the non-test files in pytest and specifically who should care about them. Everyone should know about these:
-
pytest.ini: This is the primary pytest configuration file that allows you to change default behavior. Since there are quite a few configuration changes you can make, a big chunk of this chapter is about the settings you can make in pytest.ini.
-
conftest.py: This is a local plugin to allow hook functions and fixtures for the directory where the conftest.py file exists and all subdirectories. conftest.py files are covered Chapter 5, Plugins.
-
__init__.py: When put into every test subdirectory, this file allows you to have identical test filenames in multiple test directories. We’ll look at an example of what can go wrong without __init__.py files in test directories in Avoiding Filename Collisions.
If you use tox, you’ll be interested in:
- tox.ini: This file is similar to pytest.ini, but for tox. However, you can put your pytest configuration here instead of having both a tox.ini and a pytest.ini file, saving you one configuration file. Tox is covered in Chapter 7, Using pytest with Other Tools.
If you want to distribute a Python package (like Tasks), this file will be of interest:
- setup.cfg: This is a file that’s also in ini file format and affects the behavior of setup.py. It’s possible to add a couple of lines to setup.py to allow you to run python setup.py test and have it run all of your pytest tests. If you are distributing a package, you may already have a setup.cfg file, and you can use that file to store pytest configuration. You’ll see how in Appendix 4, Packaging and Distributing Python Projects.
Regardless of which file you put your pytest configuration in, the format will mostly be the same.
For pytest.ini:
| | [pytest] |
| | addopts = -rsxX -l --tb=short --strict |
| | xfail_strict = true |
| | ... more options ... |
For tox.ini:
| | ... tox specific stuff ... |
| | |
| | [pytest] |
| | addopts = -rsxX -l --tb=short --strict |
| | xfail_strict = true |
| | ... more options ... |
For setup.cfg:
| | ... packaging specific stuff ... |
| | |
| | [tool:pytest] |
| | addopts = -rsxX -l --tb=short --strict |
| | xfail_strict = true |
| | ... more options ... |
The only difference is that the section header for setup.cfg is [tool:pytest] instead of [pytest].
List the Valid ini-file Options with pytest –help
You can get a list of all the valid settings for pytest.ini from pytest --help:
| | $ pytest --help |
| | ... |
| | [pytest] ini-options in the first pytest.ini|tox.ini|setup.cfg file found: |
| | |
| | markers (linelist) markers for test functions |
| | norecursedirs (args) directory patterns to avoid for recursion |
| | testpaths (args) directories to search for tests when no files or |
| | directories are given in the command line. |
| | usefixtures (args) list of default fixtures to be used with this project |
| | python_files (args) glob-style file patterns for Python test module discovery |
| | python_classes (args) prefixes or glob names for Python test class discovery |
| | python_functions (args) prefixes or glob names for Python test function and |
| | method discovery |
| | xfail_strict (bool) default for the strict parameter of xfail markers |
| | when not given explicitly (default: False) |
| | doctest_optionflags (args) option flags for doctests |
| | addopts (args) extra command line options |
| | minversion (string) minimally required pytest version |
| | ... |
You’ll look at all of these settings in this chapter, except doctest_optionflags, which is covered in Chapter 7, Using pytest with Other Tools.
Plugins Can Add ini-file Options
The previous settings list is not a constant. It is possible for plugins (and conftest.py files) to add ini file options. The added options will be added to the pytest --help output as well.
Now, let’s explore some of the configuration changes we can make with the builtin ini file settings available from core pytest.