openQA для розробників і супровідників

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

openQA має певну специфічну термінологію: завдання (job) — це одне виконання набору тестів на зображенні, тоді як обробник (worker) — це машина або контейнер, який виконує це завдання. Документація openQA пояснює ці та інші концепції, включаючи тестові модулі, групи завдань, ресурси (resources) та веб-інтерфейс.

Як працюють тести

Обробник тестів працює паралельно з конвеєром неперервної інтеграції (CI), тому він може використовувати образи та віртуальні диски, створені під час збірки, не завантажуючи ці великі файли в інше місце. Тести надходять до віртуальної машини через системне розширення та взаємодіють з нею за допомогою SSH.

Тести стільниці використовують програмний інтерфейс доступності через selenium-webdriver-at-spi, що дозволяє їм взаємодіяти з програмами та перевіряти їхній стан, не покладаючись виключно на зіставлення знімків екрана. Пакет також перевіряє наявність збоїв системних служб, аварійно завершених процесів робочого столу, мережевих проблем та регресій у командах KDE Linux.

Робочий процес конвеєра неперервної інтеграції та супроводу

У захищеній типовій гілці основного сховища KDE Linux конвеєр працює наступним чином:

1. Завдання створення образів збирає, підписує та розміщує образ і його канал sysupdate на storage.kde.org.
2. Завдання trigger-openqa запускає конвеєр в os-autoinst-distri-kdelinux, передаючи йому адресу проміжного образу та адресу каналу sysupdate.
3. Конвеєр наступного етапу виконує процеси встановлення (install) та оновлення (upgrade), визначені у файлі tests/tests.toml, — як для звичайного, так і для зашифрованого встановлення.
4. Завдання оприлюднення основного потоку виконується лише після успішного завершення конвеєра openQA. Воно поширює вже підготовлений образ для публічного використання.

Це робить збій openQA шлюзом для оприлюднення образу. Спочатку відкрийте низхідний конвеєр із завдання trigger-openqa, а потім відкрийте завдання openQA, що завершилося невдачею, з його журналу неперервної інтеграції. Сторінка завдання показує тестові модулі за порядком та надає змогу визначити тип збою: у встановленні, тестах на працездатність встановленої системи чи шляху оновлення.

Отримання етапного образу

Посилання, надане після повідомлення журналу «У разі невдачі ви можете перевірити та завантажити образ .iso та дерево sysupdate за адресою…», відкриває браузер сховища для тестованої збірки. Вивантажте туди файл .iso, щоб завантажити його вручну, або передайте його до локального стосу openQA. Дерево sysupdate містить артефакти поетапного оновлення, що використовуються тестом оновлення.

Виявлення завдання, виконання якого призвело до помилки

Відкрийте завдання у вебінтерфейсі openQA і спочатку виберіть модуль, у якому сталася помилка. Посилання на вебінтерфейс з'явиться після повідомлення журналу «<назва> тестове завдання зараз виконується». Його детальна інформація містить результат модуля, знімки екрана або відео, де це можливо, та діагностичні дані. На вкладці Журнали та ресурси завантажте або перегляньте файл autoinst-log.txt для журналу обробника openQA та тестового рушія. Це основний журнал для самого завдання.

Тести, які виконують команди в тестованій системі, KDE Linux запускає у тимчасових службах systemd та записує журнал служби як діагностичне виведення результатів перевірки. Перегляньте autoinst-log.txt, щоб ознайомитися із виведеними командою даними та журналом. Ви також можете завантажити файл *kde-linux-collected-logs.tar.zst для ознайомлення зі журналом, отриманим за допомогою інструменту collect-logs.

Запуск тестів локально

Ви можете використовувати openQA для тестування локально зібраного образу перед надсиланням змін. Це потрібно під час роботи з відгалуженням поза kde-linux/kde-linux — його конвеєр неперервної інтеграції створює тестовий образ, але не запускає конвеєр openQA. Це також корисно під час розробки тестів для ваших власних змін.

Тестове сховище openQA для KDE Linux містить локальний стос, що містить як вебінтерфейс openQA, так і обробник. Для нього потрібні Python 3.14, Podman та podman-compose, які включені до KDE Linux.

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

Запустіть локальний стос з кореня сховища:

./qa-mock up

Як тільки все буде готово, відкрийте http://localhost:1080, щоб оглянути вебінтерфейс openQA. Завдання не процедуру встановлення. Виконайте команди flow, job і build-sysext всередині цього контейнера.

./qa-mock enter
./qa flow install

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

./qa flow upgrade

Для встановлення із шифруванням передайте FDE_INSTALL=1 як параметр openQA. Суфікс варіанта (flavor suffix) надає змогу розрізняти завдання із шифруванням у вебінтерфейсі:

