# `unittest` — Unit testing framework

Вихідний код: Lib/unittest/__init__.py

(Якщо ви вже знайомі з основними концепціями тестування, ви можете перейти до списку методів assert.)

Фреймворк модульного тестування `unittest` спочатку був натхненний JUnit і має подібний смак, як основні фреймворки модульного тестування іншими мовами. Він підтримує автоматизацію тестування, спільне використання коду налаштування та завершення тестів, об’єднання тестів у колекції та незалежність тестів від структури звітування.

Щоб досягти цього, `unittest` підтримує деякі важливі концепції в об’єктно-орієнтований спосіб:

тестове пристосування

  test fixture представляє підготовку, необхідну для виконання одного або кількох тестів і будь-яких пов’язаних дій очищення. Це може включати, наприклад, створення тимчасових або проксі-баз даних, каталогів або запуск серверного процесу.

тестовий випадок

  test case — це окрема одиниця тестування. Він перевіряє конкретну відповідь на певний набір вхідних даних. `unittest` надає базовий клас, `TestCase`, який можна використовувати для створення нових тестів.

набір тестів

  test suite — це набір тестів, наборів тестів або обох. Він використовується для агрегування тестів, які слід виконувати разом.

тестовий бігун

  test runner — це компонент, який керує виконанням тестів і надає результат користувачеві. Виконувач може використовувати графічний інтерфейс, текстовий інтерфейс або повертати спеціальне значення для вказівки результатів виконання тестів.

Дивись також

Модуль `doctest`

  Ще один модуль підтримки тестування з зовсім іншим смаком.

Просте тестування Smalltalk: із шаблонами

  Оригінальна стаття Кента Бека про тестування фреймворків за шаблоном, яким поділився `unittest`.

pytest

  Фреймворк модульного тестування третьої сторони зі спрощеним синтаксисом для написання тестів. Наприклад, `assert func(10) == 42`.

Таксономія інструментів тестування Python

  Широкий список інструментів тестування Python, включаючи фреймворки функціонального тестування та бібліотеки макетів об’єктів.

Тестування в списку розсилки Python

  Група спеціальних інтересів для обговорення тестування та інструментів тестування на Python.

The script `Tools/unittestgui/unittestgui.py` in the Python source distribution is a GUI tool for test discovery and execution. This is intended largely for ease of use for those new to unit testing. For production environments it is recommended that tests be driven by a continuous integration system such as Buildbot, Jenkins or Travis-CI, or AppVeyor.

## Базовий приклад

Модуль `unittest` надає багатий набір інструментів для побудови та виконання тестів. У цьому розділі показано, що невеликого набору інструментів достатньо для задоволення потреб більшості користувачів.

Ось короткий скрипт для перевірки трьох методів рядків:

    import unittest

    class TestStringMethods(unittest.TestCase):

        def test_upper(self):
            self.assertEqual('foo'.upper(), 'FOO')

        def test_isupper(self):
            self.assertTrue('FOO'.isupper())
            self.assertFalse('Foo'.isupper())

        def test_split(self):
            s = 'hello world'
            self.assertEqual(s.split(), ['hello', 'world'])
            # check that s.split fails when the separator is not a string
            with self.assertRaises(TypeError):
                s.split(2)

    if __name__ == '__main__':
        unittest.main()

Тестовий приклад створюється підкласом `unittest.TestCase`. Три окремі тести визначаються методами, назви яких починаються з літер `test`. Ця домовленість про найменування інформує виконавця тестів про те, які методи представляють тести.

Суть кожного тесту полягає у виклику `assertEqual()` для перевірки очікуваного результату; `assertTrue()` або `assertFalse()` для перевірки умови; або `assertRaises()`, щоб перевірити, чи виникає певний виняток. Ці методи використовуються замість оператора `assert`, щоб виконавець тесту міг накопичувати всі результати тестування та створювати звіт.

Методи `setUp()` і `tearDown()` дозволяють визначати інструкції, які виконуватимуться до і після кожного методу тестування. Більш детально вони описані в розділі Організація тестового коду.

Останній блок показує простий спосіб виконання тестів. `unittest.main()` надає інтерфейс командного рядка для тестового сценарію. Під час запуску з командного рядка наведений вище сценарій створює вихідні дані, які виглядають так:

    ...
    ----------------------------------------------------------------------
    Ran 3 tests in 0.000s

    OK

Передача параметра `-v` у ваш тестовий сценарій вказує `unittest.main()` увімкнути вищий рівень докладності та створить такий вихід:

    test_isupper (__main__.TestStringMethods) ... ok
    test_split (__main__.TestStringMethods) ... ok
    test_upper (__main__.TestStringMethods) ... ok

    ----------------------------------------------------------------------
    Ran 3 tests in 0.001s

    OK

Наведені вище приклади показують найпоширеніші функції `unittest`, яких достатньо для задоволення багатьох щоденних потреб тестування. У решті документації розглядається повний набір функцій із перших принципів.

## Інтерфейс командного рядка

Модуль unittest можна використовувати з командного рядка для запуску тестів із модулів, класів або навіть окремих методів тестування:

    python -m unittest test_module1 test_module2
    python -m unittest test_module.TestClass
    python -m unittest test_module.TestClass.test_method

Ви можете передати список із будь-якою комбінацією імен модулів і повних імен класів або методів.

Тестові модулі також можна вказати шляхом до файлу:

    python -m unittest tests/test_something.py

Це дозволяє використовувати завершення назви файлу оболонки для визначення тестового модуля. Зазначений файл усе ще має бути імпортованим як модуль. Шлях перетворюється на назву модуля шляхом видалення «.py» та перетворення роздільників шляху на «.». Якщо ви хочете виконати тестовий файл, який не можна імпортувати як модуль, вам слід виконати цей файл безпосередньо.

Ви можете запустити тести з більшою деталізацією (вищою детальністю), передавши прапор -v:

    python -m unittest -v test_module

При виконанні без аргументів Тестове відкриття запускається:

    python -m unittest

Список усіх параметрів командного рядка:

    python -m unittest -h

Змінено в версії 3.2: У попередніх версіях було можливо запускати лише окремі методи тестування, а не модулі чи класи.

### Параметри командного рядка

unittest підтримує такі параметри командного рядка:

`-b````,` `--buffer```

  Стандартний вихід і стандартні потоки помилок буферизуються під час виконання тесту. Вихідні дані під час проходження тесту відкидаються. Вихідні дані зазвичай відтворюються у разі невдачі тесту або помилки та додаються до повідомлень про помилки.

`-c````,` `--catch```

  ``Control`-`C`` під час тестового запуску чекає завершення поточного тесту, а потім повідомляє всі результати. Другий ``Control`-`C`` викликає звичайний виняток `KeyboardInterrupt`.

  Перегляньте Обробка сигналів (Signal Handling) для функцій, які забезпечують цю функціональність.

`-f````,` `--failfast```

  Зупиніть тестовий запуск при першій помилці або невдачі.

`-k```

  Запускайте лише тестові методи та класи, які відповідають шаблону або підрядку. Цю опцію можна використовувати кілька разів, і в цьому випадку будуть включені всі тестові випадки, які відповідають будь-якому із заданих шаблонів.

  Шаблони, які містять символ підстановки (`*`), зіставляються з назвою тесту за допомогою `fnmatch.fnmatchcase()`; інакше використовується просте зіставлення підрядка з урахуванням регістру.

  Шаблони зіставляються з повною назвою методу тестування, імпортованою завантажувачем тестів.

  Наприклад, `-k foo` відповідає `foo_tests.SomeTest.test_something`, `bar_tests.SomeTest.test_something`, але не `bar_tests.FooTest.test_something`.

`--locals```

  Показати локальні змінні в трасуваннях.

Нове в версії 3.2: Додано параметри командного рядка `-b`, `-c` і `-f`.

Нове в версії 3.5: Параметр командного рядка `--locals`.

Нове в версії 3.7: Параметр командного рядка `-k`.

Командний рядок також можна використовувати для виявлення тестів, для запуску всіх тестів у проекті або лише підмножини.

## Тестове відкриття

Нове в версії 3.2.

Unittest supports simple test discovery. In order to be compatible with test discovery, all of the test files must be modules or packages (including namespace packages) importable from the top-level directory of the project (this means that their filenames must be valid identifiers).

Виявлення тесту реалізовано в `TestLoader.discover()`, але його також можна використовувати з командного рядка. Основне використання командного рядка:

    cd project_directory
    python -m unittest discover

Примітка

Як скорочення, `python -m unittest` є еквівалентом `python -m unittest discover`. Якщо ви хочете передати аргументи для перевірки виявлення, підкоманду `discover` слід використовувати явно.

Підкоманда `discover` має такі параметри:

`-v````,` `--verbose```

  Детальний висновок

`-s````,` `--start-directory` `directory`

  Каталог для початку виявлення (`.` за замовчуванням)

`-p````,` `--pattern` `pattern`

  Шаблон для відповідності тестовим файлам (`test*.py` за замовчуванням)

`-t````,` `--top-level-directory` `directory`

  Каталог верхнього рівня проекту (за замовчуванням це початковий каталог)

Параметри `-s`, `-p` і `-t` можна передати як позиційні аргументи в такому порядку. Наступні два командні рядки еквівалентні:

    python -m unittest discover -s project_directory -p "*_test.py"
    python -m unittest discover project_directory "*_test.py"

Окрім шляху, можна передати назву пакета, наприклад `myproject.subpackage.test`, як початковий каталог. Указане вами ім’я пакета буде імпортовано, а його розташування у файловій системі використовуватиметься як початковий каталог.

Застереження

Відкриття тестів завантажує тести, імпортуючи їх. Після того як тестове виявлення знайде всі тестові файли з початкового каталогу, який ви вкажете, воно перетворює шляхи на імена пакетів для імпорту. Наприклад, `foo/bar/baz.py` буде імпортовано як `foo.bar.baz`.

Якщо у вас глобально встановлено пакет, і ви намагаєтеся виявити тест на іншій копії пакета, то імпорт може відбутися не з того місця. Якщо це станеться, тестове виявлення попередить вас і вийде.

Якщо ви вказуєте початковий каталог як назву пакета, а не як шлях до каталогу, тоді виявлення припускає, що будь-яке місце, з якого він імпортує, є тим розташуванням, яке ви хотіли, тому ви не отримаєте попередження.

Тестові модулі та пакети можуть налаштувати тестове завантаження та виявлення за допомогою load_tests protocol.

