Table of Contents

When I try to run pytest locally for a Python project, I noticed that the import in those test scripts may fail if I run pytest in different directories. The import error usually means that your actual code modules is not in the python path, so they can not be imported successfully by your test scripts.

This has something to do with how pytest set up the python path when you run it.

change the python path
#

You can add other path to the sys.path by setting the pythonpath option. Multiple config file formats are supported. Here is how to do it in pyproject.toml:

[tool.pytest.ini_options]
pythonpath = ["/path/to/project/root"]

After you set it up correctly, the import error should be gone.

Note that you can not change sys.path with --rootdir option, the --rootdir is for other things like __pytest_cache directory. This is clearly documented in pytest official doc

using `python -m pytest`
#

This will add the current directory to sys.path, that is why the test scripts under unit_tests folder can import modules in the parent directory.

contest.py file
#

Create an empty conftest.py in the parent directory also works. See also https://github.com/pytest-dev/pytest/issues/4699 This may be a hacky way, but it should work.

should we add `init.py` to tests directory?
#

Suppose the tests folder is in the same level as the source code, and there is no __init__.py inside tests folder,

.
├── app/
│   ├── foo/
│   │   └── foo.py
│   ├── baz.py
│   └── bar/
└── tests/
    ├── unit_tests/
    └── test_foo.py

Pytest treat the test module under tests directory as standalone modules. When pytest run the test cases in a test module, it will insert the parent directory of this test module to sys.path. For example, when it runs test_foo.py, <project-root>/tests is inserted to sys.path. For it runs tests/unit_tests/test_bar.py, <project-root>/tests/unit_tests will be inserted to sys.path.

In this case, pytest use the base name of the test module as the module name (you can check this in the sys.modules table). So you can not have test modules with the same name under tests directory, even if they are in different directory.

If you have __init__.py like below, pytest will treat these as packages, and find the project root accordingly.

└── tests/
    ├── __init__.py
    ├── unit_tests/
    │   └── __init__.py
    └── test_foo.py

In this particular case, the project root will be the directory containing both tests and app directory. The full module name for test_foo.py will be tests.test_foo instead.

This is also explained in the official doc on standalone test modules.