Add tests docs: params for Mock

main/tests.py

@@ -7,7 +7,6 @@ import random
 from unittest.mock import patch, Mock
 
 from django.contrib.auth import get_user_model
-# from django.contrib.auth.models import User
 from django.core import mail
 from django.http import HttpResponseRedirect
 from django.template.loader import render_to_string
@@ -171,13 +170,15 @@ class MakeEngineerTestCase(UsersBaseTestCase):
     """
     Класс тестирования присвоения пользователю роли engineer.
 
-    В тестах используется @patch('main.extra_func.zenpy') замещающий API Zendesk.
+    В тестах используется @patch('main.extra_func.zenpy') Mock для работы с API Zendesk.
     """
 
     @patch('main.extra_func.zenpy')
-    def test_become_engineer_redirect(self, _zenpy_mock: zenpy) -> None:
+    def test_become_engineer_redirect(self, _zenpy_mock: Mock) -> None:
         """
         Функция тестирования редиректа на рабочую страницу тестового пользователя при назначении его инженером.
+
+        :param _zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
         """
         user = get_user_model().objects.get(email=self.light_agent)
         resp = self.agent_client.post(reverse_lazy('work_become_engineer'))
@@ -185,41 +186,49 @@ class MakeEngineerTestCase(UsersBaseTestCase):
         self.assertEqual(resp.status_code, 302)
 
     @patch('main.extra_func.zenpy')
-    def test_light_agent_make_engineer(self, zenpy_mock: zenpy) -> None:
+    def test_light_agent_make_engineer(self, zenpy_mock: Mock) -> None:
         """
         Функция тестирования назначения легкого агента на роль инженера.
 
         Проверяет установку роли "engineer" в Zendesk.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
         """
         self.agent_client.post(reverse_lazy('work_become_engineer'))
         self.assertEqual(zenpy_mock.update_user.call_args[0][0].custom_role_id, sets.ZENDESK_ROLES['engineer'])
 
     @patch('main.extra_func.zenpy')
-    def test_admin_make_engineer(self, zenpy_mock: zenpy) -> None:
+    def test_admin_make_engineer(self, zenpy_mock: Mock) -> None:
         """
         Функция тестирования назначения администратора на роль инженера.
 
         Проверяет установку роли "engineer" в Zendesk.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
         """
         self.admin_client.post(reverse_lazy('work_become_engineer'))
         self.assertEqual(zenpy_mock.update_user.call_args[0][0].custom_role_id, sets.ZENDESK_ROLES['engineer'])
 
     @patch('main.extra_func.zenpy')
-    def test_engineer_make_engineer(self, zenpy_mock: zenpy) -> None:
+    def test_engineer_make_engineer(self, zenpy_mock: Mock) -> None:
         """
         Функция тестирования назначения инженера на роль инженера.
 
         Проверяет установку роли "engineer" в Zendesk.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
         """
         self.engineer_client.post(reverse_lazy('work_become_engineer'))
         self.assertEqual(zenpy_mock.update_user.call_args[0][0].custom_role_id, sets.ZENDESK_ROLES['engineer'])
 
     @patch('main.extra_func.zenpy')