Змінено в версії 3.4: Тестове виявлення підтримує пакети простору імен для початкового каталогу. Зауважте, що вам також потрібно вказати каталог верхнього рівня (наприклад, `python -m unittest discover -s root/namespace -t root`).

## Організація тестового коду

Основними будівельними блоками модульного тестування є test cases — окремі сценарії, які необхідно налаштувати та перевірити на правильність. У `unittest` тестові випадки представлені екземплярами `unittest.TestCase`. Щоб створити власні тестові випадки, ви повинні написати підкласи `TestCase` або використати `FunctionTestCase`.

Тестовий код екземпляра `TestCase` має бути повністю самостійним, щоб його можна було запускати окремо або в довільній комбінації з будь-якою кількістю інших тестів.

Найпростіший підклас `TestCase` просто реалізує тестовий метод (тобто метод, назва якого починається з `test`), щоб виконати певний код тестування:

    import unittest

    class DefaultWidgetSizeTestCase(unittest.TestCase):
        def test_default_widget_size(self):
            widget = Widget('The widget')
            self.assertEqual(widget.size(), (50, 50))

Note that in order to test something, we use one of the `assert*()` methods provided by the `TestCase` base class. If the test fails, an exception will be raised with an explanatory message, and `unittest` will identify the test case as a failure. Any other exceptions will be treated as errors.

Тестів може бути багато, а їх налаштування можуть повторюватися. На щастя, ми можемо виключити код налаштування, реалізувавши метод під назвою `setUp()`, який система тестування автоматично викличе для кожного тесту, який ми виконуємо:

    import unittest

    class WidgetTestCase(unittest.TestCase):
        def setUp(self):
            self.widget = Widget('The widget')

        def test_default_widget_size(self):
            self.assertEqual(self.widget.size(), (50,50),
                             'incorrect default size')

        def test_widget_resize(self):
            self.widget.resize(100,150)
            self.assertEqual(self.widget.size(), (100,150),
                             'wrong size after resize')

Примітка

Порядок, у якому виконуватимуться різні тести, визначається сортуванням назв методів тестування відповідно до вбудованого порядку для рядків.

Якщо метод `setUp()` викликає виняток під час виконання тесту, фреймворк вважатиме, що тест зазнав помилки, і метод тесту не буде виконано.

Подібним чином ми можемо надати метод `tearDown()`, який наводить порядок після виконання тестового методу:

    import unittest

    class WidgetTestCase(unittest.TestCase):
        def setUp(self):
            self.widget = Widget('The widget')

        def tearDown(self):
            self.widget.dispose()

Якщо `setUp()` виконано успішно, `tearDown()` буде запущено незалежно від того, чи вдався метод тестування.

Таке робоче середовище для коду тестування називається test fixture. Новий екземпляр TestCase створюється як унікальний тестовий прилад, який використовується для виконання кожного окремого методу тестування. Таким чином, `setUp()`, `tearDown()` і `__init__()` буде викликано один раз на тест.

Рекомендується використовувати реалізації TestCase для групування тестів відповідно до функцій, які вони тестують. `unittest` забезпечує механізм для цього: test suite, представлений `unittest` класом `TestSuite`. У більшості випадків виклик `unittest.main()` зробить правильну річ і збере для вас усі тестові приклади модуля та виконає їх.

Однак, якщо ви хочете налаштувати збірку свого набору тестів, ви можете зробити це самостійно:

    def suite():
        suite = unittest.TestSuite()
        suite.addTest(WidgetTestCase('test_default_widget_size'))
        suite.addTest(WidgetTestCase('test_widget_resize'))
        return suite

    if __name__ == '__main__':
        runner = unittest.TextTestRunner()
        runner.run(suite())

Ви можете розмістити визначення тестів і наборів тестів у тих самих модулях, що й код, який вони мають тестувати (наприклад, `widget.py`), але є кілька переваг розміщення тестового коду в окремому модулі, наприклад `test_widget.py`:

- Тестовий модуль можна запускати автономно з командного рядка.

- Тестовий код можна легше відокремити від надісланого коду.

- Менше спокуси змінити тестовий код, щоб відповідати коду, який він тестує, без вагомої причини.

- Тестовий код слід змінювати набагато рідше, ніж код, який він тестує.

- Перевірений код можна легше рефакторингувати.

- Тести для модулів, написаних мовою C, у будь-якому разі повинні бути окремими модулями, то чому б не бути послідовними?

- Якщо стратегія тестування змінюється, немає необхідності змінювати вихідний код.

## Повторне використання старого тестового коду

Деякі користувачі виявлять, що у них є тестовий код, який вони хотіли б запустити з `unittest`, не перетворюючи кожну стару тестову функцію на підклас `TestCase`.

З цієї причини `unittest` надає клас `FunctionTestCase`. Цей підклас `TestCase` можна використовувати для обгортання існуючої тестової функції. Також можуть бути передбачені функції налаштування та демонтажу.

Дано таку тестову функцію:

    def testSomething():
        something = makeSomething()
        assert something.name is not None
        # ...

можна створити еквівалентний екземпляр тестового сценарію наступним чином із додатковими методами налаштування та демонтажу:

    testcase = unittest.FunctionTestCase(testSomething,
                                         setUp=makeSomethingDB,
                                         tearDown=deleteSomethingDB)

Примітка

Незважаючи на те, що `FunctionTestCase` можна використовувати для швидкого перетворення наявної тестової бази на систему на основі `unittest`, цей підхід не рекомендується. Витративши час на налаштування належних підкласів `TestCase`, ви значно спростите рефакторинг майбутніх тестів.

У деяких випадках існуючі тести могли бути написані за допомогою модуля `doctest`. Якщо так, `doctest` надає клас `DocTestSuite`, який може автоматично створювати екземпляри `unittest.TestSuite` з існуючих тестів на основі `doctest`.

## Пропуск тестів і очікувані невдачі

Нове в версії 3.1.

Unittest підтримує пропуски окремих методів тестування і навіть цілих класів тестів. Крім того, він підтримує позначення тесту як «очікуваної помилки», тобто тесту, який зламано і буде невдалим, але його не слід вважати помилкою в `TestResult`.

Пропуск тесту – це просто використання `skip()` decorator або одного з його умовних варіантів, виклик `TestCase.skipTest()` у `setUp()` або тестовий метод або безпосередньо підняти `SkipTest`.

Базовий пропуск виглядає так:

    class MyTestCase(unittest.TestCase):

        @unittest.skip("demonstrating skipping")
        def test_nothing(self):
            self.fail("shouldn't happen")

        @unittest.skipIf(mylib.__version__ < (1, 3),
                         "not supported in this library version")
        def test_format(self):
            # Tests that work for only a certain version of the library.
            pass

        @unittest.skipUnless(sys.platform.startswith("win"), "requires Windows")
        def test_windows_support(self):
            # windows specific testing code
            pass

        def test_maybe_skipped(self):
            if not external_resource_available():
                self.skipTest("external resource not available")
            # test code that depends on the external resource
            pass

Це результат виконання наведеного вище прикладу в докладному режимі:

    test_format (__main__.MyTestCase) ... skipped 'not supported in this library version'
    test_nothing (__main__.MyTestCase) ... skipped 'demonstrating skipping'
    test_maybe_skipped (__main__.MyTestCase) ... skipped 'external resource not available'
    test_windows_support (__main__.MyTestCase) ... skipped 'requires Windows'

    ----------------------------------------------------------------------
    Ran 4 tests in 0.005s

    OK (skipped=4)

Класи можна пропускати, як і методи:

    @unittest.skip("showing class skipping")
    class MySkippedTestCase(unittest.TestCase):
        def test_not_run(self):
            pass

`TestCase.setUp()` також може пропустити тест. Це корисно, коли ресурс, який потрібно налаштувати, недоступний.

Очікувані помилки використовують декоратор `expectedFailure()`.

    class ExpectedFailureTestCase(unittest.TestCase):
        @unittest.expectedFailure
        def test_fail(self):
            self.assertEqual(1, 0, "broken")

Легко запустити власні декоратори пропуску, створивши декоратор, який викликає `skip()` у тесті, коли хоче, щоб його було пропущено. Цей декоратор пропускає перевірку, якщо переданий об’єкт не має певного атрибута:

    def skipUnlessHasattr(obj, attr):
        if hasattr(obj, attr):
            return lambda func: func
        return unittest.skip("{!r} doesn't have {!r}".format(obj, attr))

Наступні декоратори та винятки реалізують пропуск тесту та очікувані помилки:

`@``unittest.``skip`(reason)

  Беззастережно пропустіть оформлений тест. причина має описувати, чому тест пропускається.

`@``unittest.``skipIf`(condition, reason)

  Пропустіть декорований тест, якщо умова істинна.

`@``unittest.``skipUnless`(condition, reason)

  Пропустіть оформлений тест, якщо умова не виконується.

`@``unittest.``expectedFailure`

  Позначте тест як очікувану невдачу або помилку. Якщо тест зазнає невдачі або помилки в самій тестовій функції (а не в одному з методів test fixture), тоді він вважатиметься успішним. Якщо тест буде пройдений, він буде вважатися невдалим.

exception `unittest.``SkipTest`(reason)

  Цей виняток створюється, щоб пропустити тест.

  Зазвичай ви можете використовувати `TestCase.skipTest()` або один із декораторів пропуску замість того, щоб піднімати це безпосередньо.

Пропущені тести не запускатимуть `setUp()` або `tearDown()`. Пропущені класи не виконуватимуться `setUpClass()` або `tearDownClass()`. Пропущені модулі не запускатимуть `setUpModule()` або `tearDownModule()`.

## Розрізнення тестових ітерацій за допомогою субтестів

Нове в версії 3.4.

Якщо між вашими тестами є дуже невеликі відмінності, наприклад деякі параметри, unittest дозволяє розрізняти їх у тілі тестового методу за допомогою контекстного менеджера `subTest()`.

Наприклад, такий тест:

    class NumbersTest(unittest.TestCase):

        def test_even(self):
            """
            Test that numbers between 0 and 5 are all even.
            """
            for i in range(0, 6):
                with self.subTest(i=i):
                    self.assertEqual(i % 2, 0)

виведе наступний вихід:

    ======================================================================
    FAIL: test_even (__main__.NumbersTest) (i=1)
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "subtests.py", line 32, in test_even
        self.assertEqual(i % 2, 0)
    AssertionError: 1 != 0

    ======================================================================
    FAIL: test_even (__main__.NumbersTest) (i=3)
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "subtests.py", line 32, in test_even
        self.assertEqual(i % 2, 0)
    AssertionError: 1 != 0

    ======================================================================
    FAIL: test_even (__main__.NumbersTest) (i=5)
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "subtests.py", line 32, in test_even
        self.assertEqual(i % 2, 0)
    AssertionError: 1 != 0

