openQA pre vývojárov a správcov

KDE Linux používa openQA na automatické otestovanie každého systémového obrazu pred jeho zverejnením. openQA zavedie každý obraz vo virtuálnom stroji a overí, že sa dá úspešne nainštalovať, aktualizovať a používať.

openQA má vlastnú terminológiu: úloha je jedno spustenie testovacej sady nad obrazom, kým pracovník je stroj alebo kontajner, ktorý úlohu vykonáva. Dokumentácia openQA vysvetľuje tieto aj ďalšie pojmy vrátane testovacích modulov, skupín úloh, prostriedkov a webového rozhrania.

Ako testy fungujú

Testovací pracovník beží popri reťazci CI, takže môže použiť obrazy a virtuálne disky vytvorené pri zostavení bez toho, aby sa tie veľké súbory museli niekam nahrávať. Testy sa do virtuálneho stroja dostávajú cez systémové rozšírenie a komunikujú s ním cez SSH.

Testy pracovného prostredia využívajú prístupnostné API cez selenium-webdriver-at-spi, vďaka čomu dokážu s aplikáciami pracovať a overovať ich stav bez toho, aby sa spoliehali výhradne na porovnávanie snímok obrazovky. Sada tiež kontroluje zlyhané systémové služby, spadnuté procesy prostredia, problémy so sieťou a regresie v príkazoch KDE Linux.

Reťazec CI a postup správcu

V chránenej predvolenej vetve repozitára KDE Linux funguje reťazec takto:

  1. Úloha imaging zostaví, podpíše a pripraví obraz aj jeho kanál sysupdate na storage.kde.org.
  2. Úloha trigger-openqa spustí reťazec v os-autoinst-distri-kdelinux a odovzdá mu URL pripraveného obrazu a URL kanála sysupdate.
  3. Následný pipeline spúšťa postupy install a upgrade deklarované v tests/tests.toml, každý s bežnou aj šifrovanou inštaláciou.
  4. Úloha publish v pôvodnom reťazci beží až po úspešnom dokončení reťazca openQA. Už pripravený obraz povýši na verejne dostupný.

Zlyhanie openQA je tak podmienkou, ktorá zverejnenie obrazu zastaví. Začnite tým, že z úlohy trigger-openqa otvoríte nadväzujúci reťazec a z jeho záznamu CI potom zlyhanú úlohu openQA. Stránka úlohy zobrazuje testovacie moduly v poradí a umožňuje zistiť, či zlyhanie nastalo pri inštalácii, pri základných kontrolách nainštalovaného systému alebo pri aktualizácii.

Stiahnutie pripraveného obrazu

Odkaz uvedený za hlásením „In case of failure, inspect and download the image and sysupdate tree at…“ otvorí prehliadač úložiska pre testované zostavenie. Stiahnite si odtiaľ .iso, aby ste ho zaviedli ručne alebo odovzdali lokálnej inštancii openQA. Strom sysupdate obsahuje pripravené aktualizačné artefakty, ktoré používa test aktualizácie.

Skúmanie zlyhanej úlohy

Otvorte úlohu vo webovom rozhraní openQA a vyberte najprv zlyhaný modul. Odkaz na webové rozhranie sa objaví za hlásením „ test job is now running.“ Jeho podrobnosti obsahujú výsledok modulu, prípadné snímky obrazovky či video a diagnostický výstup. Na karte Logs & Assets si stiahnite alebo zobrazte autoinst-log.txt so záznamom pracovníka openQA a testovacieho jadra. Je to hlavný záznam samotnej úlohy.

Testy, ktoré spúšťajú príkazy na testovanom systéme, KDE Linux vykonáva v dočasných službách systemd a žurnál služby zaznamenáva ako diagnostický výstup vo výsledku testu. Výstup príkazu a žurnál nájdete v autoinst-log.txt. Stiahnuť si môžete aj súbor *kde-linux-collected-logs.tar.zst so záznamami, ktoré zozbieral nástroj collect-logs.

Spustenie testov lokálne

openQA môžete použiť na otestovanie lokálne zostaveného obrazu ešte pred odoslaním zmeny. Pri práci z forku mimo kde-linux/kde-linux je to nutné – jeho reťazec CI síce testovací obraz zostaví, ale reťazec openQA nespustí. Hodí sa to aj pri vývoji testov k vlastným zmenám.