-    def test_control_page_make_engineer_one(self, zenpy_mock: zenpy) -> None:
+    def test_control_page_make_engineer_one(self, zenpy_mock: Mock) -> None:
         """
         Функция тестирования назначения администратором одного инженера  на странице "Управление".
 
         Проверяет обновление администратором роли пользователя с light_agent на engineer.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
         """
         self.admin_client.post(
             reverse_lazy('control'),
@@ -232,11 +241,13 @@ class MakeEngineerTestCase(UsersBaseTestCase):
         self.assertEqual(mock_object.custom_role_id, sets.ZENDESK_ROLES['engineer'])
 
     @patch('main.extra_func.zenpy')
-    def test_control_page_make_engineer_many(self, zenpy_mock: zenpy) -> None:
+    def test_control_page_make_engineer_many(self, zenpy_mock: Mock) -> None:
         """
         Функция тестирования назначения администратором нескольких инженеров  на странице "Управление".
 
         Проверяет обновление администратором ролей двух пользователей с light_agent на engineer.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
         """
         self.admin_client.post(
             reverse_lazy('control'),
@@ -259,16 +270,19 @@ class MakeLightAgentTestCase(UsersBaseTestCase):
     """
     Класс тестирования присвоения пользователю роли light_agent.
 
-    В тестах используется @patch('main.extra_func.zenpy') замещающий API Zendesk, а также
+    В тестах используется @patch('main.extra_func.zenpy') Mock для работы API Zendesk, а также
-    @patch('main.requester.TicketListRequester.get_tickets_list_for_user', side_effect=[[]]), предоставляющий список
+    @patch('main.requester.TicketListRequester.get_tickets_list_for_user', side_effect=[[]]), предоставляющий пустой
-    тикетов.
+    список в качестве списка тикетов пользователя.
     """
 
     @patch('main.requester.TicketListRequester.get_tickets_list_for_user', side_effect=[[]])
     @patch('main.extra_func.zenpy')
-    def test_hand_over_redirect(self, _zenpy_mock: zenpy, _user_tickets_mock: list) -> None:
+    def test_hand_over_redirect(self, _zenpy_mock: Mock, _user_tickets_Mock: Mock) -> None:
         """
         Функция тестирования переадресации инженера на рабочую страницу, после сдачи прав.
+
+        :param _zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param _user_tickets_Mock: Mock, заменяющий список тикетов пользователя на пустой список.
         """
         user = get_user_model().objects.get(email=self.engineer)
         resp = self.engineer_client.post(reverse_lazy('work_hand_over'))
@@ -277,11 +291,14 @@ class MakeLightAgentTestCase(UsersBaseTestCase):
 
     @patch('main.requester.TicketListRequester.get_tickets_list_for_user', side_effect=[[]])
     @patch('main.extra_func.zenpy')
-    def test_engineer_make_light_agent_no_tickets(self, zenpy_mock: zenpy, _user_tickets_mock: list) -> None:
+    def test_engineer_make_light_agent_no_tickets(self, zenpy_mock: Mock, _user_tickets_mock: Mock) -> None:
         """
         Функция тестирования назначения инженера легким агентом, в случае, когда у него в работе нет тикетов.
 
         Проверяет назначение роли light_agent в Zendesk.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param _user_tickets_mock: Mock, заменяющий список тикетов пользователя на пустой список.
         """
         self.engineer_client.post(reverse_lazy('work_hand_over'))
         self.assertEqual(zenpy_mock.update_user.call_args[0][0].custom_role_id, sets.ZENDESK_ROLES['light_agent'])
@@ -290,7 +307,7 @@ class MakeLightAgentTestCase(UsersBaseTestCase):
         [Mock(id=1, status='solved'), Mock(id=2, status='open'), Mock(id=3, status='open')]
     ])
     @patch('main.extra_func.zenpy')
-    def test_engineer_make_light_agent_with_tickets(self, zenpy_mock: zenpy, _user_tickets_mock: list):
+    def test_engineer_make_light_agent_with_tickets(self, zenpy_mock: Mock, _user_tickets_mock: Mock) -> None:
         """
         Функция тестирования назначения инженера легким агентом, в случае, когда у него в работе есть тикеты.
 
@@ -298,6 +315,9 @@ class MakeLightAgentTestCase(UsersBaseTestCase):
         два в состоянии: открыт.
         Проверяет распределение тикетов (поместить в решенные или назначить нового ответственного),
         а также назначение роли light_agent в Zendesk.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param _user_tickets_mock: Mock, заменяющий список тикетов пользователя на пустой список.
         """
         zenpy_mock.solved_tickets_user_id = Mock()
         self.engineer_client.post(reverse_lazy('work_hand_over'))
@@ -310,11 +330,14 @@ class MakeLightAgentTestCase(UsersBaseTestCase):
 
     @patch('main.requester.TicketListRequester.get_tickets_list_for_user', side_effect=[[]])
     @patch('main.extra_func.zenpy')
-    def test_admin_make_light_agent_no_tickets(self, zenpy_mock: zenpy, _user_tickets_mock: list) -> None:
+    def test_admin_make_light_agent_no_tickets(self, zenpy_mock: Mock, _user_tickets_mock: Mock) -> None:
         """
         Функция тестирования назначения администратора на роль легкого агента.
 
         Проверяет назначение роли light_agent в Zendesk.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param _user_tickets_mock: Mock, заменяющий список тикетов пользователя на пустой список.
         """
         self.admin_client.post(reverse_lazy('work_hand_over'))
         self.assertEqual(zenpy_mock.update_user.call_args[0][0].custom_role_id, sets.ZENDESK_ROLES['light_agent'])
