This document describes the current stable version of pytest_celery (1.0). For development docs, go here.

Advanced Installation Guide

Release:

1.0

Date:

Apr 29, 2024

The pytest-celery plugin uses the environment dependencies to install and configure the default Test Setup Matrix. The available dependencies are the feature flags for the available Vendors.

This guide will explain how to install the plugin, how to use the dependencies feature flags and how to fit the configurations to your needs.

We will start by reviewing the standard installation instructions.

Installation

The pytest-celery plugin can be easily installed via the Python Package Index (PyPI) using pip.

Installing the pytest-celery package

To install the latest version of pytest-celery, run the following command:

pip install -U pytest-celery

This command installs pytest-celery along with its required dependencies.

This will include:

  • Latest version of celery.

  • RabbitMQ broker via kombu, installed as a dependency of Celery.

Installing pytest-celery vendors

The plugin detects which vendor dependencies are installed in the test environment to configure the default configurations automatically. This means that by just installing the matching dependencies, the plugin will allow extending the default configurations, up to the supported built-in Vendors.

Warning

If you don’t install any vendor (e.g. no extras and no manual installation), the plugin will result in an empty Test Setup Matrix and might not be fully functional.

To install the vendors, you may either install all of the dependencies manually, or use the following extras:

  • all: Installs all vendors.

  • redis: Installs Redis vendor, providing broker and result backend components.

  • memcached: Installs Memcached vendor, providing a result backend component.

The following extra is installed by default:

  • rabbitmq: Installs RabbitMQ vendor, providing a broker component.

To install pytest-celery with the built-in Vendors, replace <extra> with the name of the vendor.

pip install -U "pytest-celery[<extra>]"

RabbitMQ & Redis combo

pip install -U "pytest-celery[redis]"

This will configure the plugin to generate all possible setups using only RabbitMQ and Redis vendors.

All vendors

pip install -U "pytest-celery[all]"

This will configure the plugin to generate all possible setups.

This approach allows you to tailor the installation to your project’s specific needs by including only the necessary optional vendors.

Advanced Installation

New in version 1.0.0.

In this section, we’ll improve our understanding of the plugin installation process and how to customize it.

Feature Flags

The installed dependencies dynamically configure which vendors are available for the plugin to use. Each vendor will provide its set of components, such as the broker, backend, and the worker, and the plugin will automatically add the matching components to the default setup matrix.

For example, let’s assume you want to use the RabbitMQ/Redis combination.

  1. For RabbitMQ we will need kombu.

  2. For Redis we will need redis.

To install the plugin with the RabbitMQ/Redis combination, you will need to install the following dependencies:

pip install "pytest-celery[redis]"

Let’s break down the command:

  • The pytest-celery is the plugin package, it will install the plugin alongside Celery and its dependencies,including Kombu (if not installed already).

  • The [redis] is the feature flag for the Redis vendor, it will install the redis package and configure the plugin to use it which will add the Redis backend and Redis broker components to the default setup matrix.

Experimental Vendors

Vendors that are in not stable, will not be added to the default setup matrix. To use the experimental vendors, you will need to configure the setup matrix manually.

Tip

The automatic vendors detection is implemented in defaults.py.

The all Extra

The all extra is a special feature flag that will install all available vendors and their dependencies.

pip install "pytest-celery[all]"

This command will install the plugin and configure it to use all available stable vendors in a setup matrix for each test case that uses the Test Setup.

Warning

The all extra will install all of the vendors dependencies, including the experimental vendor’s dependencies, to allow manual configuration of the setup matrix.