Add tests docs, draft 2

main/tests.py

@@ -590,14 +590,17 @@ class GetTicketsTestCase(UsersBaseTestCase):
     """
     Класс тестов для проверки функции получения тикетов.
 
-
+    В тестах используются @patch, замещающие работу с API Zendesk.
     """
 
     @patch('main.views.zenpy.get_user')
     @patch('main.extra_func.zenpy')
-    def test_redirect(self, _zenpy_mock, get_user_mock):
+    def test_redirect(self, _zenpy_mock: zenpy, get_user_mock: get_user_model()) -> None:
         """
         Функция проверки переадресации пользователя на рабочую страницу.
+
+        Проверяет редирект на рабочую страницу, в случае, когда пользователь с правами инженера заполняет форму
+        принятия тикетов в работу.
         """
         get_user_mock.return_value = Mock()
         user = get_user_model().objects.get(email=self.engineer)
@@ -607,9 +610,12 @@ class GetTicketsTestCase(UsersBaseTestCase):
 
     @patch('main.views.zenpy')
     @patch('main.views.get_tickets_list_for_group')
-    def test_take_one_ticket(self, group_tickets_mock, zenpy_mock):
+    def test_take_one_ticket(self, group_tickets_mock: list, zenpy_mock: zenpy) -> None:
         """
         Функция проверки назначения одного тикета на engineer.
+
+        Проверяет соответствие ответственного за тикет объекта tickets и тестового клиента правами инженера,
+        направившего запрос на назначение одного тикета.
         """
         group_tickets_mock.return_value = [Mock()]
         zenpy_mock.get_user.return_value = Mock(role='agent', custom_role_id=sets.ZENDESK_ROLES['engineer'])
@@ -619,9 +625,12 @@ class GetTicketsTestCase(UsersBaseTestCase):
 
     @patch('main.views.get_tickets_list_for_group')
     @patch('main.views.zenpy')
-    def test_take_many_tickets(self, zenpy_mock, group_tickets_mock):
+    def test_take_many_tickets(self, zenpy_mock: zenpy, group_tickets_mock: list) -> None:
         """
         Функция проверки назначения нескольких тикетов на engineer.
+
+        Проверяет соответствие ответственного за тикеты объекта tickets и тестового клиента правами инженера,
+        направившего запрос на назначение трех тикетов.
         """
         group_tickets_mock.return_value = [Mock()] * 3
         zenpy_mock.get_user.return_value = Mock(role='agent', custom_role_id=sets.ZENDESK_ROLES['engineer'])
@@ -632,7 +641,7 @@ class GetTicketsTestCase(UsersBaseTestCase):
 
     @patch('main.views.zenpy.get_user')
     @patch('main.views.zenpy')
-    def test_light_agent_take_ticket(self, zenpy_mock, get_user_mock):
+    def test_light_agent_take_ticket(self, zenpy_mock: zenpy, get_user_mock: get_user_model()):
         """
         Функция проверки попытки назначения тикета на light_agent.
         """
@@ -643,9 +652,11 @@ class GetTicketsTestCase(UsersBaseTestCase):
 
     @patch('main.views.zenpy')
     @patch('main.views.get_tickets_list_for_group')
-    def test_take_zero_tickets(self, tickets_mock, zenpy_mock):
+    def test_take_zero_tickets(self, tickets_mock: list, zenpy_mock: zenpy) -> None:
         """
-        Функция проверки попытки назначения нуля тикета на engineer.
+        Функция проверки попытки назначения нулевого количества тикетов.
+
+        Проверяет, что список тикетов остался пустым.
         """
         tickets_mock.return_value = [Mock()] * 3
         zenpy_mock.get_user.return_value = Mock(role='agent', custom_role_id=sets.ZENDESK_ROLES['engineer'])
@@ -655,9 +666,12 @@ class GetTicketsTestCase(UsersBaseTestCase):
 
     @patch('main.views.get_tickets_list_for_group')
     @patch('main.views.zenpy')