Без використання підтесту виконання зупинилося б після першої помилки, а помилку було б важче діагностувати, оскільки значення `i` не відображалося б:

    ======================================================================
    FAIL: test_even (__main__.NumbersTest)
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "subtests.py", line 32, in test_even
        self.assertEqual(i % 2, 0)
    AssertionError: 1 != 0

## Класи та функції

У цьому розділі докладно описано API `unittest`.

### Тестові випадки

class `unittest.``TestCase`(methodName='runTest')

  Екземпляри класу `TestCase` представляють логічні тестові одиниці у всесвіті `unittest`. Цей клас призначений для використання в якості базового класу з конкретними тестами, реалізованими конкретними підкласами. Цей клас реалізує інтерфейс, необхідний виконавцю тестів, щоб дозволити йому керувати тестами, і методи, які тестовий код може використовувати для перевірки та звітування про різні види помилок.

  Кожен екземпляр `TestCase` запускатиме один базовий метод: метод під назвою methodName. У більшості випадків використання `TestCase` ви не змінюєте methodName і не реалізуєте метод за замовчуванням `runTest()`.

  Змінено в версії 3.2: `TestCase` можна успішно створити без надання methodName. Це полегшує експерименти з `TestCase` з інтерактивного інтерпретатора.

  Екземпляри `TestCase` забезпечують три групи методів: одна група використовується для запуску тесту, інша використовується реалізацією тесту для перевірки умов і звітування про помилки, а також деякі методи запиту, які дозволяють збирати інформацію про сам тест.

  Методи першої групи (проведення тесту) це:

  `setUp`()

    Метод, який називається для підготовки випробувального матеріалу. Це викликається безпосередньо перед викликом тестового методу; крім `AssertionError` або `SkipTest`, будь-який виняток, викликаний цим методом, вважатиметься помилкою, а не помилкою тесту. Стандартна реалізація нічого не робить.

  `tearDown`()

    Метод викликається відразу після виклику тестового методу та запису результату. Це викликається, навіть якщо метод тестування викликав виняток, тому реалізація в підкласах може потребувати особливої обережності щодо перевірки внутрішнього стану. Будь-які винятки, окрім `AssertionError` або `SkipTest`, викликані цим методом, вважатимуться додатковою помилкою, а не помилкою тесту (таким чином збільшуючи загальну кількість повідомлених помилок). Цей метод буде викликано, лише якщо `setUp()` завершиться успішно, незалежно від результату тестового методу. Стандартна реалізація нічого не робить.

  `setUpClass`()

    Метод класу, який викликається перед виконанням тестів в окремому класі. `setUpClass` викликається з класом як єдиним аргументом і має бути оформлений як `classmethod()`:

        @classmethod
        def setUpClass(cls):
            ...

    Додаткову інформацію див. у розділі Class and Module Fixtures.

    Нове в версії 3.2.

  `tearDownClass`()

    Метод класу, який викликається після виконання тестів в окремому класі. `tearDownClass` викликається з класом як єдиним аргументом і має бути оформлений як `classmethod()`:

        @classmethod
        def tearDownClass(cls):
            ...

    Додаткову інформацію див. у розділі Class and Module Fixtures.

    Нове в версії 3.2.

  `run`(result=None)

    Запустіть тест, зібравши результат в об’єкт `TestResult`, переданий як result. Якщо результат пропущено або `None`, створюється та використовується тимчасовий об’єкт результату (викликом методу `defaultTestResult()`). Об’єкт результату повертається до виклику `run()`.

    Такого ж ефекту можна отримати, просто викликавши екземпляр `TestCase`.

    Змінено в версії 3.3: Попередні версії `run` не повертали результат. Також не викликав інстанції.

  `skipTest`(reason)

    Виклик цього під час тестового методу або `setUp()` пропускає поточний тест. Перегляньте Пропуск тестів і очікувані невдачі для отримання додаткової інформації.

    Нове в версії 3.1.

  `subTest`(msg=None, **params)

    Повертає контекстний менеджер, який виконує вкладений блок коду як підтест. msg і params є необов’язковими, довільними значеннями, які відображаються щоразу, коли субтест проходить невдало, що дозволяє їх чітко ідентифікувати.

    Тестовий приклад може містити будь-яку кількість оголошень субтесту, і вони можуть бути довільно вкладеними.

    Перегляньте Розрізнення тестових ітерацій за допомогою субтестів для отримання додаткової інформації.

    Нове в версії 3.4.

  `debug`()

    Виконайте тест без отримання результату. Це дозволяє поширювати винятки, викликані тестом, до викликаючого, і може бути використано для підтримки запуску тестів під налагоджувачем.

  Клас `TestCase` надає кілька методів підтвердження для перевірки помилок і звітування про них. У наведеній нижче таблиці перераховано найпоширеніші методи (перегляньте таблиці нижче, щоб отримати більше методів підтвердження):

  метод | Перевіряє це | Нове в
  --- | --- | ---
  `assertEqual(a, b)` | `a == b` |
  `assertNotEqual(a, b)` | `a != b` |
  `assertTrue(x)` | `bool(x) має значення True` |
  `assertFalse(x)` | `bool(x) є False` |
  `assertIs(a, b)` | `a є b` | 3.1
  `assertIsNot(a, b)` | `a не є b` | 3.1
  `assertIsNone(x)` | `x не має значення` | 3.1
  `assertIsNotNone(x)` | `x не є None` | 3.1
  `assertIn(a, b)` | `a в b` | 3.1
  `assertNotIn(a, b)` | `a не в b` | 3.1
  `assertIsInstance(a, b)` | `isinstance(a, b)` | 3.2
  `assertNotIsInstance(a, b)` | `не екземпляр(a, b)` | 3.2

  Усі методи assert приймають аргумент msg, який, якщо вказано, використовується як повідомлення про помилку у разі помилки (див. також `longMessage`). Зауважте, що аргумент ключового слова msg можна передати до `assertRaises()`, `assertRaisesRegex()`, `assertWarns()`, `assertWarnsRegex()` лише тоді, коли вони використовуються як менеджер контексту.

  `assertEqual`(first, second, msg=None)

    Перевірте, що перше і друге рівні. Якщо порівняльні значення не однакові, тест буде невдалим.

    Крім того, якщо first і second мають той самий тип і один із list, tuple, dict, set, frozenset або str або будь-який тип, який підклас реєструє за допомогою `addTypeEqualityFunc()`, специфічна для типу функція рівності буде викликано, щоб створити більш корисне повідомлення про помилку за замовчуванням (див. також список специфічних для типу методів).

    Змінено в версії 3.1: Додано автоматичний виклик функції рівності для певного типу.

    Змінено в версії 3.2: `assertMultiLineEqual()` додано як функцію рівності типів за умовчанням для порівняння рядків.

  `assertNotEqual`(first, second, msg=None)

    Перевірте, що перше і друге не рівні. Якщо порівняльні значення однакові, тест буде невдалим.

  `assertTrue`(expr, msg=None)
  `assertFalse`(expr, msg=None)

    Перевірте, що expr є істинним (або хибним).

    Зауважте, що це еквівалентно `bool(expr) is True`, а не `expr is True` (використовуйте `assertIs(expr, True)` для останнього). Також слід уникати цього методу, якщо доступні більш специфічні методи (наприклад, `assertEqual(a, b)` замість `assertTrue(a == b)`), тому що вони надають краще повідомлення про помилку в разі невдачі .

  `assertIs`(first, second, msg=None)
  `assertIsNot`(first, second, msg=None)

    Перевірте, чи перший і другий є (чи не є) одним і тим же об’єктом.

    Нове в версії 3.1.

  `assertIsNone`(expr, msg=None)
  `assertIsNotNone`(expr, msg=None)

    Перевірте, що expr є (чи не є) `None`.

    Нове в версії 3.1.

  `assertIn`(member, container, msg=None)
  `assertNotIn`(member, container, msg=None)

    Перевірте, чи член є (чи ні) у контейнері.

    Нове в версії 3.1.

  `assertIsInstance`(obj, cls, msg=None)
  `assertNotIsInstance`(obj, cls, msg=None)

    Перевірте, що obj є (або не є) екземпляром cls (який може бути класом або кортежем класів, як підтримується `isinstance()`). Щоб перевірити точний тип, використовуйте `assertIs(type(obj), cls)`.

    Нове в версії 3.2.

  Також можна перевірити створення винятків, попереджень і повідомлень журналу за допомогою таких методів:

  метод | Перевіряє це | Нове в
  --- | --- | ---
  `assertRaises(exc, fun, *args, **kwds)` | `fun(*args, **kwds)` підвищує exc |
  `assertRaisesRegex(exc, r, fun, *args, **kwds)` | `fun(*args, **kwds)` викликає exc і повідомлення відповідає регулярному виразу r | 3.1
  `assertWarns(warn, fun, *args, **kwds)` | `fun(*args, **kwds)` викликає попередження | 3.2
  `assertWarnsRegex(warn, r, fun, *args, **kwds)` | `fun(*args, **kwds)` викликає warn і повідомлення відповідає регулярному виразу r | 3.2
  `assertLogs(реєстратор, рівень)` | Блок `with` реєструє реєстратор з мінімальним рівнем | 3.4
  `assertNoLogs(реєстратор, рівень)` | Блок `with` не входить в систему логгер з мінімальним рівнем | 3.10

  `assertRaises`(exception, callable, *args, **kwds)
  `assertRaises`(exception, *, msg=None)

    Перевірте, чи виникає виняток, коли callable викликається з будь-якими позиційними або ключовими аргументами, які також передаються в `assertRaises()`. Перевірка проходить, якщо виникає виняток, вважається помилкою, якщо викликається інший виняток, або не виконується, якщо винятку не виникає. Щоб перехопити будь-яку групу винятків, кортеж, що містить класи винятків, можна передати як виняток.

    Якщо подано лише аргументи exception і, можливо, msg, поверніть диспетчер контексту, щоб тестований код можна було записати вбудовано, а не як функцію:

        with self.assertRaises(SomeException):
            do_something()

    У разі використання як менеджера контексту `assertRaises()` приймає додатковий аргумент ключового слова msg.

    Менеджер контексту збереже спійманий об’єкт винятку в своєму атрибуті `exception`. Це може бути корисним, якщо планується виконати додаткові перевірки викликаного винятку:

        with self.assertRaises(SomeException) as cm:
            do_something()

        the_exception = cm.exception
        self.assertEqual(the_exception.error_code, 3)

    Змінено в версії 3.1: Додано можливість використовувати `assertRaises()` як контекстний менеджер.

    Змінено в версії 3.2: Додано атрибут `exception`.

    Змінено в версії 3.3: Додано аргумент ключового слова msg, коли він використовується як менеджер контексту.

  `assertRaisesRegex`(exception, regex, callable, *args, **kwds)
  `assertRaisesRegex`(exception, regex, *, msg=None)

    Подібно до `assertRaises()`, але також перевіряє, що regex відповідає рядковому представленню викликаного винятку. regex може бути об’єктом регулярного виразу або рядком, що містить регулярний вираз, придатний для використання `re.search()`. Приклади:

        self.assertRaisesRegex(ValueError, "invalid literal for.*XYZ'$",
                               int, 'XYZ')

    або:

        with self.assertRaisesRegex(ValueError, 'literal'):
           int('XYZ')

    Нове в версії 3.1: Додано під назвою `assertRaisesRegexp`.

    Змінено в версії 3.2: Перейменовано на `assertRaisesRegex()`.

    Змінено в версії 3.3: Додано аргумент ключового слова msg, коли він використовується як менеджер контексту.

  `assertWarns`(warning, callable, *args, **kwds)
  `assertWarns`(warning, *, msg=None)

    Перевірте, чи спрацьовує попередження, коли callable викликається з будь-якими позиційними або ключовими аргументами, які також передаються до `assertWarns()`. Тест проходить, якщо спрацьовує попередження, і не виконується, якщо ні. Будь-який виняток є помилкою. Щоб перехопити будь-яку групу попереджень, кортеж, що містить класи попереджень, можна передати як попередження.

    Якщо надано лише аргументи попередження і, можливо, повідомлення, поверніть диспетчер контексту, щоб тестований код можна було записати вбудовано, а не як функцію:

        with self.assertWarns(SomeWarning):
            do_something()

    У разі використання як менеджера контексту `assertWarns()` приймає додатковий аргумент ключового слова msg.

    Менеджер контексту збереже спійманий об’єкт попередження в атрибуті `warning`, а вихідний рядок, який викликав попередження, в атрибутах `filename` і `lineno`. Це може бути корисним, якщо планується виконати додаткові перевірки виявленого попередження:

        with self.assertWarns(SomeWarning) as cm:
            do_something()

        self.assertIn('myfile.py', cm.filename)
        self.assertEqual(320, cm.lineno)

    Цей метод працює незалежно від фільтрів попереджень під час його виклику.

    Нове в версії 3.2.

    Змінено в версії 3.3: Додано аргумент ключового слова msg, коли він використовується як менеджер контексту.

  `assertWarnsRegex`(warning, regex, callable, *args, **kwds)
  `assertWarnsRegex`(warning, regex, *, msg=None)

    Подібно до `assertWarns()`, але також перевіряє відповідність regex у повідомленні викликаного попередження. regex може бути об’єктом регулярного виразу або рядком, що містить регулярний вираз, придатний для використання `re.search()`. Приклад:

        self.assertWarnsRegex(DeprecationWarning,
                              r'legacy_function\(\) is deprecated',
                              legacy_function, 'XYZ')

    або:

        with self.assertWarnsRegex(RuntimeWarning, 'unsafe frobnicating'):
            frobnicate('/etc/passwd')

    Нове в версії 3.2.

    Змінено в версії 3.3: Додано аргумент ключового слова msg, коли він використовується як менеджер контексту.

  `assertLogs`(logger=None, level=None)

    Менеджер контексту для перевірки того, що принаймні одне повідомлення зареєстровано в реєстраторі або одному з його дочірніх елементів, принаймні з заданим рівнем.

    Якщо задано, logger має бути об’єктом `logging.Logger` або `str`, що вказує назву реєстратора. За замовчуванням використовується кореневий реєстратор, який фіксуватиме всі повідомлення, які не були заблоковані нащадковим реєстратором без розповсюдження.

    If given, level should be either a numeric logging level or its string equivalent (for example either `"ERROR"` or `logging.ERROR`). The default is `logging.INFO`.

    Тест проходить, якщо принаймні одне повідомлення, видане всередині блоку `with`, відповідає умовам logger і level, в іншому випадку він не виконується.

    Об’єкт, який повертає менеджер контексту, є помічником запису, який відстежує відповідні повідомлення журналу. Він має два атрибути:

    `records`

      Список об’єктів `logging.LogRecord` відповідних повідомлень журналу.

    `output`

      Список об’єктів `str` із відформатованим виведенням відповідних повідомлень.

    Приклад:

        with self.assertLogs('foo', level='INFO') as cm:
            logging.getLogger('foo').info('first message')
            logging.getLogger('foo.bar').error('second message')
        self.assertEqual(cm.output, ['INFO:foo:first message',
                                     'ERROR:foo.bar:second message'])

    Нове в версії 3.4.

  `assertNoLogs`(logger=None, level=None)

    Менеджер контексту для перевірки того, що жодні повідомлення не реєструються в реєстраторі або одному з його дочірніх елементів, принаймні з заданим рівнем.

    Якщо задано, logger має бути об’єктом `logging.Logger` або `str`, що вказує назву реєстратора. Типовим є кореневий реєстратор, який фіксуватиме всі повідомлення.

    If given, level should be either a numeric logging level or its string equivalent (for example either `"ERROR"` or `logging.ERROR`). The default is `logging.INFO`.

    На відміну від `assertLogs()`, контекстний менеджер нічого не повертатиме.

    Нове в версії 3.10.

  Існують також інші методи, які використовуються для виконання більш конкретних перевірок, наприклад:

  метод | Перевіряє це | Нове в
  --- | --- | ---
  `assertAlmostEqual(a, b)` | `round(a-b, 7) == 0` |
  `assertNotAlmostEqual(a, b)` | `округлення(a-b, 7) != 0` |
  `assertGreater(a, b)` | `a > b` | 3.1
  `assertGreaterEqual(a, b)` | `a >= b` | 3.1
  `assertLess(a, b)` | `a < b` | 3.1
  `assertLessEqual(a, b)` | `a <= b` | 3.1
  `assertRegex(s, r)` | `r.search(s)` | 3.1
  `assertNotRegex(s, r)` | `не r.search(s)` | 3.2
  `assertCountEqual(a, b)` | a і b містять однакові елементи в однаковій кількості, незалежно від їх порядку. | 3.2

  `assertAlmostEqual`(first, second, places=7, msg=None, delta=None)
  `assertNotAlmostEqual`(first, second, places=7, msg=None, delta=None)

    Перевірте, що перший і другий приблизно (чи не приблизно) рівні, обчислюючи різницю, округляючи до вказаної кількості десяткових розрядів (за замовчуванням 7) і порівнюючи з нулем. Зауважте, що ці методи округлюють значення до заданої кількості десяткових знаків (тобто як функція `round()`), а не до значущих цифр.

    Якщо замість розрядів вказано delta, тоді різниця між першим і другим має бути менше або дорівнювати (або більше) delta.

    Надання delta і places викликає `TypeError`.

    Змінено в версії 3.2: `assertAlmostEqual()` автоматично вважає майже рівні об’єкти, які порівнюються рівними. `assertNotAlmostEqual()` автоматично не виконується, якщо об’єкти порівнюються. Додано аргумент ключового слова дельта.

  `assertGreater`(first, second, msg=None)
  `assertGreaterEqual`(first, second, msg=None)
  `assertLess`(first, second, msg=None)
  `assertLessEqual`(first, second, msg=None)

    Перевірте, що first відповідно >, >=, < або <= ніж second залежно від назви методу. Якщо ні, тест не пройде:

        >>> self.assertGreaterEqual(3, 4)
        AssertionError: "3" unexpectedly not greater than or equal to "4"

    Нове в версії 3.1.

  `assertRegex`(text, regex, msg=None)
  `assertNotRegex`(text, regex, msg=None)

    Перевірте, чи регулярний вираз пошуку відповідає (або не відповідає) тексту. У разі помилки повідомлення про помилку міститиме шаблон і текст (або шаблон і частину тексту, які неочікувано збіглися). regex може бути об’єктом регулярного виразу або рядком, що містить регулярний вираз, придатний для використання `re.search()`.

    Нове в версії 3.1: Додано під назвою `assertRegexpMatches`.

    Змінено в версії 3.2: Метод `assertRegexpMatches()` було перейменовано на `assertRegex()`.

    Нове в версії 3.2: `assertNotRegex()`.

    Нове в версії 3.5: The name `assertNotRegexpMatches` is a deprecated alias for `assertNotRegex()`.

  `assertCountEqual`(first, second, msg=None)

    Перевірте, чи послідовність first містить ті самі елементи, що й second, незалежно від їх порядку. Якщо цього не зробити, буде згенеровано повідомлення про помилку з переліком відмінностей між послідовностями.

    Повторювані елементи не ігноруються під час порівняння першого та другого. Він перевіряє, чи кожен елемент має однакову кількість в обох послідовностях. Еквівалент: `assertEqual(Counter(list(first)), Counter(list(second)))`, але також працює з послідовностями нехешованих об’єктів.

    Нове в версії 3.2.

  Метод `assertEqual()` надсилає перевірку рівності для об’єктів одного типу до різних методів, що залежать від типу. Ці методи вже реалізовано для більшості вбудованих типів, але також можна зареєструвати нові методи за допомогою `addTypeEqualityFunc()`:

  `addTypeEqualityFunc`(typeobj, function)

    Реєструє специфічний для типу метод, викликаний `assertEqual()`, щоб перевірити, чи порівнюються два об’єкти абсолютно однакового typeobj (не підкласи). функція має приймати два позиційних аргументи та третій аргумент ключового слова msg=None так само, як це робить `assertEqual()`. Він повинен викликати `self.failureException(msg)`, коли виявлено нерівність між першими двома параметрами — можливо, надаючи корисну інформацію та докладно пояснюючи нерівності в повідомленні про помилку.

    Нове в версії 3.1.

  Список специфічних для типу методів, які автоматично використовує `assertEqual()`, підсумовано в наступній таблиці. Зауважте, що зазвичай не потрібно безпосередньо викликати ці методи.

  метод | Використовується для порівняння | Нове в
  --- | --- | ---
  `assertMultiLineEqual(a, b)` | рядки | 3.1
  `assertSequenceEqual(a, b)` | послідовності | 3.1
  `assertListEqual(a, b)` | списки | 3.1
  `assertTupleEqual(a, b)` | кортежі | 3.1
  `assertSetEqual(a, b)` | набори або заморожені набори | 3.1
  `assertDictEqual(a, b)` | дикт | 3.1

  `assertMultiLineEqual`(first, second, msg=None)

    Перевірте, чи багаторядковий рядок перший дорівнює рядку другий. Якщо відмінність двох рядків не дорівнює, у повідомленні про помилку буде включено виділення відмінностей. Цей метод використовується за замовчуванням під час порівняння рядків із `assertEqual()`.

    Нове в версії 3.1.

  `assertSequenceEqual`(first, second, msg=None, seq_type=None)

    Перевіряє рівність двох послідовностей. Якщо вказано seq_type, і first, і second мають бути екземплярами seq_type, інакше виникне помилка. Якщо послідовності відрізняються, створюється повідомлення про помилку, яке показує різницю між ними.

    Цей метод не викликається безпосередньо `assertEqual()`, але він використовується для реалізації `assertListEqual()` і `assertTupleEqual()`.

    Нове в версії 3.1.

  `assertListEqual`(first, second, msg=None)
  `assertTupleEqual`(first, second, msg=None)

    Перевіряє рівність двох списків або кортежів. Якщо ні, створюється повідомлення про помилку, яке показує лише відмінності між ними. Помилка також виникає, якщо один із параметрів має неправильний тип. Ці методи використовуються за замовчуванням під час порівняння списків або кортежів із `assertEqual()`.

    Нове в версії 3.1.

  `assertSetEqual`(first, second, msg=None)

    Перевіряє рівність двох наборів. Якщо ні, створюється повідомлення про помилку, яке містить перелік відмінностей між наборами. Цей метод використовується за замовчуванням під час порівняння наборів або заморожених наборів за допомогою `assertEqual()`.

    Помилка, якщо first або second не має методу `set.difference()`.

    Нове в версії 3.1.

  `assertDictEqual`(first, second, msg=None)

    Перевірте рівність двох словників. Якщо ні, створюється повідомлення про помилку, яке показує відмінності в словниках. Цей метод використовуватиметься за умовчанням для порівняння словників у викликах `assertEqual()`.

    Нове в версії 3.1.

  Нарешті, `TestCase` надає такі методи та атрибути:

  `fail`(msg=None)

    Безумовно сигналізує про помилку тесту за допомогою msg або `None` для повідомлення про помилку.

  `failureException`

    Цей атрибут класу дає виняток, викликаний методом тестування. Якщо тестова структура потребує використання спеціалізованого винятку, можливо, для передачі додаткової інформації, вона повинна створити підклас цього винятку, щоб «грати чесно» з структурою. Початковим значенням цього атрибута є `AssertionError`.

  `longMessage`

    Цей атрибут класу визначає, що відбувається, коли настроюване повідомлення про помилку передається як аргумент msg для виклику assertXYY, який завершується помилкою. `True` - значення за умовчанням. У цьому випадку спеціальне повідомлення додається в кінець стандартного повідомлення про помилку. Якщо встановлено значення `False`, спеціальне повідомлення замінює стандартне повідомлення.

    Налаштування класу можна перевизначити в окремих методах тестування, призначивши атрибуту екземпляра self.longMessage значення `True` або `False` перед викликом методів assert.

    Налаштування класу скидається перед кожним тестовим викликом.

    Нове в версії 3.1.

  `maxDiff`

    Цей атрибут контролює максимальну довжину виведення відмінностей методами assert, які повідомляють про відмінності у разі помилки. За замовчуванням 80*8 символів. Методи підтвердження, на які впливає цей атрибут: `assertSequenceEqual()` (включно з усіма методами порівняння послідовностей, які йому делегують), `assertDictEqual()` і `assertMultiLineEqual()`.

    Встановлення `maxDiff` на `None` означає, що не існує максимальної довжини відмінностей.

    Нове в версії 3.2.

  Платформи тестування можуть використовувати такі методи для збору інформації про тест:

  `countTestCases`()

    Повертає кількість тестів, представлених цим тестовим об’єктом. Для екземплярів `TestCase` це завжди буде `1`.

  `defaultTestResult`()

    Повертає екземпляр класу результатів тесту, який слід використовувати для цього класу тестів (якщо для методу `run()` не надано інший екземпляр результату).

    Для екземплярів `TestCase` це завжди буде екземпляр `TestResult`; підкласи `TestCase` мають замінити це, якщо необхідно.

  `id`()

    Повертає рядок, що ідентифікує конкретний тест. Зазвичай це повна назва тестового методу, включаючи назву модуля та класу.

  `shortDescription`()

    Повертає опис тесту або `None`, якщо опис не надано. Реалізація цього методу за замовчуванням повертає перший рядок документації тестового методу, якщо доступний, або `None`.

    Змінено в версії 3.1: У 3.1 це було змінено, щоб додати назву тесту до короткого опису навіть за наявності рядка документації. Це викликало проблеми сумісності з розширеннями unittest, і додавання назви тесту було перенесено до `TextTestResult` у Python 3.2.

  `addCleanup`(function, /, *args, **kwargs)

    Додайте функцію, яка буде викликатися після `tearDown()` для очищення ресурсів, використаних під час тесту. Функції будуть викликані в порядку, зворотному порядку їх додавання (LIFO). Вони викликаються з будь-якими аргументами та ключовими аргументами, які передаються в `addCleanup()` під час їх додавання.

    Якщо `setUp()` не вдається, тобто `tearDown()` не викликається, тоді будь-які додані функції очищення все одно будуть викликані.

    Нове в версії 3.1.

  `doCleanups`()

    Цей метод викликається безумовно після `tearDown()` або після `setUp()`, якщо `setUp()` викликає виняткову ситуацію.

    Він відповідає за виклик усіх функцій очищення, доданих `addCleanup()`. Якщо вам потрібно, щоб функції очищення викликалися перед `tearDown()`, ви можете викликати `doCleanups()` самостійно.

    `doCleanups()` витягує методи зі стеку функцій очищення по одному, тому їх можна викликати будь-коли.

    Нове в версії 3.1.

  classmethod `addClassCleanup`(function, /, *args, **kwargs)

    Додайте функцію, яка буде викликатися після `tearDownClass()` до ресурсів очищення, використаних під час тестового класу. Функції будуть викликані в порядку, зворотному порядку їх додавання (LIFO). Вони викликаються з будь-якими аргументами та ключовими аргументами, які передаються в `addClassCleanup()` під час їх додавання.

    Якщо `setUpClass()` не вдається, тобто `tearDownClass()` не викликається, тоді будь-які додані функції очищення все одно будуть викликані.

    Нове в версії 3.8.

  classmethod `doClassCleanups`()

    Цей метод викликається безумовно після `tearDownClass()` або після `setUpClass()`, якщо `setUpClass()` викликає виняток.

    Він відповідає за виклик усіх функцій очищення, доданих `addClassCleanup()`. Якщо вам потрібно, щоб функції очищення викликалися перед `tearDownClass()`, ви можете викликати `doClassCleanups()` самостійно.

    `doClassCleanups()` витягує методи зі стеку функцій очищення по одному, тому їх можна викликати будь-коли.

    Нове в версії 3.8.

