Написання, виконання та тестування коду¶

Щоб виправити помилку або реалізувати нову функцію, вам доведеться написати новий код.

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

У нас є посібник зі стилю написання коду, в якому викладені наші рекомендації щодо написання коду для BeeWare.

Розробка на основі тестування¶

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

Запустіть свій код¶

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

Ви додасте свій тестовий приклад до набору тестів, щоб його можна було виконати разом з іншими тестами. Наступним кроком є запуск набору тестів.

Виконання тестів та вимірювання покриття¶

BeeWare використовує tox для управління процесом тестування та pytest для власного набору тестів.

Команда tox за замовчуванням передбачає виконання:

хуки перед комітом
towncrier перевірка приміток до випуску
перевірка документації на дотримання стилістики
набір тестів для доступних версій Python
звіти про покриття коду

По суті, саме це виконує CI, коли ви надсилаєте запит на злиття.

Щоб запустити повний набір тестів, виконайте наступну команду:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

Виконання повного набору тестів може зайняти деякий час. Ви можете значно пришвидшити цей процес, запустивши tox паралельно, за допомогою команди tox p (або tox run-parallel). Якщо ви запускаєте набір тестів паралельно, ви отримаєте менше інформації про хід виконання тестів під час їх роботи, але все одно отримаєте звіт про виявлені проблеми наприкінці тестування. Ви повинні отримати вихідні дані, що вказують на те, що тести були виконані. Ви можете побачити SKIPPED тестів, але ніколи не повинні отримувати жодних результатів тестів FAIL або ERROR. Ми запускаємо повний набір тестів перед злиттям кожного патча. Якщо під час цього процесу виявляються якісь проблеми, ми не зливаємо патч. Якщо ви все-таки виявили помилку або збій у тесті, це означає, що або у вашому тестовому середовищі є щось незвичайне, або ви знайшли крайній випадок, якого ми раніше не бачили — у будь-якому разі, повідомте нам про це!

Окрім успішного виконання тестів, це має забезпечити 100% покриття тестами.

Виконання варіантів тестів¶

Виконати тести для декількох версій Python¶

За замовчуванням багато команд tox намагатимуться запустити набір тестів кілька разів — по одному разу для кожної версії Python, що підтримується BeeWare. Однак для цього кожна з цих версій Python має бути встановлена на вашому комп’ютері та доступна для процесу [виявлення]tox Python, що виконується (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). Загалом, якщо версія Python доступна через PATH, то tox має змогу її знайти та використовувати.

Виконати лише набір тестів¶

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

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Виконати підмножину тестів¶

За замовчуванням команда tox запускає всі тести з набору модульних тестів. Під час розробки нового тесту може бути корисно запустити лише цей один тест. Для цього можна передати будь-який специфікатор pytest як аргумент до tox. Ці шляхи до тестів є відносними до каталогу briefcase. Наприклад, щоб запустити лише тести з одного файлу, виконайте:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

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

Запустити набір тестів для конкретної версії Python¶

За замовчуванням tox -e py виконуватиметься з використанням того інтерпретатора, який на вашому комп’ютері розпізнається як python. Якщо у вас встановлено кілька версій Python і ви хочете протестувати конкретну версію з-поміж встановлених, ви можете вказати конкретну версію Python для використання. Наприклад, щоб запустити набір тестів на Python 3.10, виконайте:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

Підмножину тестів можна запустити, додавши -- та специфікацію тесту до командного рядка.

Запустити набір тестів без перевірки покриття (швидко)¶

За замовчуванням tox запускає набір тестів pytest у однопотоковому режимі. Ви можете пришвидшити виконання набору тестів, запустивши його паралельно. У цьому режимі файли покриття не створюються через складнощі з фіксацією покриття в запущених процесах. Щоб запустити окрему версію Python у «швидкому» режимі, виконайте:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

Підмножину тестів можна запустити, додавши -- та специфікацію тесту до командного рядка; конкретну версію Python можна використовувати, додавши версію до об’єкта тестування (наприклад, py310-fast для швидкого виконання на Python 3.10).

Покриття коду¶

BeeWare забезпечує 100% покриття гілок у своїй кодовій базі. Коли ви додаєте або змінюєте код у проєкті, вам необхідно додати тестовий код, щоб забезпечити покриття всіх внесених змін.

Однак BeeWare призначений для роботи на різних платформах, а також з різними версіями Python, тому повне покриття неможливо перевірити лише на одній платформі та в одній версії Python. Щоб врахувати це, у розділі tool.coverage.coverage_conditional_plugin.rules файлу pyproject.toml визначено кілька умовних правил покриття (наприклад, no-cover-if-is-windows можна використовувати для позначення блоку коду, який не виконуватиметься під час запуску набору тестів у Windows). Ці правила використовуються для виявлення фрагментів коду, які покриваються лише на певних платформах або у певних версіях Python.

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

Розуміння результатів охоплення¶

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

Назва    Звіти   Відділення «Місс» Частина «Бр»   Покриття   Відсутні
 ---------------------------------------------------
 ВСЬОГО    7540 0   1040 0  100,0 %

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

Якщо ви внесете зміни до коду, можливо, у покритті з’явиться прогалина. У такому випадку звіт про покриття покаже, які рядки не виконуються. Наприклад, припустимо, ми внесли зміну до some/interesting_file.py, додавши нову логіку. Звіт про покриття може виглядати приблизно так:

Ім'я Заяви   Міс Бранч БрПарт  Обкладинка   Відсутні
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1%   170, 302–307, 320–335
 -------------------------------------------------------------------------------
 ВСЬОГО 7540 1   1726 0  99,9%

Це свідчить про те, що рядок 170, рядки 302–307, а також перехід із рядка 320 до рядка 335 не виконуються набором тестів. Щоб відновити цей рівень покриття, вам потрібно додати нові тести (або змінити існуючий тест).

Звіт про сумісність з платформою-господарем та версією Python¶

Ви можете створити звіт про покриття для вашої платформи та версії Python. Наприклад, щоб запустити набір тестів і створити звіт про покриття для Python 3.10, виконайте наступну команду:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Звіт про охоплення для платформи-господаря¶

Якщо tox має доступ до всіх підтримуваних версій Python, то звіт про покриття для хост-платформи можна отримати, виконавши наступну команду:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Звіти про охоплення у форматі HTML¶

Звіт про покриття HTML можна створити, додавши -html до будь-якої назви середовища покриття tox, наприклад:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Справа не лише в написанні тестів!¶

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

Під час розробки тестів вам слід також перевіряти, чи є основний модуль послідовним у своїй внутрішній структурі. Якщо ви помітите назви методів, які не є внутрішньо узгодженими (наприклад, щось називається on_select в одному модулі, а в іншому — on_selected), або випадки, коли дані обробляються непослідовно, позначте це та повідомте нам, створивши квиток. Або, якщо ви впевнені, що знаєте, що потрібно зробити, створіть pull-запит, який виправляє виявлену вами проблему.

Як тільки все запрацює, ви зможете надіслати запит на злиття зі своїми змінами.