Testing your package¶
While writing new functionality for your package, you should also make sure that you write unit tests. We suggest using the pytest framework for writing and running tests.
Where to keep tests¶
We recommend placing the tests inside sub-folders called
tests alongside the
Python code they are meant to test - for example, the layout of the package might
my_package/__init__.py my_package/utils.py my_package/tests/__init__.py my_package/tests/test_utils.py
Assuming you have installed pytest, the easiest way to run the tests is to run the
Note that if your package contains C extension, you will need to make sure the extensions are compiled ahead of time - you can either do this with:
python setup.py build_ext --inplace
pip install -e .
Once you have done this, the pytest command should work. If your package defines
entry points, you will likely need to run the
pip command if you are running
tests that rely on the entry points.
Defining default pytest options¶
If you regularly need to run tests with the same command-line flags for your
package, or if you want to set options that are required for certain pytest
plugins, you can control these by adding a
pyproject.toml file; for example
[tool.pytest.ini_options] addopts = "-v"
will ensure that tests are always run in verbose mode.
It is possible to use pytest to run doctests (blocks of code in docstrings or in
the .rst docs) as part of the test suite. If you want to do this, we recommend
using the pytest-doctestplus <https://github.com/astropy/pytest-doctestplus>
plugin. You can define the following options in your
pyproject.toml file to make
sure that this option is always enabled
[tool.pytest.ini_options] doctest_plus = "enabled" addopts = "--doctest-rst"
Declaring dependencies for tests¶
To make it easier for contributors to get set up with the dependencies
required to run the tests, as well as to make it easier to
configure automated builds (with e.g. tox), you should
[project.optional-dependencies] section in
pyproject.toml file named
test which lists the dependencies
required to run the tests (not including dependencies already
[project.optional-dependencies] test = [ "pytest", "pytest-doctestplus", ]
This will then allow contributors to type
pip install -e .[test]
to install the package in developer/editable mode along with the test dependencies.