Document how to use pytest in packages using meson-python

[dnicolodi]

There are two common directory layouts used by Python packages: tests source code alongside the Python source code, or tests source code in a dedicated package top-level directory. Some packages install the tests and some do not. AFAIU pytest 8.0 and later do not allow to have the tests files alongside the Python source code and execute them without installing them.

Example, given a package source code structure looking like:

meson.build
package/
   __init__.py
   _foo.pyx
   foo.py
   foo_test.py
pyproject.toml

The package needs to be installed to build the Cython extension module:

python -m pip install --no-build-isolation -e .

However, if foo_test.py is not installed, running pytest package/ results in tests loading errors because pytest imports pacakage.fo_test, which puts the package folder in the source directory in the modules cache, and it does not contain the _foo extension module. With pytest version previous to the 8.0 release, using the --import-mode=importlib option solved the issue. However, this is not true for pytest 8.0 and later.

The only solution I've found is to install the tests alongside the package. Then pytest package/ works as expected.

If a project does not want to have the tests as part of the distributed wheels, it needs either to add a meson build option that disables installing the tests and set it when building wheels for redistribution and not for development builds, or it needs to use install tags to filter the tests out and use -Cinstall-args=--tags=python-runtime,tests in development builds. I don't like the latter solution much, because it requires listing all the tags to be installed.

The pytest issue is not meson-python specific, it is more specific to packages using extension modules, but it is complex enough that it may be worth a mention somewhere in the documentation. Maybe we need a Development with meson-python section in the documentation.