.. _setup-matrix:

===================
 Test Setup Matrix
===================

:Release: |version|
:Date: |today|

The plugin simplifies the setup of test environments by utilizing the
`pytest fixtures mechanism <https://docs.pytest.org/en/latest/reference/fixtures.html#fixtures>`_ to configure
each component of the test setup independently which allows for a high degree of flexibility in matching
specific Celery architectures to each test case.

In this guide we'll discuss how does the setup matrix work and how to use it.

.. contents::
    :local:
    :depth: 2

What is the setup matrix?
=========================

.. versionadded:: 1.0.0

The setup matrix is a combination of all of the possible Celery architectures that can be used
with the available :ref:`vendors` for each test. It is automatically generated by the plugin
to match the installed dependencies when using the default configuration, or it can be manually
configured to set each test case separately.

The matrix is configured using the :ref:`default-fixtures` of each component and is available
to the test case using the :ref:`test-setup`.

Common Setups
=============

.. versionadded:: 1.0.0

The following snippets show how to use the setup matrix to configure manual setups, overriding
the default configuration using the built-in :ref:`vendors`.

It may be used in conftest.py or in the test file itself.

RabbitMQ Broker and No Backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Use only RabbitMQ as the broker.

.. code-block:: python

    @pytest.fixture
    def celery_broker_cluster(celery_rabbitmq_broker: RabbitMQTestBroker) -> CeleryBrokerCluster:
        cluster = CeleryBrokerCluster(celery_rabbitmq_broker)
        yield cluster
        cluster.teardown()

2. :ref:`Disable the backend <disable_backend>`.

.. code-block:: python

    @pytest.fixture
    def celery_backend_cluster():
        return None

RabbitMQ Broker and Redis Backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Use only RabbitMQ as the broker.

.. code-block:: python

    @pytest.fixture
    def celery_broker_cluster(celery_rabbitmq_broker: RabbitMQTestBroker) -> CeleryBrokerCluster:
        cluster = CeleryBrokerCluster(celery_rabbitmq_broker)
        yield cluster
        cluster.teardown()

2. Use Redis as the backend.

.. code-block:: python

    @pytest.fixture
    def celery_backend_cluster(celery_redis_backend: RedisTestBackend) -> CeleryBackendCluster:
        cluster = CeleryBackendCluster(celery_redis_backend)
        yield cluster
        cluster.teardown()

Redis Broker and No Backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Use only Redis as the broker.

.. code-block:: python

    @pytest.fixture
    def celery_broker_cluster(celery_redis_broker: RedisTestBroker) -> CeleryBrokerCluster:
        cluster = CeleryBrokerCluster(celery_redis_broker)
        yield cluster
        cluster.teardown()

2. :ref:`Disable the backend <disable_backend>`.

.. code-block:: python

    @pytest.fixture
    def celery_backend_cluster():
        return None

Redis Broker and Redis Backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Use only Redis as the broker.

.. code-block:: python

    @pytest.fixture
    def celery_broker_cluster(celery_redis_broker: RedisTestBroker) -> CeleryBrokerCluster:
        cluster = CeleryBrokerCluster(celery_redis_broker)
        yield cluster
        cluster.teardown()

2. Use Redis as the backend.

.. code-block:: python

    @pytest.fixture
    def celery_backend_cluster(celery_redis_backend: RedisTestBackend) -> CeleryBackendCluster:
        cluster = CeleryBackendCluster(celery_redis_backend)
        yield cluster
        cluster.teardown()