class `unittest.``IsolatedAsyncioTestCase`(methodName='runTest')

  Цей клас надає API, подібний до `TestCase`, а також приймає співпрограми як тестові функції.

  Нове в версії 3.8.

  coroutine `asyncSetUp`()

    Метод, який називається для підготовки випробувального матеріалу. Це викликається після `setUp()`. Це викликається безпосередньо перед викликом тестового методу; крім `AssertionError` або `SkipTest`, будь-який виняток, викликаний цим методом, вважатиметься помилкою, а не помилкою тесту. Стандартна реалізація нічого не робить.

  coroutine `asyncTearDown`()

    Метод викликається відразу після виклику тестового методу та запису результату. Це викликається перед `tearDown()`. Це викликається, навіть якщо метод тестування викликав виняток, тому реалізація в підкласах може потребувати особливої обережності щодо перевірки внутрішнього стану. Будь-які винятки, окрім `AssertionError` або `SkipTest`, викликані цим методом, вважатимуться додатковою помилкою, а не помилкою тесту (таким чином збільшуючи загальну кількість повідомлених помилок). Цей метод буде викликано, лише якщо `asyncSetUp()` завершиться успішно, незалежно від результату тестового методу. Стандартна реалізація нічого не робить.

  `addAsyncCleanup`(function, /, *args, **kwargs)

    Цей метод приймає співпрограму, яку можна використовувати як функцію очищення.

  `run`(result=None)

    Встановлює новий цикл подій для запуску тесту, збираючи результат в об’єкт `TestResult`, переданий як результат. Якщо результат пропущено або `None`, створюється та використовується тимчасовий об’єкт результату (викликом методу `defaultTestResult()`). Об’єкт результату повертається до виклику `run()`. Після закінчення тесту всі завдання в циклі подій скасовуються.

  Приклад, що ілюструє порядок:

      from unittest import IsolatedAsyncioTestCase

      events = []

      class Test(IsolatedAsyncioTestCase):

          def setUp(self):
              events.append("setUp")

          async def asyncSetUp(self):
              self._async_connection = await AsyncConnection()
              events.append("asyncSetUp")

          async def test_response(self):
              events.append("test_response")
              response = await self._async_connection.get("https://example.com")
              self.assertEqual(response.status_code, 200)
              self.addAsyncCleanup(self.on_cleanup)

          def tearDown(self):
              events.append("tearDown")

          async def asyncTearDown(self):
              await self._async_connection.close()
              events.append("asyncTearDown")

          async def on_cleanup(self):
              events.append("cleanup")

      if __name__ == "__main__":
          unittest.main()

  Після виконання тесту `події` міститимуть `["setUp", "asyncSetUp", "test_response", "asyncTearDown", "tearDown", "cleanup"]`.