./qa flow install --var FDE_INSTALL=1 --flavor-suffix=-encrypted
./qa flow upgrade --var FDE_INSTALL=1 --flavor-suffix=-encrypted

Параметр --var NAME=VALUE можна використовувати багаторазово, але кожна змінна має бути оголошена в списку variables вибраної процедури у файлі tests/tests.toml.

Набір тестів sanity-test використовує віртуальний диск, створений командою install-system. Щоб зосередитися на конкретних тестах, відредагуйте список tests у файлі tests/tests.toml або визначте там інший набір тестів і процедуру обробки (flow). Ви також можете запустити окремий набір тестів за допомогою команди ./qa job --name <комплекс>, враховуючи при цьому залежності від відповідного диска. Команди flow, job і build-sysext підтримують параметр --manifest-path <шлях>, що надає змогу використовувати інший файл маніфесту замість tests/tests.toml. Шляхи до тестів у маніфесті вказуються відносно каталогу, в якому розміщено цей маніфест. Віддайте команду ./qa job --help, щоб переглянути перелік обов'язкових параметрів.

Наприклад, зберіть системне розширення та запустіть завдання install-system, використовуючи файл .iso у каталозі сховища. Замініть ідентифікатор збірки та варіант на відповідні параметри вашого образу:

./qa build-sysext
./qa job \
    --live ./kde-linux_<build-id>.iso \
    --hdd kde-linux_<build-id>.qcow2 \
    --sysext ./openqa-sysext.img \
    --build <build-id> \
    --variant <variant> \
    --name install-system \
    --flavor live

Коли роботу буде завершено, вийдіть з командної оболонки контейнера, зупиніть стос і вилучіть його локальні томи з основної системи.

./qa-mock down -v

./qa-mock пропускає аргументи до podman-compose. Наприклад, скористайтеся ./qa-mock up -d для запуску стосу у фоновому режимі.

Тестування оновлень між локальними збираннями

Розмістіть базовий образ ISO у кореневому каталозі тестового сховища. Під час запуску стека з основної системи встановіть для змінної KDE_LINUX_OUTPUT значення шляху до каталогу mkosi.output, що містить збірку, до якої ви хочете оновитися:

KDE_LINUX_OUTPUT=~/Repositories/kde-linux/mkosi.output ./qa-mock up

Увійдіть у контейнер і запустіть процес оновлення, замінивши <build-id> на ідентифікатор збірки вашого базового образу ISO:

./qa-mock enter
./qa flow upgrade \
    --upgrade-from /casedir/kde-linux_<build-id>.iso \
    --upgrade-to /kde-linux-output

Обидва параметри необхідно вказувати разом. Сховище буде змонтовано до /casedir, а вибраний каталог mkosi.output буде змонтовано до /kde-linux-output у режимі «лише для читання». Найновіша збірка з цього каталогу надається віртуальній машині як тимчасове джерело для sysupdate; вона має бути новішою за базовий образу ISO. Щоб протестувати встановлення із шифруванням, додайте параметри --var FDE_INSTALL=1 --flavor-suffix=-encrypted.

Оголошення комплектів і шляхів

Файл tests/tests.toml визначає дистрибутив (параметри name та distri), набори тестів (suites) і процедури (flows). Набір тестів — це впорядкований перелік тестів, які буде виконано у межах одного завдання openQA. Параметр action визначає, як саме завдання використовує віртуальний диск:

• install завантажує портативний образ і створює диск для встановлення.
• upgrade завантажує систему з диска встановлення та встановлює змінну DO_UPGRADE для тестів, що виконують оновлення.
• test завантажує встановлений диск для перевірки.

Процедура обробки виконує набори в оголошеному порядку, передаючи встановлений диск між завданнями. KDE Linux визначає такі процедури:

[flows.install]
suites = ["install-system", "sanity-test"]
variables = ["FDE_INSTALL"]

[flows.upgrade]
suites = ["install-system", "upgrade-system", "sanity-test"]
variables = ["FDE_INSTALL"]

Процедура install встановлює та перевіряє тестову збірку. Процедура upgrade спочатку встановлює старіший образ, оновлює його до тестової збірки, а потім виконує перевірки працездатності. Для поетапної збірки системи інтеграції основою є останній опублікований образ. Якщо не вказано параметри --upgrade-from і --upgrade-to, локальне оновлення за замовчуванням орієнтується на останню загальнодоступну збірку як цільову версію, використовуючи наявний локальний образ ISO (за його наявності) або завантажуючи попередній образ.

Перед виконанням кожного завдання обробник створює тимчасовий тестовий каталог (CASEDIR) із планом виконання main.pm для вибраного набору тестів. Тести виконуються в порядку, визначеному в маніфесті, зокрема і ті, що вказані в ньому кілька разів. Щоб змінити план виконання, відредагуйте маніфест.