-    def test_take_invalid_count_tickets(self, zenpy_mock, group_tickets_mock):
+    def test_take_invalid_count_tickets(self, zenpy_mock: zenpy, group_tickets_mock: list) -> None:
         """
-        Функция проверки попытки назначения нуля тикетов на engineer.
+        Функция проверки попытки назначения некорректного количества тикетов (введении в форму назначения тикетов
+        не числового значения, а строки).
+
+        Проверяет, отсутствие списка тикетов.
         """
         group_tickets_mock.return_value = [Mock()] * 3
         zenpy_mock.get_user.return_value = Mock(role='agent', custom_role_id=sets.ZENDESK_ROLES['engineer'])
@@ -670,13 +684,24 @@ class ProfileTestCase(TestCase):
     """
     Класс тестов для проверки синхронизации профиля пользователя.
 
-
+    Для тестов используются фикстуры тестовых пользователей (profile.json).
     """
     fixtures = ['fixtures/profile.json']
 
-    def setUp(self):
+    def setUp(self) -> None:
         """
-        Предустановленные значения для проведения тестов.
+        Функция предустановки значений переменных.
+
+        Добавляем email тестовых пользователей Zendesk и создаем клиентов для тестов.
+
+        :param zendesk_agent_email: email тестового пользователя с правами light_agent
+        :type zendesk_agent_email: :class:`str`
+        :param zendesk_admin_email: email тестового пользователя с правами admin
+        :type zendesk_admin_email: :class:`str`
+        :param client: клиент, залогиненный как пользователь с email zendesk_agent_email
+        :type client: :class:`django.test.client.Client`
+        :param admin_client: клиент, залогиненный как пользователь с zendesk_admin_email
+        :type admin_client: :class:`django.test.client.Client`
         """
         self.zendesk_agent_email = 'krav-88@mail.ru'
         self.zendesk_admin_email = 'idar.sokurov.05@mail.ru'
@@ -685,32 +710,42 @@ class ProfileTestCase(TestCase):
         self.admin_client = Client()
         self.admin_client.force_login(get_user_model().objects.get(email=self.zendesk_admin_email))
 
-    def test_correct_username(self):
+    def test_correct_username(self) -> None:
         """
         Функция проверки синхронизации имени пользователя.
+
+        Проверяет соответствие имени пользователя из контекста страницы профиля имени пользователя в Zendesk.
         """
         resp = self.client.get(reverse('profile'))
         self.assertEqual(resp.context['profile'].name, zenpy.get_user(self.zendesk_agent_email).name)
 
-    def test_correct_email(self):
+    def test_correct_email(self) -> None:
         """
         Функция проверки синхронизации почты пользователя.
+
+        Проверяет соответствие email пользователя из контекста страницы профиля email пользователя в Zendesk.
         """
         resp = self.client.get(reverse('profile'))
         self.assertEqual(resp.context['profile'].user.email, zenpy.get_user(self.zendesk_agent_email).email)
 
-    def test_correct_role(self):
+    def test_correct_role(self) -> None:
         """
         Функция проверки синхронизации роли пользователя.
+
+        Проверяет соответствие роли пользователя из контекста страницы профиля роли пользователя в Zendesk. Проверка
+        осуществляется на примере администратора и агента.
         """
         resp = self.client.get(reverse('profile'))
         self.assertEqual(resp.context['profile'].role, zenpy.get_user(self.zendesk_agent_email).role)
         resp = self.admin_client.get(reverse('profile'))
         self.assertEqual(resp.context['profile'].role, zenpy.get_user(self.zendesk_admin_email).role)
 
-    def test_correct_custom_role_id(self):
+    def test_correct_custom_role_id(self) -> None:
         """
         Функция проверки синхронизации рабочей роли пользователя.
+
+        Проверяет соответствие id рабочей роли пользователя из контекста страницы профиля id
+        роли пользователя в Zendesk. Проверка осуществляется на примере администратора и агента.
         """
         resp = self.client.get(reverse('profile'))
         user = zenpy.get_user(self.zendesk_agent_email)