class `unittest.``FunctionTestCase`(testFunc, setUp=None, tearDown=None, description=None)

  Цей клас реалізує частину інтерфейсу `TestCase`, яка дозволяє виконавцю тесту управляти тестом, але не надає методів, які тестовий код може використовувати для перевірки та звітування про помилки. Це використовується для створення тестів із використанням застарілого тестового коду, що дозволяє інтегрувати його в тестову структуру на основі `unittest`.

#### Deprecated aliases

For historical reasons, some of the `TestCase` methods had one or more aliases that are now deprecated. The following table lists the correct names along with their deprecated aliases:

> Method Name | Deprecated alias | Deprecated alias
> --- | --- | ---
> `assertEqual()` | failUnlessEqual | assertEquals
> `assertNotEqual()` | failIfEqual | assertNotEquals
> `assertTrue()` | failUnless | assert_
> `assertFalse()` | failIf |
> `assertRaises()` | failUnlessRaises |
> `assertAlmostEqual()` | failUnlessAlmostEqual | assertAlmostEquals
> `assertNotAlmostEqual()` | failIfAlmostEqual | assertNotAlmostEquals
> `assertRegex()` |  | assertRegexpMatches
> `assertNotRegex()` |  | assertNotRegexpMatches
> `assertRaisesRegex()` |  | assertRaisesRegexp