Repozitár testov openQA pre KDE Linux obsahuje lokálnu zostavu s webovým rozhraním openQA aj pracovníkom. Vyžaduje Python 3.14, Podman a podman-compose, ktoré sú v KDE Linux súčasťou systému.

Naklonujte repozitár testov a do jeho koreňového adresára umiestnite obraz .iso KDE Linux, ktorý chcete otestovať. Ak tam žiadny obraz nie je, spúšťač testov stiahne najnovší verejne dostupný.

Spustite lokálnu zostavu z koreňa repozitára:

./qa-mock up

Keď je pripravená, otvorte http://localhost:1080 a pozrite si webové rozhranie openQA. Úlohy sa neodosielajú automaticky, preto otvorte shell v kontajneri a odošlite postup install. Príkazy flow, job a build-sysext spúšťajte v tomto kontajneri.

./qa-mock enter
./qa flow install

Ak chcete namiesto toho spustiť postup upgrade:

./qa flow upgrade

Pre šifrovanú inštaláciu zadajte FDE_INSTALL=1 ako nastavenie openQA. Prípona variantu odlišuje šifrované úlohy vo webovom rozhraní:

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

--var NAME=VALUE je možné opakovať, ale každá premenná musí byť deklarovaná v zozname variables vybraného postupu v tests/tests.toml.

Sada sanity-test používa virtuálny disk vytvorený pomocou install-system. Ak sa chcete sústrediť na konkrétne testy, upravte zoznam tests sady v tests/tests.toml alebo tam deklarujte ďalšiu sadu a postup. Jednotlivú sadu môžete spustiť aj pomocou ./qa job --name <suite>, pričom pamätajte na jej závislosti od diskov. Príkazy flow, job a build-sysext prijímajú --manifest-path <path> na použitie iného manifestu než tests/tests.toml. Cesty k testom v manifeste sú relatívne voči adresáru manifestu. Povinné možnosti zobrazíte pomocou ./qa job --help.

Napríklad zostavte systémové rozšírenie a spustite úlohu install-system so súborom .iso v adresári repozitára. ID zostavenia a variant nahraďte údajmi vášho obrazu:

./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

Keď skončíte, ukončite shell kontajnera a potom z hostiteľa zostavu zastavte a odstráňte jej lokálne zväzky.

./qa-mock down -v

./qa-mock odovzdáva argumenty do podman-compose. Napríklad pomocou ./qa-mock up -d spustíte zostavu na pozadí.

Testovanie aktualizácií medzi lokálnymi zostaveniami

Umiestnite základné ISO do koreňa testovacieho repozitára. Pri spúšťaní zostavy z hostiteľa nastavte KDE_LINUX_OUTPUT na adresár mkosi.output, ktorý obsahuje zostavenie, na ktoré chcete aktualizovať:

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

Vstúpte do kontajnera a spustite postup aktualizácie, pričom &lt;build-id&gt; nahraďte ID zostavenia vášho základného ISO:

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

Obe možnosti sa musia zadať spolu. Repozitár je pripojený v /casedir a vybraný adresár mkosi.output je pripojený iba na čítanie v /kde-linux-output. Najnovšie zostavenie v tomto adresári sa virtuálnemu stroju poskytne ako dočasný zdroj sysupdate a musí byť novšie ako základné ISO. Na testovanie šifrovanej inštalácie pridajte --var FDE_INSTALL=1 --flavor-suffix=-encrypted.

Deklarovanie sád a postupov

tests/tests.toml definuje distribúciu (name a distri), sady a postupy. Sada je usporiadaný zoznam testov spustených v jednej úlohe openQA. Jej action určuje, ako úloha používa virtuálny disk:

  • install zavedie živý obraz a vytvorí nainštalovaný disk.
  • upgrade zavedie nainštalovaný disk a nastaví DO_UPGRADE pre testy, ktoré vykonávajú aktualizáciu.
  • test zavedie nainštalovaný disk na overenie.

Postup spúšťa sady v deklarovanom poradí a odovzdáva nainštalovaný disk medzi úlohami. KDE Linux definuje tieto postupy:

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

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

