Skip to content

Commit d9811fe

Browse files
docs: Update contributing guidelines with instructions to run tests with tox (#4857)
Updating instructions to run unit tests with a little background about `tox` and some commands you can use to run the tests. Closes #4548
1 parent c3d3672 commit d9811fe

File tree

1 file changed

+23
-5
lines changed

1 file changed

+23
-5
lines changed

CONTRIBUTING.md

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -74,19 +74,37 @@ That's it. You should be ready to make changes, run tests, and make commits! If
7474

7575
## Running Tests
7676

77-
You can run all tests with the following command:
77+
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.
78+
79+
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.
80+
81+
[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.
82+
83+
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.
84+
85+
To run Celery tests for version v5.5.3 of its Python library using a 3.12 interpreter, use
7886

7987
```bash
80-
pytest tests/
88+
tox -p auto -o -e py3.12-celery-v5.5.3
8189
```
8290

83-
If you would like to run the tests for a specific integration, use a command similar to the one below:
91+
or to use the `common` environment, run
8492

8593
```bash
86-
pytest -rs tests/integrations/flask/ # Replace "flask" with the specific integration you wish to test
94+
tox -p auto -o -e py3.12-common
8795
```
8896

89-
**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)
97+
To select specific tests, you can forward arguments to `pytest` like so
98+
99+
```bash
100+
tox -p auto -o -e py3.12-celery-v5.5.3 -- -k test_transaction_events
101+
```
102+
103+
In general, you use
104+
105+
```bash
106+
tox -p auto -o -e <tox_env> -- <pytest_args>
107+
```
90108

91109
## Adding a New Integration
92110

0 commit comments

Comments
 (0)