Where should I put tests when packaging python modules?

The Sample Project stores the tests outside the module.

The directory structure looks like this:

├── data│   └── data_file├── MANIFEST.in├── README.rst├── sample│   ├── __init__.py│   └── package_data.dat├── setup.cfg├── setup.py└── tests    ├── __init__.py    └── test_simple.py

Related: The Packing Guide: https://packaging.python.org/en/latest/

Hint: Don't follow the "The Hitchhiker's Guide to Packaging". It has not been updated since 2010!

(do not confuse both pages. The "The Hitchhiker’s Guide to Python" is a very solid book)

You should put your test module inside the module it tests according to The Hitchhiker's Guide to Packaging.

Here is their example:

TowelStuff/    bin/    CHANGES.txt    docs/    LICENSE.txt    MANIFEST.in    README.txt    setup.py    towelstuff/        __init__.py        location.py        utils.py        test/            __init__.py            test_location.py            test_utils.py

This way your module will be distributed with its tests and users can use them to verify that it works with their set up.

See http://the-hitchhikers-guide-to-packaging.readthedocs.org/en/latest/creation.html.

I personally create a single tests package as a sub package of the main package for a few reasons:

• If tests is in parallel with the root package there's an off chance you, or a user may misconfigure setup.py and accidentally expose a global package named tests that will cause a great deal of confusion and headache until you realize what has happened. Putting it in the main module solves this as it's now under a (hopefully) globally unique namespace.

• I don't like putting a test module within user package because test runners have to search through production code. This is probably not a problem for most. But, if you happen to be a hardware test engineer, you probably use the word 'test' a lot in your production code and don't want the unit test runner to pick that stuff up. It's much easier if all the tests are in one place separate from the production code.

• I can further subdivide my tests folder into the types of tests, such as unit, functional and integration. My functional tests tend to have dependencies on weird proprietary hardware, data or are slow. So it's easy for me to continuously run just the fast unit test folder as I develop.

• It can sometimes be convenient to have the tests be inside of the same package hierarchy as what it is testing.

Overall though, I think it's important to think for yourself about what's best for your particular problem domain after taking everyone's advice into account. 'Best practices' are great starting points, not end points, for developing a process.