Написання тесту

Визначення тестів і код розміщено у сховищі os-autoinst-distri-kdelinux. Додайте тестові скрипти до каталогу tests/ (поруч із пов'язаними тестами) і зареєструйте їх у масиві tests відповідного набору тестів у файлі tests/tests.toml. Приклад:

[suites.example]
action = "test"
tests = [
    { path = "common/bootup.py", type = "openqa" },
    { path = "common/basic_test.py", type = "python" },
    { path = "kdelinux/app/firefox.py", type = "selenium", user = "installed", timeout = 180 },
]

Тести openqa виконуються на обробнику і безпосередньо використовують програмний інтерфейс openQA. Тести python і selenium виконуються на системі, що тестується; системне розширення автоматично пакує їхні скрипти, а обробник створює оболонки тестів openQA для їхнього запуску.

Виберіть тип тестування на основі того, що ви перевіряєте:

• Скористайтеся звичайним unittest Python для інструментів командного рядка, служб, стану файлової системи або інших речей, які не пов'язано із графікою.
• Скористайтеся Selenium за допомогою selenium-webdriver-at-spi, якщо потрібне взаємодія із програмою з графічним інтерфейсом.

Звичайні тести Python

Створіть unittest у tests/, наприклад tests/kdelinux/system/example.py. Він має виконати перевірки тестованої системи і записати свої результати у файл XML JUnit, який буде автоматично зібраний як ресурс openQA та звіт неперервної інтеграції GitLab.

import unittest
from lib.sut import openqa_junit_xml

class ExampleTests(unittest.TestCase):
    def test_expected_behaviour(self):
        self.assertTrue(True)

if __name__ == "__main__":
    openqa_junit_xml.run(ExampleTests, "example")

Додавання запису до масиву tests відповідного набору тестів:

{ path = "kdelinux/system/example.py", type = "python" },

Створена обгортка збирає результат JUnit та виведені командою дані, щоб помилки було показано у завданні openQA та результатах роботи системи неперервної інтеграції.

Тестування графіки з Selenium

Тести графіки також є класами Python unittest, але використовують драйвер Appium/Selenium для пошуку та взаємодії з доступними елементами інтерфейсу користувача. Засіб запуску Selenium активує інфраструктуру доступності і запускає драйвер.

Наприклад, тест графіки створює драйвер для своєї програми, взаємодіє з доступними елементами і після цього закриває драйвер:

import unittest
from appium import webdriver
from appium.options.common.base import AppiumOptions
from appium.webdriver.common.appiumby import AppiumBy
from lib.sut import openqa_junit_xml

class ExampleTests(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        options = AppiumOptions()
        options.set_capability("app", "org.kde.example.desktop")
        cls.driver = webdriver.Remote("http://127.0.0.1:4723", options=options)

    @classmethod
    def tearDownClass(cls):
        cls.driver.quit()

    def test_expected_behaviour(self):
        self.driver.find_element(AppiumBy.ACCESSIBILITY_ID, "example-control").click()

if __name__ == "__main__":
    openqa_junit_xml.run(ExampleTests, "example")

Збережіть скрипт, наприклад, як tests/kdelinux/app/example.py і додайте його до відповідного набору тестів із параметром type = "selenium". Виберіть встановленого тестового користувача для стільничних програм:

{ path = "kdelinux/app/example.py", type = "selenium", user = "installed", timeout = 180 },

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

Перевірка параметрів та нетипових обгорток

Для створених обгорток системи тестування модулів у записах маніфесту можна вказати користувача (root, live, installed або plasma_setup), час очікування в секундах (типово — 90), artifacts (як список шляхів для збирання), а також прапорці openQA fatal = true або always_run = true. Встановіть enabled = false, щоб залишити тест оголошеним, але виключити його з розкладу.

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

{ path = "kdelinux/system/collect_logs.py", type = "selenium", override = "kdelinux/system/collect_logs.openqa.py" },

Ця нетипова обгортка відповідає за власні прапорці, користувача, час очікування і збір результатів; вона повинна передавати відносний шлях до скрипту SUT у метод CliTest.run_python() або CliTest.run_selenium(). Приклад див. у наявному файлі collect_logs.openqa.py.

Щоб дізнатися більше про написання тестів Selenium, ознайомтеся з даними щодо автоматичного тестування Appium та тестуванням графіки за допомогою selenium-webdriver-at-spi.

Додаткові відомості

Докладніші пояснення щодо процесу тестування та його реалізації наведено на сторінці Тестування openQA в KDE Linux. Розробка інфраструктури тестування виконується у сховищі os-autoinst-distri-kdelinux.

Статтю надіслано Thomas Duckworth, умови ліцензування — CC-BY-4.0.