> Застаріло починаючи з версії 3.1: The fail* aliases listed in the second column have been deprecated.

> Застаріло починаючи з версії 3.2: The assert* aliases listed in the third column have been deprecated.

> Застаріло починаючи з версії 3.2: `assertRegexpMatches` and `assertRaisesRegexp` have been renamed to `assertRegex()` and `assertRaisesRegex()`.

> Застаріло починаючи з версії 3.5: The `assertNotRegexpMatches` name is deprecated in favor of `assertNotRegex()`.

### Групування тестів

class `unittest.``TestSuite`(tests=())

  Цей клас представляє сукупність окремих тестових випадків і наборів тестів. Клас представляє інтерфейс, необхідний виконавцю тесту, щоб дозволити йому запускатися як будь-який інший тестовий приклад. Запуск екземпляра `TestSuite` — це те саме, що ітерація по набору, запускаючи кожен тест окремо.

  Якщо надано тести, це має бути ітерація окремих тестових випадків або інших наборів тестів, які будуть використані для створення набору спочатку. Додаткові методи надаються для додавання тестів і пакетів до колекції пізніше.

  Об’єкти `TestSuite` поводяться так само, як об’єкти `TestCase`, за винятком того, що вони насправді не реалізують тест. Натомість вони використовуються для агрегування тестів у групи тестів, які слід виконувати разом. Деякі додаткові методи доступні для додавання тестів до екземплярів `TestSuite`:

  `addTest`(test)

    Додайте `TestCase` або `TestSuite` до набору.

  `addTests`(tests)

    Додайте всі тести з ітерації екземплярів `TestCase` і `TestSuite` до цього набору тестів.

    Це еквівалентно повторенню тестів, виклику `addTest()` для кожного елемента.

  `TestSuite` використовує такі методи спільно з `TestCase`:

  `run`(result)

    Запустіть тести, пов’язані з цим набором, зібравши результат в об’єкт результату тесту, переданий як результат. Зауважте, що на відміну від `TestCase.run()`, `TestSuite.run()` вимагає передачі об’єкта результату.

  `debug`()

    Виконуйте тести, пов’язані з цим пакетом, без збору результатів. Це дозволяє поширювати винятки, викликані тестом, до абонента та може використовуватися для підтримки запуску тестів під налагоджувачем.

  `countTestCases`()

    Повертає кількість тестів, представлених цим тестовим об’єктом, включаючи всі окремі тести та піднабори.

  `__iter__`()

    Tests grouped by a `TestSuite` are always accessed by iteration. Subclasses can lazily provide tests by overriding `__iter__()`. Note that this method may be called several times on a single suite (for example when counting tests or comparing for equality) so the tests returned by repeated iterations before `TestSuite.run()` must be the same for each call iteration. After `TestSuite.run()`, callers should not rely on the tests returned by this method unless the caller uses a subclass that overrides `TestSuite._removeTestAtIndex()` to preserve test references.

    Змінено в версії 3.2: In earlier versions the `TestSuite` accessed tests directly rather than through iteration, so overriding `__iter__()` wasn’t sufficient for providing tests.

    Змінено в версії 3.4: У попередніх версіях `TestSuite` містив посилання на кожен `TestCase` після `TestSuite.run()`. Підкласи можуть відновити цю поведінку, замінивши `TestSuite._removeTestAtIndex()`.

  У типовому використанні об’єкта `TestSuite` метод `run()` викликається `TestRunner`, а не тестовим пакетом кінцевого користувача.

### Завантаження та виконання тестів

class `unittest.``TestLoader`

  Клас `TestLoader` використовується для створення наборів тестів із класів і модулів. Зазвичай немає необхідності створювати екземпляр цього класу; модуль `unittest` надає екземпляр, який можна використовувати як `unittest.defaultTestLoader`. Однак використання підкласу або екземпляра дозволяє налаштувати деякі настроювані властивості.

  `TestLoader` об’єкти мають такі атрибути:

  `errors`

    A list of the non-fatal errors encountered while loading tests. Not reset by the loader at any point. Fatal errors are signalled by the relevant method raising an exception to the caller. Non-fatal errors are also indicated by a synthetic test that will raise the original error when run.

    Нове в версії 3.5.

  Об’єкти `TestLoader` мають такі методи:

  `loadTestsFromTestCase`(testCaseClass)

    Повертає набір усіх тестів, що містяться в `TestCase`-похідному `testCaseClass`.

    Екземпляр тестового випадку створюється для кожного методу, названого `getTestCaseNames()`. За замовчуванням це імена методів, які починаються з `test`. Якщо `getTestCaseNames()` не повертає жодних методів, але реалізовано метод `runTest()`, натомість для цього методу створюється один тестовий приклад.

  `loadTestsFromModule`(module, pattern=None)

    Повертає набір усіх тестів, що містяться в даному модулі. Цей метод шукає в module класи, похідні від `TestCase`, і створює екземпляр класу для кожного тестового методу, визначеного для класу.

    Примітка

    Хоча використання ієрархії похідних класів `TestCase`може бути зручним для спільного використання фікстур і допоміжних функцій, визначення методів тестування на базових класах, які не призначені для безпосереднього створення екземплярів, не підходить для цього методу. Однак це може бути корисним, коли прилади різні та визначені в підкласах.

    Якщо модуль надає функцію `load_tests`, її буде викликано для завантаження тестів. Це дозволяє модулям налаштовувати тестове завантаження. Це протокол load_tests. Аргумент pattern передається як третій аргумент у `load_tests`.

    Змінено в версії 3.2: Додано підтримку `load_tests`.

    Змінено в версії 3.5: The undocumented and unofficial use_load_tests default argument is deprecated and ignored, although it is still accepted for backward compatibility. The method also now accepts a keyword-only argument pattern which is passed to `load_tests` as the third argument.

  `loadTestsFromName`(name, module=None)

    Повертає набір усіх тестів із специфікатором рядка.

    Специфікатор name — це «ім’я з крапками», яке може перетворюватися на модуль, клас тестового прикладу, метод тестування в класі тестового випадку, екземпляр `TestSuite` або викликаний об’єкт, який повертає: екземпляр `TestCase` або `TestSuite`. Ці перевірки застосовуються в зазначеному тут порядку; тобто метод у можливому класі тестового випадку буде вибрано як «метод тестування в класі тестового випадку», а не як «об’єкт, який можна викликати».

    Наприклад, якщо у вас є модуль `SampleTests`, який містить `TestCase`-похідний клас `SampleTestCase` із трьома методами тестування (`test_one()`, `test_two()` і `test_three()`), специфікатор `'SampleTests.SampleTestCase'` призведе до того, що цей метод повертатиме набір, який виконуватиме всі три методи тестування. Використання специфікатора `'SampleTests.SampleTestCase.test_two` призведе до повернення набору тестів, який запускатиме лише метод тестування `test_two()`. Специфікатор може посилатися на модулі та пакунки, які не були імпортовані; вони будуть імпортовані як побічний ефект.

    Метод необов’язково розпізнає ім’я відносно даного модуля.

    Змінено в версії 3.5: Якщо `ImportError` або `AttributeError` виникає під час обходу name, тоді буде повернено синтетичний тест, який викликає цю помилку під час запуску. Ці помилки включено до помилок, накопичених self.errors.

  `loadTestsFromNames`(names, module=None)

    Подібно до `loadTestsFromName()`, але приймає послідовність імен, а не одне ім’я. Повернене значення — це набір тестів, який підтримує всі тести, визначені для кожного імені.

  `getTestCaseNames`(testCaseClass)

    Повертає відсортовану послідовність імен методів, знайдених у testCaseClass; це має бути підклас `TestCase`.

  `discover`(start_dir, pattern='test*.py', top_level_dir=None)

    Знайдіть усі тестові модулі, перейшовши до підкаталогів із зазначеного початкового каталогу, і поверніть об’єкт TestSuite, що містить їх. Будуть завантажені лише тестові файли, які відповідають шаблону. (Використовуючи зіставлення шаблону стилю оболонки.) Завантажуватимуться лише імена модулів, які можна імпортувати (тобто є дійсними ідентифікаторами Python).

    All test modules must be importable from the top level of the project. If the start directory is not the top level directory then the top level directory must be specified separately.

    Якщо імпортувати модуль не вдалося, наприклад, через синтаксичну помилку, це буде записано як одну помилку, і виявлення продовжиться. Якщо помилка імпорту спричинена викликом `SkipTest`, це буде записано як пропуск замість помилки.

    Якщо пакунок (каталог, що містить файл із назвою `__init__.py`) знайдено, пакунок буде перевірено на наявність функції `load_tests`. Якщо він існує, він називатиметься `package.load_tests(loader, tests, pattern)`. Тестове виявлення піклується про те, щоб пакет перевірявся на наявність тестів лише один раз під час виклику, навіть якщо сама функція load_tests викликає `loader.discover`.

    Якщо `load_tests` існує, виявлення не рекурсує в пакунок, `load_tests` відповідає за завантаження всіх тестів у пакунок.

    The pattern is deliberately not stored as a loader attribute so that packages can continue discovery themselves. top_level_dir is stored so `load_tests` does not need to pass this argument in to `loader.discover()`.

    start_dir може бути назвою модуля з крапками, а також каталогом.

    Нове в версії 3.2.

    Змінено в версії 3.4: Модулі, які викликають `SkipTest` під час імпорту, записуються як пропуски, а не як помилки.

    Змінено в версії 3.4: start_dir може бути пакети простору імен.

    Змінено в версії 3.4: Шляхи сортуються перед імпортом, щоб порядок виконання був однаковим, навіть якщо порядок базової файлової системи не залежить від імені файлу.

    Змінено в версії 3.5: Знайдені пакунки тепер перевіряються на `load_tests` незалежно від того, чи відповідає їхній шлях шаблону, оскільки назва пакета не може відповідати шаблону за замовчуванням.

  Наступні атрибути `TestLoader` можуть бути налаштовані за допомогою підкласу або призначення для екземпляра:

  `testMethodPrefix`

    Рядок із префіксом імен методів, які будуть інтерпретуватися як тестові методи. Значення за замовчуванням - `'test'`.

    This affects `getTestCaseNames()` and all the `loadTestsFrom*()` methods.

  `sortTestMethodsUsing`

    Function to be used to compare method names when sorting them in `getTestCaseNames()` and all the `loadTestsFrom*()` methods.

  `suiteClass`

    Викликаний об’єкт, який створює набір тестів зі списку тестів. Жодних методів для отриманого об’єкта не потрібно. Стандартним значенням є клас `TestSuite`.

    This affects all the `loadTestsFrom*()` methods.

  `testNamePatterns`

    List of Unix shell-style wildcard test name patterns that test methods have to match to be included in test suites (see `-k` option).

    If this attribute is not `None` (the default), all test methods to be included in test suites must match one of the patterns in this list. Note that matches are always performed using `fnmatch.fnmatchcase()`, so unlike patterns passed to the `-k` option, simple substring patterns will have to be converted using `*` wildcards.

    This affects all the `loadTestsFrom*()` methods.

    Нове в версії 3.7.