@@ -331,6 +354,9 @@ class MakeLightAgentTestCase(UsersBaseTestCase):
         два в состоянии: открыт.
         Проверяет распределение тикетов (поместить в решенные или назначить нового ответственного),
         а также назначение роли light_agent в Zendesk.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param _user_tickets_mock: Mock, заменяющий список тикетов пользователя на пустой список.
         """
         zenpy_mock.solved_tickets_user_id = Mock()
         self.admin_client.post(reverse_lazy('work_hand_over'))
@@ -343,22 +369,28 @@ class MakeLightAgentTestCase(UsersBaseTestCase):
 
     @patch('main.requester.TicketListRequester.get_tickets_list_for_user', side_effect=[[]])
     @patch('main.extra_func.zenpy')
-    def test_light_agent_make_light_agent(self, zenpy_mock: zenpy, _user_tickets_mock: list):
+    def test_light_agent_make_light_agent(self, zenpy_mock: Mock, _user_tickets_mock: Mock) -> None:
         """
         Функция тестирования назначения легкого агента на роль легкого агента.
 
         Проверяет назначение роли light_agent в Zendesk.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param _user_tickets_mock: Mock, заменяющий список тикетов пользователя на пустой список.
         """
         self.agent_client.post(reverse_lazy('work_hand_over'))
         self.assertEqual(zenpy_mock.update_user.call_args[0][0].custom_role_id, sets.ZENDESK_ROLES['light_agent'])
 
     @patch('main.requester.TicketListRequester.get_tickets_list_for_user', side_effect=[[]])
     @patch('main.extra_func.zenpy')
-    def test_control_page_make_light_agent_one(self, zenpy_mock: zenpy, _user_tickets_mock: list) -> None:
+    def test_control_page_make_light_agent_one(self, zenpy_mock: Mock, _user_tickets_mock: Mock) -> None:
         """
         Функция тестирования назначения администратором одного легкого агента на странице "Управление".
 
         Проверяет обновление администратором роли пользователя с engineer на light_agent.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param _user_tickets_mock: Mock, заменяющий список тикетов пользователя на пустой список.
         """
         self.admin_client.post(
             reverse_lazy('control'),
@@ -372,11 +404,14 @@ class MakeLightAgentTestCase(UsersBaseTestCase):
 
     @patch('main.requester.TicketListRequester.get_tickets_list_for_user', side_effect=[[], []])
     @patch('main.extra_func.zenpy')
-    def test_control_page_make_light_agent_many(self, zenpy_mock: zenpy, _user_tickets_mock: list) -> None:
+    def test_control_page_make_light_agent_many(self, zenpy_mock: Mock, _user_tickets_mock: Mock) -> None:
         """
         Функция тестирования назначения администратором нескольких легких агентов на странице "Управление".
 
         Проверяет обновление администратором ролей двух пользователей с engineer на light_agent.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param _user_tickets_mock: Mock, заменяющий список тикетов пользователя на пустой список.
         """
 
         self.admin_client.post(
@@ -590,17 +625,21 @@ class GetTicketsTestCase(UsersBaseTestCase):
     """
     Класс тестов для проверки функции получения тикетов.
 
-    В тестах используются @patch, замещающие работу с API Zendesk.
+    В тестах используются  @patch('main.views.zenpy.get_user') и  @patch('main.views.zenpy.get_user')
+    для  работы с API Zendesk.
     """
 
     @patch('main.views.zenpy.get_user')
     @patch('main.extra_func.zenpy')
-    def test_redirect(self, _zenpy_mock: zenpy, get_user_mock: get_user_model()) -> None:
+    def test_redirect(self, _zenpy_mock: Mock, get_user_mock: Mock) -> None:
         """
         Функция проверки переадресации пользователя на рабочую страницу.
 
         Проверяет редирект на рабочую страницу, в случае, когда пользователь с правами инженера заполняет форму
         принятия тикетов в работу.
