openQA pro vývojáře a správce

KDE Linux využívá openQA k automatickému testování každého systémového obrazu před jeho zveřejněním. openQA spustí každý obraz ve virtuálním stroji a ověří, zda je možné jej úspěšně nainstalovat, aktualizovat a používat.

openQA používá určitou specifickou terminologii: úloha (job) představuje jedno spuštění testovací sady na obrazu, zatímco stroj (worker) je stroj nebo kontejner, na kterém se úloha spouští. Dokumentace openQA vysvětluje tyto a další pojmy, včetně testovacích modulů, skupin úloh, prostředků a webového uživatelského rozhraní.

Jak testy fungují

Testovací proces běží souběžně s CI pipeline, takže může využívat obrazy a virtuální disky vytvořené v rámci sestavení, aniž by bylo nutné tyto velké soubory nahrávat někam jinam. Testy jsou do virtuálního stroje dodávány prostřednictvím systémového rozšíření a komunikují s ním přes SSH.

Testy pro stolní počítače využívají rozhraní API pro přístupnost prostřednictvím selenium-webdriver-at-spi, což jim umožňuje komunikovat s aplikacemi a kontrolovat jejich stav, aniž by se spoléhaly výhradně na porovnávání snímků obrazovky. Tato sada testů také kontroluje selhání systémových služeb, havárie procesů na ploše, problémy se sítí a regrese v příkazech KDE Linux.

CI pipeline a pracovní postup správce

Na chráněné výchozí větvi upstreamového repozitáře KDE Linux funguje tento proces následovně:

  1. Úloha imaging sestaví, podepíše a připraví obraz a jeho kanál sysupdate na serveru storage.kde.org.
  2. Úloha trigger-openqa spustí pipeline v os-autoinst-distri-kdelinux a předá jí URL připraveného obrazu a URL kanálu sysupdate.
  3. Následující část procesu spouští proudy install a upgrade deklarované v souboru tests/tests.toml, přičemž každý z nich zahrnuje instalaci v nezakódované i zakódované podobě.
  4. Úloha publish se spustí až po úspěšném dokončení pipeline openQA. Tato úloha zpřístupňuje již připravený obraz pro veřejnost.

Díky tomu se selhání openQA stává bránou pro publikování obrazu. Nejprve otevřete navazující pipeline z úlohy trigger-openqa a poté otevřete selhávající úlohu openQA z jejího protokolu CI. Stránka úlohy zobrazuje testovací moduly v pořadí a umožňuje vám zjistit, zda k selhání došlo při instalaci, při testech správnosti nainstalovaného systému nebo při aktualizaci.

Stažení připraveného obrazu

Odkaz uvedený za zprávou záznamu "V případě selhání zkontrolujte a stáhněte obraz a strom sysupdate na…" otevře prohlížeč úložiště pro testovanou sestavu. Stáhněte si odtud soubor .iso, abyste jej mohli spustit ručně, nebo jej předávejte lokálnímu stacku openQA. Strom sysupdate obsahuje připravené aktualizační artefakty používané při testu aktualizace.

Prošetření neúspěšné úlohy

Otevřete úlohu ve webovém rozhraní openQA a nejprve vyberte modul, u kterého došlo k selhání. Odkaz na webové rozhraní se zobrazí za záznamem " testovací úloha právě běží.". Mezi podrobnosti patří výsledek modulu, případně snímky obrazovky nebo video a diagnostický výstup. Na kartě Logs & Assets si stáhněte nebo prohlédněte soubor autoinst-log.txt s protokoly stroje openQA a testovacího modulu. Jedná se o hlavní protokol samotné úlohy.

U testů, které provádějí příkazy na testovaném systému, je KDE Linux spouští v dočasných službách systemd a zaznamenává protokol služby jako diagnostický výstup do výsledku testu. Výstup příkazů a protokol najdete v souboru autoinst-log.txt. Můžete si také stáhnout soubor *kde-linux-collected-logs.tar.zst, který obsahuje protokoly zaznamenané nástrojem collect-logs.

Spuštění testů lokálně

Před odesláním změny můžete pomocí openQA otestovat obraz sestavený lokálně. To je nutné při práci s forkem mimo repozitář kde-linux/kde-linux – jeho CI pipeline sice sestaví testovací obraz, ale nespustí pipeline openQA. Je to užitečné také při vývoji testů pro vaše vlastní změny.