class `unittest.``TestResult`

  Цей клас використовується для компіляції інформації про те, які тести були успішними, а які невдалими.

  Об’єкт `TestResult` зберігає результати набору тестів. Класи `TestCase` і `TestSuite` забезпечують належний запис результатів; авторам тестів не потрібно турбуватися про запис результатів тестів.

  Фреймворки тестування, створені на основі `unittest`, можуть потребувати доступу до об’єкта `TestResult`, згенерованого за допомогою виконання набору тестів для цілей звітування; екземпляр `TestResult` повертається методом `TestRunner.run()` для цієї мети.

  Екземпляри `TestResult` мають такі атрибути, які будуть цікавими під час перевірки результатів виконання набору тестів:

  `errors`

    Список, що містить 2 кортежі екземплярів `TestCase` і рядки, що містять відформатовані відстеження. Кожен кортеж представляє тест, який викликав несподіваний виняток.

  `failures`

    A list containing 2-tuples of `TestCase` instances and strings holding formatted tracebacks. Each tuple represents a test where a failure was explicitly signalled using the `TestCase.assert*()` methods.

  `skipped`

    Список, що містить 2 кортежі екземплярів `TestCase` і рядки з причиною пропуску тесту.

    Нове в версії 3.1.

  `expectedFailures`

    Список, що містить 2 кортежі екземплярів `TestCase` і рядки, що містять відформатовані відстеження. Кожен кортеж представляє очікуваний збій або помилку тестового випадку.

  `unexpectedSuccesses`

    Список, що містить екземпляри `TestCase`, які були позначені як очікувані помилки, але були успішними.

  `shouldStop`

    Установіть значення `True`, коли виконання тестів має зупинятися на `stop()`.

  `testsRun`

    Загальна кількість проведених тестів.

  `buffer`

    Якщо встановлено значення true, `sys.stdout` і `sys.stderr` будуть буферизовані між викликами `startTest()` і `stopTest()`. Зібраний вихід буде відображено на справжній `sys.stdout` і `sys.stderr` лише у разі невдачі тесту або помилок. Будь-який вихід також додається до повідомлення про збій/помилку.

    Нове в версії 3.2.

  `failfast`

    Якщо встановлено значення true, `stop()` буде викликано при першій невдачі або помилці, зупиняючи тестовий запуск.

    Нове в версії 3.2.

  `tb_locals`

    Якщо встановлено значення true, то локальні змінні відображатимуться у відстеженнях.

    Нове в версії 3.5.

  `wasSuccessful`()

    Повертає `True`, якщо всі тести, запущені до цього моменту, пройдено, інакше повертає `False`.

    Змінено в версії 3.4: Повертає `False`, якщо були будь-які `unexpectedSuccesses` від тестів, позначених декоратором `expectedFailure()`.

  `stop`()

    Цей метод можна викликати, щоб повідомити про те, що набір запущених тестів має бути перервано, встановивши атрибут `shouldStop` на `True`. Об’єкти `TestRunner` мають поважати цей прапор і повертатися без виконання додаткових тестів.

    Наприклад, ця функція використовується класом `TextTestRunner`, щоб зупинити тестову структуру, коли користувач сигналізує про переривання з клавіатури. Інтерактивні інструменти, які забезпечують реалізації `TestRunner`, можуть використовувати це подібним чином.

  Наступні методи класу `TestResult` використовуються для підтримки внутрішніх структур даних і можуть бути розширені в підкласах для підтримки додаткових вимог до звітності. Це особливо корисно для створення інструментів, які підтримують інтерактивне звітування під час виконання тестів.

  `startTest`(test)

    Викликається, коли тестовий приклад test збирається запустити.

  `stopTest`(test)

    Викликається після виконання тесту test, незалежно від результату.

  `startTestRun`()

    Викликається один раз перед виконанням будь-яких тестів.

    Нове в версії 3.1.

  `stopTestRun`()

    Викликається один раз після виконання всіх тестів.

    Нове в версії 3.1.

  `addError`(test, err)

    Викликається, коли тестовий приклад test викликає несподіваний виняток. err — це кортеж у формі, яку повертає `sys.exc_info()`: `(тип, значення, відстеження)`.

    Реалізація за замовчуванням додає кортеж `(test, formatted_err)` до атрибута екземпляра `errors`, де formatted_err є відформатованим зворотним трасуванням, отриманим від err.

  `addFailure`(test, err)

    Викликається, коли тестовий приклад test сигналізує про помилку. err — це кортеж у формі, яку повертає `sys.exc_info()`: `(тип, значення, відстеження)`.

    Реалізація за замовчуванням додає кортеж `(test, formatted_err)` до атрибута екземпляра `failures`, де formatted_err є відформатованим зворотним трасуванням, отриманим від err.

  `addSuccess`(test)

    Викликається, коли тестовий приклад test виконується успішно.

    Стандартна реалізація нічого не робить.

  `addSkip`(test, reason)

    Викликається, коли тестовий приклад test пропускається. причина — причина пропуску тесту.

    Реалізація за замовчуванням додає кортеж `(test, reason)` до атрибута екземпляра `skipped`.

  `addExpectedFailure`(test, err)

    Викликається, коли тестовий приклад test зазнає невдачі або помилки, але його позначено декоратором `expectedFailure()`.

    Реалізація за замовчуванням додає кортеж `(test, formatted_err)` до атрибута екземпляра `expectedFailures`, де formatted_err є відформатованим зворотним трасуванням, отриманим від err.

  `addUnexpectedSuccess`(test)

    Викликається, коли тестовий приклад test був позначений декоратором `expectedFailure()`, але завершився успішно.

    Стандартна реалізація додає тест до атрибута екземпляра `unexpectedSuccesses`.

  `addSubTest`(test, subtest, outcome)

    Викликається після завершення підтесту. test — тестовий приклад, що відповідає методу тестування. subtest — це спеціальний екземпляр `TestCase`, який описує субтест.

    Якщо результат `None`, субтест пройшов успішно. В іншому випадку це не вдалося за винятком, коли результат є кортежем форми, яку повертає `sys.exc_info()`: `(тип, значення, відстеження)`.

    Реалізація за замовчуванням не робить нічого, якщо результат є успішним, і записує помилки підтесту як звичайні помилки.

    Нове в версії 3.4.

class `unittest.``TextTestResult`(stream, descriptions, verbosity)

  A concrete implementation of `TestResult` used by the `TextTestRunner`.

  Нове в версії 3.2: This class was previously named `_TextTestResult`. The old name still exists as an alias but is deprecated.

`unittest.``defaultTestLoader`

  Примірник класу `TestLoader` призначений для спільного використання. Якщо налаштування `TestLoader` не потрібні, цей екземпляр можна використовувати замість повторного створення нових екземплярів.

class `unittest.``TextTestRunner`(stream=None, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None, warnings=None, *, tb_locals=False)

  Базова реалізація програми виконання тестів, яка виводить результати в потік. Якщо stream має значення `None`, стандартний `sys.stderr` використовується як вихідний потік. Цей клас має декілька настроюваних параметрів, але по суті дуже простий. Графічні програми, які запускають набори тестів, повинні надавати альтернативні реалізації. Такі реалізації повинні приймати `**kwargs`, оскільки інтерфейс для створення бігунів змінюється, коли функції додаються до unittest.

  By default this runner shows `DeprecationWarning`, `PendingDeprecationWarning`, `ResourceWarning` and `ImportWarning` even if they are ignored by default. Deprecation warnings caused by deprecated unittest methods are also special-cased and, when the warning filters are `'default'` or `'always'`, they will appear only once per-module, in order to avoid too many warning messages. This behavior can be overridden using Python’s `-Wd` or `-Wa` options (see Warning control) and leaving warnings to `None`.

  Змінено в версії 3.2: Added the `warnings` argument.

  Змінено в версії 3.2: Потік за замовчуванням встановлено на `sys.stderr` під час створення екземпляра, а не під час імпорту.

  Змінено в версії 3.5: Added the tb_locals parameter.

  `_makeResult`()

    Цей метод повертає екземпляр `TestResult`, який використовується `run()`. Він не призначений для безпосереднього виклику, але може бути замінений у підкласах, щоб надати спеціальний `TestResult`.

    `_makeResult()` створює екземпляр класу або виклику, переданого в конструкторі `TextTestRunner` як аргумент `resultclass`. За замовчуванням `TextTestResult`, якщо не надано `resultclass`. Клас результату створюється з такими аргументами:

        stream, descriptions, verbosity

  `run`(test)

    Цей метод є основним публічним інтерфейсом для `TextTestRunner`. Цей метод приймає екземпляр `TestSuite` або `TestCase`. `TestResult` створюється шляхом виклику `_makeResult()`, і тест(и) запускаються, а результати виводяться на stdout.

