diff --git a/docs/developers/contributing/testing.md b/docs/developers/contributing/testing.md index dada85d8e..ff168fd08 100644 --- a/docs/developers/contributing/testing.md +++ b/docs/developers/contributing/testing.md @@ -143,18 +143,87 @@ in `System Settings > Privacy & Security > Accessibility` so `pyautogui` can con It is also possible to run tests locally using `tox`. We use `tox` to run test in CI. The main difference between running `pytest` locally or `tox` locally is that `tox` will create a virtual environment for each test environment, so it will take a bit more time. Though, `tox` will be more similar to the CI environment. +The only requirement for running tests is to have `tox` in your environment and the target Python version discoverable on your system. To run test using `tox` using Python 3.13 and pyqt6 on Linux, enter: ```sh -tox -e py313-linux-pyqt6 +tox -e py313-linux-pyqt6-no_cov ``` -To get list of all available environments that may be run: +To get the list of all available environments that may be run: ```sh tox list ``` +#### Minimum requirements testing. + +One of our test suite entries is testing napari against minimum requirements declared in `pyproject.toml` file. +This checks if napari will still work, even if someone have outdated dependencies installed in their environment. +Most often if something is failing in this test run it is either a simple change or reason to bump minimum requirements in `pyproject.toml` file. + +To run this test use: + +```sh +MIN_REQ=1 tox -e py311-linux-pyqt5-no_cov --recreate +``` + +or + +```sh +MIN_REQ=1 tox -e py311-windows-pyqt5-no_cov --recreate +``` + +Unfortunately, it is impossible to test this on arm macOS, because of lack of pyqt5 support for this platform. + +#### Speed up tox environment creation + +To speed up the setup of creation of tox environments you can install `tox-uv` plugin that uses `uv` in +place of `pip` plus `virtualenv` to create tox environments. +The only disadvantage of this method is that it install `uv` in your environment +that is making precedence over global `uv` installation. +So you need to remember to regularly update one more `uv` installation. + +#### Running with constraints + +For fully reproduce CI environment you might use constraints files for tox environment creation. +For example, to run tests using Python 3.13 and pyqt6 on Linux with a constraints file, enter: + +```sh +PIP_CONSTRAINT=resources/constraints/constraints_py313.txt tox -e py313-linux-pyqt6-no_cov +``` + +or with `tox-uv` + +```sh +UV_CONSTRAINT=resources/constraints/constraints_py313.txt tox -e py313-linux-pyqt6-no_cov +``` + +Constraint usage guarantees the same version of dependencies as in CI environment. Its usually isn’t needed, but it sometimes happens that the newest version of some dependency is not compatible with napari test suite, and it is good to have a way to run tests with the same versions of dependencies as in the CI environment. + +#### Running a subset of test using tox + +The part of tox call after `--` is passed to pytest. So you can run a subset of tests using tox as well. For example, to run only tests in `src/napari/layers/image/` file using Python 3.13 and pyqt6 on Linux, enter: + +```sh +tox -e py313-linux-pyqt6-no_cov -- src/napari/layers/image +``` + +#### Use tox to create an environment for debugging + +The `tox` provides a convenient way to create a virtual environment for debugging. You can use `devenv` command to create a virtual environment for debugging. For example, to create a virtual environment for debugging using Python 3.13 and pyqt6 on Linux, enter: + +```sh +$ tox devenv -e py313-linux-pyqt6-no_cov +``` +Then at the end of the output is a path to created virtual environment. + +```sh +... +ROOT: created development environment under /Users/grzegorzbokota/Documents/Projekty/napari/venv +``` +That you can activate in your IDE or terminal as a normal virtual environment. + ### Run tests without pop-up windows Some tests create visible napari viewers, which pop up on your monitor then quickly disappear.