Testovací repozitář KDE Linux openQA obsahuje lokální stack, který zahrnuje jak webové uživatelské rozhraní openQA, tak pracovní proces. Vyžaduje Python 3.14, Podman a podman-compose, které jsou součástí KDE Linuxu.

Zkopírujte testovací repozitář a do jeho kořenového adresáře umístěte obraz KDE Linux .iso, který chcete otestovat. Pokud tam žádný obraz není, nástroj pro spouštění testů místo toho stáhne nejnovější veřejně dostupný obraz.

Spustit lokální stack z kořenového adresáře repozitáře:

./qa-mock up

Jakmile bude vše připraveno, otevřete stránku http://localhost:1080, abyste si prohlédli webové rozhraní openQA. Úlohy se neodesílají automaticky, proto v kontejneru otevřete shell a odešlete proud install. V tomto kontejneru spusťte příkazy flow, job a build-sysext.

./qa-mock enter
./qa flow install

Chcete-li místo toho spustit proud upgrade:

./qa flow upgrade

Chcete-li provést šifrovanou instalaci, zadejte jako nastavení openQA hodnotu FDE_INSTALL=1. Přípona varianty slouží k rozlišení šifrovaných úloh ve webovém uživatelském rozhraní:

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

--var NAME=VALUE lze opakovat, ale každá proměnná musí být deklarována v seznamu variables vybraného proudu v souboru tests/tests.toml.

Sada testů sanity-test využívá virtuální disk vytvořený příkazem install-system. Chcete-li se zaměřit na konkrétní testy, upravte seznam tests této sady v souboru tests/tests.toml nebo tam definujte jinou sadu a proud. Jednotlivé sady testů můžete spouštět také příkazem ./qa job --name <suite>, přičemž je třeba brát v úvahu jejich závislosti na disku. Příkazy flow, job a build-sysext podporují volbu --manifest-path <path> pro použití jiného manifestu než tests/tests.toml. Cesty k testům v manifestu jsou relativní vůči adresáři tohoto manifestu. Zadejte příkaz ./qa job --help pro zobrazení požadovaných voleb.

Například sestavte systémové rozšíření a spusťte úlohu install-system s souborem .iso v adresáři repozitáře. Nahraďte ID sestavení a variantu hodnotami odpovídajícími vašemu 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

Až budete hotovi, ukončete shell kontejneru, poté zastavte stack a odeberte jeho lokální svazky z hostitele.

./qa-mock down -v

Příkaz ./qa-mock předává argumenty příkazu podman-compose. Chcete-li například spustit stack na pozadí, použijte příkaz ./qa-mock up -d.

Testování aktualizací mezi lokálními sestaveními

Umístěte základní ISO do kořenového adresáře testovacího repozitáře. Při spouštění stacku z hostitelského počítače nastavte proměnnou KDE_LINUX_OUTPUT na adresář mkosi.output, který obsahuje sestavení, na které chcete provést aktualizaci:

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

Přejděte do kontejneru a spusťte proces aktualizace, přičemž nahraďte &lt;build-id&gt; identifikátorem sestavení vašeho základního ISO:

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

Obě možnosti je nutné zadat společně. Repozitář je připojen do adresáře /casedir a vybraný adresář mkosi.output je připojen jako jen pro čtení do adresáře /kde-linux-output. Nejnovější sestavení v tomto adresáři je poskytováno virtuálnímu stroji jako dočasný zdroj sysupdate a musí být novější než základní ISO. Pro otestování šifrované instalace přidejte --var FDE_INSTALL=1 --flavor-suffix=-encrypted.

Definice sad a proudů

Soubor tests/tests.toml definuje distribuci (name a distri), sady testů a proudy. Sada testů je uspořádaný seznam testů spouštěných v rámci jedné úlohy OpenQA. Její parametr action určuje, jakým způsobem úloha využívá virtuální disk:

  • Příkaz install spustí živý obraz a vytvoří nainstalovaný disk.
  • Příkaz upgrade spustí systém z nainstalovaného disku a nastaví proměnnou DO_UPGRADE pro testy, které provádějí aktualizaci.
  • Příkaz test spustí nainstalovaný disk za účelem ověření.

Průběh spouští sady v zadaném pořadí a mezi jednotlivými úlohami předává nainstalovaný disk. KDE Linux definuje tyto průběhy:

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

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