Postup install nainštaluje a skontroluje testované zostavenie. Postup upgrade najprv nainštaluje starší obraz, aktualizuje ho na testované zostavenie a potom spustí základné testy. Pri pripravenom zostavení CI je základom najnovší zverejnený obraz. Bez --upgrade-from a --upgrade-to použije lokálne spustenie aktualizácie ako cieľ predvolene najnovšie verejné zostavenie, pričom použije staršie lokálne ISO, ak je k dispozícii, alebo stiahne predchádzajúci obraz.

Pred každou úlohou pracovník vygeneruje dočasný testovací adresár (CASEDIR) s plánom main.pm pre vybranú sadu. Testy sa spúšťajú v poradí manifestu vrátane opakovaných položiek. Na zmenu plánu upravte manifest.

Napísanie testu

Definície testov aj kód sú v os-autoinst-distri-kdelinux. Testovacie skripty pridajte do tests/ k súvisiacim testom a zaregistrujte ich v poli tests príslušnej sady v tests/tests.toml. Napríklad:

[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 },
]

Testy openqa sa vykonávajú na pracovníkovi a priamo používajú API openQA. Testy python a selenium sa vykonávajú na testovanom systéme, systémové rozšírenie automaticky zabalí ich skripty a pracovník vygeneruje obaly testov openQA, ktoré ich spúšťajú.

Typ testu si zvoľte podľa toho, čo overujete:

  • Pri nástrojoch príkazového riadka, službách, stave súborového systému alebo inom negrafickom správaní použite bežný unittest v Pythone.
  • Keď si správanie vyžaduje prácu s grafickou aplikáciou, použite Selenium cez selenium-webdriver-at-spi.

Bežné testy v Pythone

Vytvorte unittest v tests/, napríklad tests/kdelinux/system/example.py. Mal by overovať tvrdenia o testovanom systéme a zapisovať výsledky do súboru JUnit XML, ktorý sa automaticky zozbiera ako prostriedok openQA a ako správa pre GitLab CI.

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")

Pridajte položku do poľa tests príslušnej sady:

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

Vygenerovaný obal zozbiera výsledok JUnit a výstup príkazu, takže sa zlyhania objavia v úlohe openQA a v artefaktoch CI.

Grafické testy so Seleniom

Aj grafické testy sú triedy unittest v Pythone, na hľadanie prístupných prvkov rozhrania a prácu s nimi však používajú ovládač Appium/Selenium. Spúšťač Selenia zapne prístupnostnú infraštruktúru a ovládač naštartuje za vás.

Grafický test napríklad vytvorí ovládač pre svoju aplikáciu, pracuje s prístupnými prvkami a potom ovládač zavrie:

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")

Uložte skript napríklad ako tests/kdelinux/app/example.py a pridajte ho do príslušnej sady s type = "selenium". Pre desktopové aplikácie vyberte nainštalovaného testovacieho používateľa:

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

Počas vývoja spúšťajte postup obsahujúci vašu sadu lokálne.

Možnosti testov a vlastné obaly

Pri vygenerovaných obaloch pre testovaný systém môžu položky manifestu nastaviť user (root, live, installed alebo plasma_setup), timeout v sekundách (predvolene 90), artifacts ako zoznam ciest na zozbieranie a príznaky openQA fatal = true alebo always_run = true. Nastavením enabled = false ponecháte test deklarovaný, ale vylúčite ho z plánu.

Ak test na svoje spustenie potrebuje nejakú vlastnú orchestráciu, umiestnite obal vedľa jeho skriptu pre testovaný systém a odkážte naň pomocou override:

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

Tento vlastný obal zodpovedá za svoje príznaky, používateľa, časový limit a zbieranie artefaktov a musí odovzdať relatívnu cestu skriptu pre testovaný systém do CliTest.run_python() alebo CliTest.run_selenium(). Príklad nájdete v existujúcom collect_logs.openqa.py.

Viac o písaní testov v Seleniu nájdete v Automatizovanom testovaní s Appium a Testovaní rozhrania pomocou selenium-webdriver-at-spi.

Zistiť viac

Podrobnejší výklad testovacieho postupu a jeho implementácie nájdete v článku openQA Testing in KDE Linux. Testovacia infraštruktúra sa vyvíja v repozitári os-autoinst-distri-kdelinux.

Článok napísal pod licenciou CC-BY-4.0.