@@ -719,9 +754,11 @@ class ProfileTestCase(TestCase):
         user = zenpy.get_user(self.zendesk_admin_email)
         self.assertEqual(resp.context['profile'].custom_role_id, user.custom_role_id if user.custom_role_id else 0)
 
-    def test_correct_image(self):
+    def test_correct_image(self) -> None:
         """
         Функция проверки синхронизации изображения пользователя.
+
+        Проверяет соответствие аватарки пользователя из контекста страницы профиля аватарке пользователя в Zendesk.
         """
         resp = self.client.get(reverse('profile'))
         user = zenpy.get_user(self.zendesk_agent_email)
@@ -729,38 +766,78 @@ class ProfileTestCase(TestCase):
 
 
 class LoggingTestCase(UsersBaseTestCase):
+    """
+    Класс тестирования процесса логгирования.
+    """
 
-    def setUp(self):
+    def setUp(self) -> None:
+        """
+        Функция предустановки значений переменных.
+
+        Определяем профили пользователей с разными ролями.
+
+        :param admin_profile: профиль тестового пользователя с правами admin
+        :type admin_profile: :class:`Userprofile`
+        :param agent_profile: профиль тестового пользователя с правами light_agent
+        :type agent_profile: :class:`Userprofile`
+        :param engineer_profile: профиль тестового пользователя с правами engineer
+        :type engineer_profile: :class:`Userprofile`
+        """
         super().setUp()
         self.admin_profile = get_user_model().objects.get(email=self.admin).userprofile
         self.agent_profile = get_user_model().objects.get(email=self.light_agent).userprofile
         self.engineer_profile = get_user_model().objects.get(email=self.engineer).userprofile
 
     @staticmethod
-    def get_file_output():
+    def get_file_output() -> str:
+        """
+        Получение данных из файла логов.
+        """
         with open('logs/logs.csv', 'r') as file:
             file_output = file.readlines()[-1]
         return file_output
 
-    def test_engineer_with_admin(self):
+    def test_engineer_with_admin(self) -> None:
+        """
+        Функция проверки корректной записи лога по смене роли инженера в файл.
+
+        Сравнивает запись в файле и созданный лог с переданными значениями профилей инженера и администратора
+        для смены прав.
+        """
         log(self.engineer_profile, self.admin_profile)
         file_output = self.get_file_output()
         self.assertEqual(file_output, f'UserForAccessTest,engineer,'
                                       f'{str(timezone.now().today())[:16]},ZendeskAdmin\n')
 
-    def test_engineer_without_admin(self):
+    def test_engineer_without_admin(self) -> None:
+        """
+        Функция проверки корректной записи лога по смене роли инженера в файл без указания администратора.
+
+        Сравнивает запись в файле и созданный лог с переданным значением профиля инженера для смены прав.
+        """
         log(self.engineer_profile)
         file_output = self.get_file_output()
         self.assertEqual(file_output, f'UserForAccessTest,engineer,'
                                       f'{str(timezone.now().today())[:16]},UserForAccessTest\n')
 
-    def test_light_agent_with_admin(self):
+    def test_light_agent_with_admin(self) -> None:
+        """
+        Функция проверки корректной записи лога по смене роли агента в файл.
+
+        Сравнивает запись в файле и созданный лог с переданными значениями профилей агента и администратора
+        для смены прав.
+        """
         log(self.agent_profile, self.admin_profile)
         file_output = self.get_file_output()
         self.assertEqual(file_output, f'UserForAccessTest,light_agent,'
                                       f'{str(timezone.now().today())[:16]},ZendeskAdmin\n')
 
-    def test_light_agent_without_admin(self):
+    def test_light_agent_without_admin(self) -> None:
+        """
+        Функция проверки корректной записи лога по смене роли агента  в файл без указания администратора.
+
+        Сравнивает запись в файле и созданный лог с переданным значением профиля агента для смены прав.
+        """
         log(self.agent_profile)
         file_output = self.get_file_output()
         self.assertEqual(file_output, f'UserForAccessTest,light_agent,'