+
+        :param _zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param get_user_mock: Mock объекта zenpy_user.
         """
         get_user_mock.return_value = Mock()
         user = get_user_model().objects.get(email=self.engineer)
@@ -610,12 +649,15 @@ class GetTicketsTestCase(UsersBaseTestCase):
 
     @patch('main.views.zenpy')
     @patch('main.views.get_tickets_list_for_group')
-    def test_take_one_ticket(self, group_tickets_mock: list, zenpy_mock: zenpy) -> None:
+    def test_take_one_ticket(self, group_tickets_mock: Mock, zenpy_mock: Mock) -> None:
         """
         Функция проверки назначения одного тикета на engineer.
 
         Проверяет соответствие ответственного за тикет объекта tickets и тестового клиента правами инженера,
         направившего запрос на назначение одного тикета.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param group_tickets_mock: Mock списка не назначенных и нерешенных тикетов группы.
         """
         group_tickets_mock.return_value = [Mock()]
         zenpy_mock.get_user.return_value = Mock(role='agent', custom_role_id=sets.ZENDESK_ROLES['engineer'])
@@ -625,12 +667,15 @@ class GetTicketsTestCase(UsersBaseTestCase):
 
     @patch('main.views.get_tickets_list_for_group')
     @patch('main.views.zenpy')
-    def test_take_many_tickets(self, zenpy_mock: zenpy, group_tickets_mock: list) -> None:
+    def test_take_many_tickets(self, zenpy_mock: Mock, group_tickets_mock: Mock) -> None:
         """
         Функция проверки назначения нескольких тикетов на engineer.
 
         Проверяет соответствие ответственного за тикеты объекта tickets и тестового клиента правами инженера,
         направившего запрос на назначение трех тикетов.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param group_tickets_mock: Mock списка не назначенных и нерешенных тикетов группы.
         """
         group_tickets_mock.return_value = [Mock()] * 3
         zenpy_mock.get_user.return_value = Mock(role='agent', custom_role_id=sets.ZENDESK_ROLES['engineer'])
@@ -641,9 +686,12 @@ class GetTicketsTestCase(UsersBaseTestCase):
 
     @patch('main.views.zenpy.get_user')
     @patch('main.views.zenpy')
-    def test_light_agent_take_ticket(self, zenpy_mock: zenpy, get_user_mock: get_user_model()):
+    def test_light_agent_take_ticket(self, zenpy_mock: Mock, get_user_mock: Mock) -> None:
         """
         Функция проверки попытки назначения тикета на light_agent.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param get_user_mock: Mock объекта zenpy_user.
         """
         get_user_mock.return_value = Mock(role='agent', custom_role_id=sets.ZENDESK_ROLES['light_agent'])
         self.agent_client.post(reverse('work_get_tickets'), data={'count_tickets': 3})
@@ -652,11 +700,14 @@ class GetTicketsTestCase(UsersBaseTestCase):
 
     @patch('main.views.zenpy')
     @patch('main.views.get_tickets_list_for_group')
-    def test_take_zero_tickets(self, tickets_mock: list, zenpy_mock: zenpy) -> None:
+    def test_take_zero_tickets(self, tickets_mock: Mock, zenpy_mock: Mock) -> None:
         """
         Функция проверки попытки назначения нулевого количества тикетов.
 
         Проверяет, что список тикетов остался пустым.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param tickets_mock: Mock списка тикетов - возвращает пустой список.
         """
         tickets_mock.return_value = [Mock()] * 3
         zenpy_mock.get_user.return_value = Mock(role='agent', custom_role_id=sets.ZENDESK_ROLES['engineer'])
@@ -666,12 +717,15 @@ class GetTicketsTestCase(UsersBaseTestCase):
 
     @patch('main.views.get_tickets_list_for_group')
     @patch('main.views.zenpy')
-    def test_take_invalid_count_tickets(self, zenpy_mock: zenpy, group_tickets_mock: list) -> None:
+    def test_take_invalid_count_tickets(self, zenpy_mock: Mock, group_tickets_mock: Mock) -> None:
         """
         Функция проверки попытки назначения некорректного количества тикетов (введении в форму назначения тикетов
         не числового значения, а строки).
 
         Проверяет, отсутствие списка тикетов.
+
+        :param zenpy_mock: Mock объекта zenpy для функций, работающих с API Zendesk.
+        :param group_tickets_mock: Mock списка не назначенных и нерешенных тикетов группы.
         """
         group_tickets_mock.return_value = [Mock()] * 3
         zenpy_mock.get_user.return_value = Mock(role='agent', custom_role_id=sets.ZENDESK_ROLES['engineer'])