`unittest.``main`(module='__main__', defaultTest=None, argv=None, testRunner=None, testLoader=unittest.defaultTestLoader, exit=True, verbosity=1, failfast=None, catchbreak=None, buffer=None, warnings=None)

  Програма командного рядка, яка завантажує набір тестів із модуля та запускає їх; це насамперед для того, щоб зробити тестові модулі зручними для виконання. Найпростішим використанням цієї функції є додавання такого рядка в кінці тестового сценарію:

      if __name__ == '__main__':
          unittest.main()

  Ви можете запустити тести з більш детальною інформацією, передавши аргумент verbosity:

      if __name__ == '__main__':
          unittest.main(verbosity=2)

  Аргумент defaultTest — це або назва окремого тесту, або ітерація імен тестів для запуску, якщо жодні імена тестів не вказані через argv. Якщо не вказано або `None`, а імена тестів не надаються через argv, запускаються всі тести, знайдені в module.

  Аргумент argv може бути списком параметрів, переданих програмі, з першим елементом, який є назвою програми. Якщо не вказано або `None`, використовуються значення `sys.argv`.

  The testRunner argument can either be a test runner class or an already created instance of it. By default `main` calls `sys.exit()` with an exit code indicating success or failure of the tests run.

  Аргумент testLoader має бути екземпляром `TestLoader` і за умовчанням має значення `defaultTestLoader`.

  `main` підтримує використання з інтерактивного інтерпретатора шляхом передачі аргументу `exit=False`. Це відображає результат у стандартному виводі без виклику `sys.exit()`:

      >>> from unittest import main
      >>> main(module='test_module', exit=False)

  Параметри failfast, catchbreak і buffer мають той самий ефект, що й одноіменні параметри командного рядка (command-line options).

  Аргумент попередження вказує фільтр попереджень, який слід використовувати під час виконання тестів. Якщо його не вказано, він залишатиметься `None`, якщо параметр `-W` передано python (див. Контроль попередження), інакше він буде встановлений на `'за замовчуванням`.

  Calling `main` actually returns an instance of the `TestProgram` class. This stores the result of the tests run as the `result` attribute.

  Змінено в версії 3.1: Додано параметр exit.

  Змінено в версії 3.2: Додано параметри verbosity, failfast, catchbreak, buffer і warnings.

  Змінено в версії 3.4: Параметр defaultTest було змінено, щоб також приймати ітерацію імен тестів.

#### протокол load_tests

Нове в версії 3.2.

Модулі або пакунки можуть налаштувати спосіб завантаження тестів з них під час звичайних тестових прогонів або виявлення тестів, реалізувавши функцію під назвою `load_tests`.

Якщо тестовий модуль визначає `load_tests`, він буде викликаний `TestLoader.loadTestsFromModule()` з такими аргументами:

    load_tests(loader, standard_tests, pattern)

де шаблон передається безпосередньо з `loadTestsFromModule`. За замовчуванням `None`.

Він має повернути `TestSuite`.

loader — це екземпляр `TestLoader`, який виконує завантаження. standard_tests — це тести, які за замовчуванням завантажуватимуться з модуля. Зазвичай тестові модулі хочуть лише додавати або видаляти тести зі стандартного набору тестів. Третій аргумент використовується під час завантаження пакетів у рамках виявлення тесту.

Типова функція `load_tests`, яка завантажує тести з певного набору класів `TestCase`, може виглядати так:

    test_cases = (TestCase1, TestCase2, TestCase3)

    def load_tests(loader, tests, pattern):
        suite = TestSuite()
        for test_class in test_cases:
            tests = loader.loadTestsFromTestCase(test_class)
            suite.addTests(tests)
        return suite

Якщо відкриття розпочато в каталозі, що містить пакет, або з командного рядка, або викликом `TestLoader.discover()`, тоді пакет `__init__.py` буде перевірено на `load_tests`. Якщо ця функція не існує, виявлення повториться в пакунку так, ніби це просто інший каталог. В іншому випадку виявлення тестів пакета буде залишено до `load_tests`, який викликається з такими аргументами:

    load_tests(loader, standard_tests, pattern)

Це має повернути `TestSuite`, що представляє всі тести з пакета. (`standard_tests` міститиме лише тести, зібрані з `__init__.py`.)

Оскільки шаблон передається в `load_tests`, пакунок може продовжувати (і потенційно змінювати) пошук тестів. Функція `load_tests` „нічого не робити“ для тестового пакета виглядатиме так:

    def load_tests(loader, standard_tests, pattern):
        # top level directory cached on loader instance
        this_dir = os.path.dirname(__file__)
        package_tests = loader.discover(start_dir=this_dir, pattern=pattern)
        standard_tests.addTests(package_tests)
        return standard_tests

Змінено в версії 3.5: Discovery більше не перевіряє назви пакетів на відповідність шаблону через те, що назви пакетів не відповідають шаблону за замовчуванням.

## Фікстури класів і модулів

Фікстури рівня класу та модуля реалізовано в `TestSuite`. Коли набір тестів зустрічає тест з нового класу, викликається `tearDownClass()` з попереднього класу (якщо він є), а потім `setUpClass()` з нового класу.

Подібним чином, якщо тест виконується з модуля, відмінного від попереднього, тоді запускається `tearDownModule` з попереднього модуля, а потім `setUpModule` з нового модуля.

Після виконання всіх тестів запускаються остаточні `tearDownClass` і `tearDownModule`.

Зауважте, що спільні прилади погано працюють із [потенційними] функціями, такими як розпаралелювання тестів, і вони порушують ізоляцію тестів. Їх слід використовувати обережно.

Стандартний порядок тестів, створених завантажувачами тестів unittest, полягає в тому, щоб групувати всі тести з однакових модулів і класів разом. Це призведе до виклику `setUpClass` / `setUpModule` (і т.д.) рівно один раз для кожного класу та модуля. Якщо ви рандомізуєте порядок, щоб тести з різних модулів і класів були суміжними один з одним, тоді ці спільні функції фікстури можуть викликатися кілька разів під час одного запуску тесту.

Спільні світильники не призначені для роботи з комплектами з нестандартним упорядкуванням. `BaseTestSuite` все ще існує для фреймворків, які не хочуть підтримувати спільні фікстури.

Якщо є будь-які винятки, викликані під час однієї зі спільних функцій приладу, тест повідомляється як помилка. Оскільки немає відповідного екземпляра тесту, для представлення помилки створюється об’єкт `_ErrorHolder` (який має той самий інтерфейс, що й `TestCase`). Якщо ви просто використовуєте стандартний модуль тестування, ця деталь не має значення, але якщо ви є автором фреймворку, вона може бути актуальною.

### setUpClass і tearDownClass

Вони повинні бути реалізовані як методи класу:

    import unittest

    class Test(unittest.TestCase):
        @classmethod
        def setUpClass(cls):
            cls._connection = createExpensiveConnectionObject()

        @classmethod
        def tearDownClass(cls):
            cls._connection.destroy()

Якщо ви хочете викликати `setUpClass` і `tearDownClass` базових класів, ви повинні викликати їх самостійно. Реалізації в `TestCase` порожні.

Якщо під час `setUpClass` виникає виняток, то тести в класі не запускаються, а `tearDownClass` не запускається. Пропущені класи не запускатимуть `setUpClass` або `tearDownClass`. Якщо виняток є винятком `SkipTest`, тоді клас буде повідомлено як пропущений, а не як помилку.

### setUpModule і tearDownModule

Вони повинні бути реалізовані як функції:

    def setUpModule():
        createConnection()

    def tearDownModule():
        closeConnection()

Якщо в `setUpModule` виникає виняток, тоді жоден із тестів у модулі не буде запущено, а `tearDownModule` не буде запущено. Якщо виняток є винятком `SkipTest`, тоді модуль буде повідомлено як пропущений, а не як помилку.

Щоб додати код очищення, який потрібно запускати навіть у випадку винятку, використовуйте `addModuleCleanup`:

`unittest.``addModuleCleanup`(function, /, *args, **kwargs)

  Додайте функцію, яка буде викликатися після `tearDownModule()` для очищення ресурсів, використаних під час тестового класу. Функції будуть викликані в порядку, зворотному порядку їх додавання (LIFO). Вони викликаються з будь-якими аргументами та ключовими аргументами, які передаються в `addModuleCleanup()` під час їх додавання.

  Якщо `setUpModule()` не вдається, тобто `tearDownModule()` не викликається, тоді будь-які додані функції очищення все одно будуть викликані.

  Нове в версії 3.8.

`unittest.``doModuleCleanups`()

  Ця функція викликається безумовно після `tearDownModule()` або після `setUpModule()`, якщо `setUpModule()` викликає виняткову ситуацію.

  Він відповідає за виклик усіх функцій очищення, доданих `addModuleCleanup()`. Якщо вам потрібно, щоб функції очищення викликалися перед `tearDownModule()`, ви можете викликати `doModuleCleanups()` самостійно.

  `doModuleCleanups()` витягує методи зі стеку функцій очищення по одному, тому їх можна викликати будь-коли.

  Нове в версії 3.8.

## Обробка сигналів

Нове в версії 3.2.

The `-c/--catch` command-line option to unittest, along with the `catchbreak` parameter to `unittest.main()`, provide more friendly handling of control-C during a test run. With catch break behavior enabled control-C will allow the currently running test to complete, and the test run will then end and report all the results so far. A second control-c will raise a `KeyboardInterrupt` in the usual way.

Обробник сигналів обробки control-c намагається залишатися сумісним із кодом або тестами, які встановлюють власний обробник `signal.SIGINT`. Якщо обробник `unittest` викликається, але не встановлений обробник `signal.SIGINT`, тобто він був замінений тестованою системою та делегований, тоді він викликає обробник за замовчуванням. Зазвичай це буде очікувана поведінка коду, який замінює встановлений обробник і делегує йому. Для окремих тестів, які потребують вимкнення обробки `unittest` control-c, можна використовувати декоратор `removeHandler()`.

Існує кілька службових функцій для авторів фреймворків, щоб увімкнути функціональність обробки control-c у тестових фреймворках.

`unittest.``installHandler`()

  Встановіть обробник control-c. Коли отримано `signal.SIGINT` (зазвичай у відповідь на натискання користувачем control-c), усі зареєстровані результати викликають `stop()`.

`unittest.``registerResult`(result)

  Зареєструйте об’єкт `TestResult` для обробки control-c. Реєстрація результату зберігає слабке посилання на нього, тому це не запобігає збиранню сміття результату.

  Реєстрація об’єкта `TestResult` не має побічних ефектів, якщо обробку control-c не ввімкнено, тому тестові фреймворки можуть беззастережно реєструвати всі створені ними результати незалежно від того, увімкнено обробку чи ні.

`unittest.``removeResult`(result)

  Видалити зареєстрований результат. Після видалення результату `stop()` більше не викликатиметься для цього об’єкта результату у відповідь на control-c.

`unittest.``removeHandler`(function=None)

  При виклику без аргументів ця функція видаляє обробник control-c, якщо він був встановлений. Цю функцію також можна використовувати як декоратор тесту для тимчасового видалення обробника під час виконання тесту:

      @unittest.removeHandler
      def test_signal_handling(self):
          ...