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 look like:

my_package/__init__.py
my_package/utils.py
my_package/tests/__init__.py
my_package/tests/test_utils.py

The name of the test files should start with test_. We recommend taking a look at the Getting Started guide for pytest for how to write tests, as well as the Astropy guide on writing tests.

Running tests

Assuming you have installed pytest, the easiest way to run the tests is to run the pytest command:

pytest my_package

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

or with:

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 [tool:pytest] section to your setup.cfg file, for example:

[tool:pytest]
addopts = -v

will ensure that tests are always run in verbose mode.

Running doctests

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 setup.cfg file to make sure that this option is always enabled:

[tool:pytest]
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 define an [options.extras_require] section in your setup.cfg file named test which lists the dependencies required to run the tests (not including dependencies already mentioned in install_requires):

[options.extras_require]
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.