From 735ed9d2122d924653264948f5998c4b8faec7d6 Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Wed, 24 Sep 2025 10:08:44 +0200 Subject: [PATCH 1/2] docs: Update contributing guidelines with instructions to run tests with tox --- CONTRIBUTING.md | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 313910fe56..e8baca7f5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -74,19 +74,35 @@ That's it. You should be ready to make changes, run tests, and make commits! If ## Running Tests -You can run all tests with the following command: +We test against a number of Python language and library versions, which are automatically generated and stored in the [tox.ini](tox.ini) file. The `envlist` defines the environments you can choose from when running tests, and correspond to package versions and environment variables. The `TESTPATH` environment variable, in turn, determines which tests are run. + +The tox CLI tool is required to run the tests locally. Follow [the installation instructions](https://tox.wiki/en/latest/installation.html) for tox. Dependencies are installed for you when you run the command below, but _you_ need to bring an appropriate Python interpreter. Versions 3.8 and up can be installed with brew. + +An environment consists of the Python major and minor version and the library name and version. The exception to the rule is that you can provide `common` instead of the library information. The environments tied to a specific library usually run the corresponding test suite, while `common` targets all tests but skips those that require uninstalled dependencies. + +To run Celery tests for version v5.5.3 of its Python library using a 3.12 interpreter, use + +```bash +tox -p auto -o -e py3.12-celery-v5.5.3 +``` + +or to use the `common` environment, run ```bash -pytest tests/ +tox -p auto -o -e py3.12-common ``` -If you would like to run the tests for a specific integration, use a command similar to the one below: +To select specific tests, you can forward arguments to `pytest` like so ```bash -pytest -rs tests/integrations/flask/ # Replace "flask" with the specific integration you wish to test +tox -p auto -o -e py3.12-celery-v5.5.3 -- -k test_transaction_events ``` -**Hint:** Tests of integrations need additional dependencies. The switch `-rs` will show you why tests were skipped and what dependencies you need to install for the tests to run. (You can also consult the [tox.ini](tox.ini) file to see what dependencies are installed for each integration) +In general, you use + +```bash +tox -p auto -o -e -- +``` ## Adding a New Integration From 1b507dc59f685f8c8c0f524adbc9751505e80ebb Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Wed, 24 Sep 2025 12:09:14 +0200 Subject: [PATCH 2/2] Add pyenv link --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e8baca7f5e..89330087d9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -76,7 +76,9 @@ That's it. You should be ready to make changes, run tests, and make commits! If We test against a number of Python language and library versions, which are automatically generated and stored in the [tox.ini](tox.ini) file. The `envlist` defines the environments you can choose from when running tests, and correspond to package versions and environment variables. The `TESTPATH` environment variable, in turn, determines which tests are run. -The tox CLI tool is required to run the tests locally. Follow [the installation instructions](https://tox.wiki/en/latest/installation.html) for tox. Dependencies are installed for you when you run the command below, but _you_ need to bring an appropriate Python interpreter. Versions 3.8 and up can be installed with brew. +The tox CLI tool is required to run the tests locally. Follow [the installation instructions](https://tox.wiki/en/latest/installation.html) for tox. Dependencies are installed for you when you run the command below, but _you_ need to bring an appropriate Python interpreter. + +[Pyenv](https://github.com/pyenv/pyenv) is a cross-platform utility for managing Python versions. You can also use a conventional package manager, but not all versions may be distributed in the package manager of your choice. For macOS, Versions 3.8 and up can be installed with Homebrew. An environment consists of the Python major and minor version and the library name and version. The exception to the rule is that you can provide `common` instead of the library information. The environments tied to a specific library usually run the corresponding test suite, while `common` targets all tests but skips those that require uninstalled dependencies.