Proud install nainstaluje a zkontroluje testovanou verzi. Proud upgrade nejprve nainstaluje starší obraz, aktualizuje jej na testovanou verzi a poté spustí základní testy. U postupné CI sestavy je základem nejnovější zveřejněný obraz. Bez parametrů --upgrade-from a --upgrade-to bude místní aktualizace standardně směřovat k nejnovější veřejné sestavě, přičemž použije starší místní ISO, pokud je k dispozici, nebo stáhne předchozí obraz.

Před každým úkolem worker vytvoří dočasný testovací adresář (CASEDIR) s plánem main.pm pro vybranou sadu testů. Testy se spouštějí v pořadí uvedeném v seznamu, včetně opakovaných položek. Chcete-li změnit plán, upravte tento seznam.

Napsání testu

Definice testů a kód se nacházejí v repozitáři os-autoinst-distri-kdelinux. Testovací skripty přidejte do adresáře tests/ společně s příslušnými testy a zaregistrujte je v poli tests příslušné sady v souboru tests/tests.toml. Napří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 se spouštějí na workeru a přímo využívají rozhraní API openQA. Testy python a selenium se spouštějí na testovaném systému; systémové rozšíření automaticky zabalí jejich skripty a pracovní stanice vygeneruje testovací wrappery openQA, které je spustí.

Vyberte typ testu podle toho, co chcete zkontrolovat:

  • Pro nástroje příkazového řádku, služby, stav souborového systému nebo jiné negrafické chování použijte standardní moduly Pythonu unittest.
  • Pokud daná úloha vyžaduje interakci s grafickou aplikací, použijte Selenium prostřednictvím selenium-webdriver-at-spi.

Běžné testy v jazyce Python

Vytvořte unittest v adresáři tests/, například tests/kdelinux/system/example.py. Test by měl provádět ověření testovaného systému a zapisovat výsledky do souboru JUnit XML, který bude automaticky shromážděn jako asset openQA a zpráva 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")

Přidejte položku do pole tests příslušné sady testů:

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

Vygenerovaný wrapper shromažďuje výsledky JUnit a výstup příkazů tak, aby se selhání zobrazila v úloze openQA a v artefaktech CI.

Grafické testy pomocí Selenium

Grafické testy rovněž využívají třídy Pythonu unittest, avšak k vyhledávání přístupných prvků uživatelského rozhraní a interakci s nimi používají ovladač Appium/Selenium. Spouštěč Selenium aktivuje infrastrukturu pro přístupnost a ovladač za vás spustí.

Grafický test například vytvoří ovladač pro danou aplikaci, provede interakci s přístupnými prvky a poté ovladač uzavře:

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

Skript uložte například jako tests/kdelinux/app/example.py a přidejte jej do příslušné sady testů s parametrem type = "selenium". Vyberte nainstalovaného testovacího uživatele pro desktopové aplikace:

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

Během vývoje spusťte lokálně proud obsahující vaši sadu testů.

Možnosti testování a vlastní wrappery

U generovaných wrapperů SUT lze v položkách manifestu nastavit user (root, live, installed nebo plasma_setup), timeout v sekundách (výchozí hodnota je 90), artifacts jako seznam cest k shromáždění a příznaky openQA fatal = true nebo always_run = true. Nastavte enabled = false, chcete-li test ponechat deklarovaný, ale vyloučit jej z plánu.

Pokud test k provedení vyžaduje nějakou formu vlastní koordinace, vložte vedle skriptu SUT wrapper a odkažte na něj pomocí override:

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

Tento vlastní wrapper je zodpovědný za své příznaky, uživatele, časový limit a sběr artefaktů a musí předat relativní cestu ke skriptu SUT do funkce CliTest.run_python() nebo CliTest.run_selenium(). Jako příklad si prohlédněte stávající soubor collect_logs.openqa.py.

Další informace o psaní testů v Seleniu najdete v článcích Automatizované testování s Appium a Testování grafického uživatelského rozhraní pomocí selenium-webdriver-at-spi.

Zjistit více

Podrobnější vysvětlení průběhu testování a jeho provádění najdete v článku Testování openQA v KDE Linux. Testovací infrastruktura je vyvíjena v repozitáři os-autoinst-distri-kdelinux.

Tento přípěvek napsal pod licencí CC-BY-4.0.